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

package/node_modules/@openclaw/fs-safe/dist/types.d.ts

@@ -1,6 +1,9 @@
+import type { ExactFileIdentity } from "./exact-identity.js";
 export type FastPathMode = "auto" | "never" | "require";
 export type SafeEncoding = BufferEncoding | null;
 export type PathStat = {
+    /** Exact companion for identity checks; numeric fields are legacy metadata. */
+    exactIdentity?: ExactFileIdentity;
     dev: number;
     gid: number;
     ino: number;
@@ -20,3 +23,4 @@ export type BasePathOptions = {
     rootDir: string;
     relativePath: string;
 };
+export type { ExactFileIdentity } from "./exact-identity.js";

package/node_modules/@openclaw/fs-safe/dist/watch-native.js

@@ -5,9 +5,9 @@ import { watchStreamPaths } from "./watch-stream.js";
 export function watchBinding(mode) {
     if (mode === "poll")
         return;
-    const binding = getNativeBinding(); // Preserves require + missing-addon failure.
+    const binding = getNativeBinding("watchRegister", "watchAdd", "watchUnregister", ...(process.platform === "darwin" ? ["watchConfigure", "watchEntries"] : []));
     // Bun TSFN teardown remains unqualified; guarded native scans remain usable.
-    if (binding?.watchRegister && (process.platform !== "darwin" || (binding.watchConfigure && binding.watchEntries)) && !process.versions.bun && !process.versions.deno && ["linux", "darwin", "win32"].includes(process.platform))
+    if (binding && !process.versions.bun && !process.versions.deno && ["linux", "darwin", "win32"].includes(process.platform))
         return binding;
     if (mode === "events" || getFsSafeNativeConfig().mode === "require") {
         throw new FsSafeError("helper-unavailable", "native watch events are unavailable", { details: { operation: "watch" } });

package/node_modules/@openclaw/fs-safe/dist/windows-appcontainer.d.ts

@@ -0,0 +1,5 @@
+import { type NativeBinding } from "./native.js";
+/** The native owner caches immutable primary-token membership across Workers. */
+export declare function isWindowsAppContainer(binding: NativeBinding): boolean | undefined;
+export declare function assertWindowsHelperAllowed(): void;
+export declare function assertWindowsAclRemediationAllowed(): void;

package/node_modules/@openclaw/fs-safe/dist/windows-appcontainer.js

@@ -0,0 +1,39 @@
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+/** The native owner caches immutable primary-token membership across Workers. */
+export function isWindowsAppContainer(binding) {
+    if (!binding.isWindowsAppContainer)
+        return undefined;
+    try {
+        const membership = binding.isWindowsAppContainer();
+        if (typeof membership !== "boolean")
+            throw new Error("Invalid AppContainer membership");
+        return membership;
+    }
+    catch (cause) {
+        throw new FsSafeError("permission-unverified", "Windows process token membership could not be verified", { cause });
+    }
+}
+export function assertWindowsHelperAllowed() {
+    if (process.platform !== "win32")
+        return;
+    const binding = getNativeBinding();
+    if (binding && isWindowsAppContainer(binding)) {
+        // Current libuv can hang while creating child-process pipes in a lowbox.
+        throw new FsSafeError("helper-unavailable", "External Windows security helpers are unavailable inside an AppContainer");
+    }
+}
+export function assertWindowsAclRemediationAllowed() {
+    if (process.platform !== "win32")
+        return;
+    let binding;
+    try {
+        binding = getNativeBinding();
+    }
+    catch {
+        return;
+    } // Command formatting remains available without an addon.
+    if (binding && isWindowsAppContainer(binding)) {
+        throw new FsSafeError("helper-unavailable", "Windows ACL reset commands are unavailable inside an AppContainer");
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/windows-owner.d.ts

@@ -6,6 +6,7 @@ export type WindowsOwnerExec = (command: string, args: string[]) => Promise<{
 export type WindowsOwnerSummary = Omit<PermissionFailureFields & {
     sid?: string;
     currentUserSid?: string;
+    currentAppContainerSid?: string;
     daclPresent?: boolean;
     aces?: WindowsOwnerAce[];
     aclError?: string;

package/node_modules/@openclaw/fs-safe/dist/windows-owner.js

@@ -1,38 +1,16 @@
-import { formatCaughtPermissionFailure, getPermissionCommandFailure, } from "./permission-exec.js";
-import { resolveWindowsSystemCommand } from "./windows-command.js";
+import { formatCaughtPermissionFailure, getPermissionCommandFailure, executePermissionCommand, } from "./permission-exec.js";
+import { assertWindowsHelperAllowed } from "./windows-appcontainer.js";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { windowsSecurityHelperPath } from "./windows-security-helper.js";
 import { hasWindowsPathAlias } from "./windows-path-alias.js";
+import { APP_CONTAINER_SID_RE } from "./windows-security-facts.js";
 const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;
 const TRUSTED_OWNER_SIDS = new Set(["s-1-5-18", "s-1-5-32-544"]);
 function normalizeSid(value) {
     const normalized = value.trim().toLowerCase();
     return normalized.startsWith("*") ? normalized.slice(1) : normalized;
 }
-function encodePowerShellCommand(source) {
-    return Buffer.from(source, "utf16le").toString("base64");
-}
-function windowsOwnerQueryCommand(targetPath) {
-    const encodedPath = Buffer.from(targetPath, "utf8").toString("base64");
-    return [
-        "$ErrorActionPreference='Stop'",
-        "$env:PSModulePath=[IO.Path]::Combine($PSHOME,'Modules')",
-        `$p=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}'))`,
-        "$sections=[System.Security.AccessControl.AccessControlSections]::Access -bor [System.Security.AccessControl.AccessControlSections]::Owner",
-        "$acl=if([IO.Directory]::Exists($p)){[IO.Directory]::GetAccessControl($p,$sections)}else{[IO.File]::GetAccessControl($p,$sections)}",
-        "$ownerSid=$acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value",
-        "$currentSid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value",
-        "$root=[IO.Path]::GetPathRoot($p)",
-        "$extendedDrive=$p.Length -ge 7 -and $p.StartsWith('\\\\?\\') -and [char]::IsLetter($p[4]) -and $p[5] -eq ':' -and $p[6] -eq '\\'",
-        "$driveRoot=if($extendedDrive){$p.Substring(4,3)}else{$root}",
-        "$namespacePath=$p.StartsWith('\\\\')",
-        "$remote=($namespacePath -and -not $extendedDrive) -or ([IO.DriveInfo]::new($driveRoot).DriveType -eq [IO.DriveType]::Network)",
-        // Emit only ASCII SID and numeric facts: console encodings can replace both
-        // Unicode pathnames and account names before JavaScript receives the bytes.
-        "$raw=[System.Security.AccessControl.RawSecurityDescriptor]::new($acl.GetSecurityDescriptorBinaryForm(),0)",
-        "$dacl=$raw.DiscretionaryAcl;$complete=$true",
-        "$aces=@(foreach($ace in $dacl){if($ace -isnot [System.Security.AccessControl.CommonAce] -or $ace.IsCallback -or [int]$ace.AceType -notin @(0,1)){$complete=$false;continue};@{sid=$ace.SecurityIdentifier.Value;mask=([long]$ace.AccessMask -band 4294967295);deny=([int]$ace.AceType -eq 1);inheritOnly=([int]$ace.AceFlags -band 8) -ne 0}})",
-        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;daclPresent=($null -ne $dacl);aces=$aces;complete=$complete;remote=$remote}|Microsoft.PowerShell.Utility\\ConvertTo-Json -Depth 4 -Compress",
-    ].join(";");
-}
 function parseWindowsAclFacts(parsed) {
     if (parsed.complete !== true || typeof parsed.daclPresent !== "boolean" || !Array.isArray(parsed.aces)) {
         return { aclError: "Windows ACL query returned incomplete descriptor data" };
@@ -53,18 +31,24 @@ export async function inspectWindowsOwner(params) {
         const error = new Error("Path uses a Windows filesystem namespace alias");
         return { error: String(error), errorCause: error };
     }
+    if (process.platform === "win32" && params.exec === executePermissionCommand) {
+        assertWindowsHelperAllowed();
+        // Refuse a missing sandbox canonicalizer before starting a helper process.
+        // Other pathname failures retain the named-query reporting contract below.
+        try {
+            realpathSync.native(params.targetPath);
+        }
+        catch (error) {
+            if (error instanceof FsSafeError && error.code === "helper-unavailable")
+                throw error;
+        }
+    }
     let command = "";
     let startedAt = performance.now();
     try {
-        command = resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`, params.env);
+        command = windowsSecurityHelperPath();
         startedAt = performance.now();
-        const { stdout } = await params.exec(command, [
-            "-NoLogo",
-            "-NoProfile",
-            "-NonInteractive",
-            "-EncodedCommand",
-            encodePowerShellCommand(windowsOwnerQueryCommand(params.targetPath)),
-        ]);
+        const { stdout } = await params.exec(command, ["owner", params.targetPath]);
         const value = JSON.parse(stdout.trim());
         if (!value || typeof value !== "object" || Array.isArray(value)) {
             return { error: "Windows owner query returned invalid SID data" };
@@ -79,6 +63,10 @@ export async function inspectWindowsOwner(params) {
         if (!ownerSid || !currentUserSid) {
             return { error: "Windows owner query returned invalid SID data" };
         }
+        if (parsed.currentAppContainerSid != null &&
+            (typeof parsed.currentAppContainerSid !== "string" || !APP_CONTAINER_SID_RE.test(parsed.currentAppContainerSid.toLowerCase()))) {
+            return { error: "Windows owner query returned invalid AppContainer SID data" };
+        }
         const remote = parsed.remote;
         if (typeof remote !== "boolean") {
             return { error: "Windows owner query returned invalid locality data" };
@@ -86,6 +74,7 @@ export async function inspectWindowsOwner(params) {
         return {
             sid: ownerSid,
             currentUserSid,
+            ...(typeof parsed.currentAppContainerSid === "string" ? { currentAppContainerSid: normalizeSid(parsed.currentAppContainerSid) } : {}),
             ...parseWindowsAclFacts(parsed),
             trusted: !remote && (ownerSid === currentUserSid || TRUSTED_OWNER_SIDS.has(ownerSid)),
         };

package/node_modules/@openclaw/fs-safe/dist/windows-security-command.js

@@ -1,9 +1,10 @@
+import { assertWindowsHelperAllowed } from "./windows-appcontainer.js";
 import { spawn, spawnSync } from "node:child_process";
 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 { parseWindowsOwnerAndDaclFacts, parseWindowsSecurityCommandFacts, unverified } from "./windows-security-facts.js";
+import { windowsSecurityHelperPath, explainWindowsSecurityHelperFailure } from "./windows-security-helper.js";
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const TERMINATION_GRACE_MS = 1_000;
 const FULL_IDENTITY = /^[0-9a-f]{16}:[0-9a-f]{32}$/;
@@ -35,10 +36,10 @@ function command(operation, params) {
         (!Number.isInteger(params.expectedLinks) || params.expectedLinks < 1 || params.expectedLinks > 0xffff_ffff)) {
         throw new TypeError("Windows security operation requires a positive uint32 link count");
     }
-    const script = fileURLToPath(new URL("./windows-security-bridge.ps1", import.meta.url));
+    const helper = windowsSecurityHelperPath();
     return {
-        file: resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`),
-        args: ["-NoLogo", "-NoProfile", "-NonInteractive", "-File", script, "-Operation", operation],
+        file: helper,
+        args: [operation],
         // Preserve Windows UTF-16 spelling and leave long paths out of the bounded
         // command line. This overrides any inherited value only in this child.
         env: {
@@ -85,14 +86,28 @@ function parseReplyValue(stdout, operation) {
         if (typeof response.code !== "string" || !codes.has(response.code) || typeof response.message !== "string") {
             unverified("Windows security command returned an invalid failure");
         }
-        throw Object.assign(new Error(response.message), { code: response.code });
+        if (response.errno !== undefined &&
+            (typeof response.errno !== "number" || !Number.isInteger(response.errno) || response.errno < 0 || response.errno > 0xffff_ffff)) {
+            unverified("Windows security command returned an invalid native error number");
+        }
+        const failure = Object.assign(new Error(response.message), { code: response.code });
+        if (response.errno !== undefined) {
+            Object.defineProperty(failure, "errno", { value: response.errno, enumerable: true, configurable: true, writable: true });
+        }
+        throw failure;
     }
     if (operation === "create" && (!record(response.result) || response.result.created !== true || !isFullIdentity(response.result.identity))) {
         unverified("Windows security command did not verify private-directory creation");
     }
     return response.result;
 }
+function explainHelperFailure(error, file) {
+    if (file.endsWith("windows-security-helper.exe")) {
+        explainWindowsSecurityHelperFailure(error);
+    }
+}
 function executeSync(operation, params) {
+    assertWindowsHelperAllowed();
     const { file, args, env } = command(operation, params);
     const startedAt = performance.now();
     const result = spawnSync(file, args, {
@@ -107,6 +122,7 @@ function executeSync(operation, params) {
             killed: result.error?.code === "ETIMEDOUT",
             ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
         });
+        explainHelperFailure(error, file);
         if (operation === "create")
             Object.assign(error, { creationOutcome: "unconfirmed" });
         throw error;
@@ -120,6 +136,8 @@ class WindowsSecurityCommandError extends PermissionCommandError {
     constructor(file, durationMs, receipt, timedOut, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
         super(file, durationMs, receipt, timeoutMs);
         this.timedOut = timedOut;
+        if (!timedOut)
+            explainHelperFailure(this, file);
         this.creationOutcome = receipt.creationOutcome;
         this.processExitConfirmed = receipt.processExitConfirmed;
         if (timedOut)
@@ -162,6 +180,7 @@ export function hasUnsettledWindowsSecurityCommand(error) {
 }
 function ignoreLateError() { }
 async function execute(operation, params, request) {
+    assertWindowsHelperAllowed();
     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();

package/node_modules/@openclaw/fs-safe/dist/windows-security-facts.d.ts

@@ -1,5 +1,6 @@
 import type { NativeWindowsSecurityFacts } from "./native-binding.js";
-export type DescriptorFacts = Pick<NativeWindowsSecurityFacts, "ownerSid" | "currentUserSid" | "daclPresent" | "isLocal" | "aceListComplete" | "unsupportedAceTypes" | "aces">;
+export declare const APP_CONTAINER_SID_RE: RegExp;
+export type DescriptorFacts = Pick<NativeWindowsSecurityFacts, "ownerSid" | "currentUserSid" | "currentAppContainerSid" | "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;

package/node_modules/@openclaw/fs-safe/dist/windows-security-facts.js

@@ -1,5 +1,6 @@
 import { FsSafeError } from "./errors.js";
 const SID_RE = /^s-\d+-\d+(?:-\d+)+$/;
+export const APP_CONTAINER_SID_RE = /^s-1-15-2(?:-\d+){7,}$/;
 const SYSTEM_SID = "s-1-5-18";
 const ADMINISTRATORS_SID = "s-1-5-32-544";
 const WORLD_SIDS = new Set([
@@ -34,6 +35,7 @@ function validateAce(value, allowUnknownFlags) {
 function validateDescriptor(value, allowUnknownFlags) {
     if (!record(value) || typeof value.ownerSid !== "string" || !SID_RE.test(value.ownerSid) ||
         typeof value.currentUserSid !== "string" || !SID_RE.test(value.currentUserSid) ||
+        (value.currentAppContainerSid != null && (typeof value.currentAppContainerSid !== "string" || !APP_CONTAINER_SID_RE.test(value.currentAppContainerSid))) ||
         typeof value.daclPresent !== "boolean" || typeof value.isLocal !== "boolean" ||
         typeof value.aceListComplete !== "boolean" || !Array.isArray(value.unsupportedAceTypes) ||
         !value.unsupportedAceTypes.every(uint32) || !Array.isArray(value.aces) ||
@@ -59,6 +61,8 @@ function summarize(facts) {
     let groupReadable = false;
     let groupWritable = false;
     const trusted = new Set([facts.currentUserSid, SYSTEM_SID, ADMINISTRATORS_SID]);
+    if (facts.currentAppContainerSid)
+        trusted.add(facts.currentAppContainerSid);
     for (const ace of facts.aces) {
         if (ace.aceType !== "allow" || ace.flags.inheritOnly || trusted.has(ace.sid))
             continue;

package/node_modules/@openclaw/fs-safe/dist/windows-security-helper.d.ts

@@ -0,0 +1,2 @@
+export declare function windowsSecurityHelperPath(): string;
+export declare function explainWindowsSecurityHelperFailure(error: Error): void;

package/node_modules/@openclaw/fs-safe/dist/windows-security-helper.js

@@ -0,0 +1,7 @@
+import { fileURLToPath } from "node:url";
+export function windowsSecurityHelperPath() {
+    return fileURLToPath(new URL("./windows-security-helper.exe", import.meta.url));
+}
+export function explainWindowsSecurityHelperFailure(error) {
+    error.message += "; Windows security helper could not complete; rebuild with pnpm build:windows-helper or reinstall @openclaw/fs-safe";
+}

package/node_modules/@openclaw/fs-safe/dist/windows-test-hooks.d.ts

@@ -0,0 +1,16 @@
+/** Test-only handle that omits delete sharing. */
+export declare function holdWindowsSharingLock(filePath: string): Disposable & {
+    close(): void;
+};
+/** Test-only attribute updates preserve unspecified bits on the opened object. */
+export declare function setWindowsFileAttributes(filePath: string, attrs: {
+    readOnly?: boolean;
+    hidden?: boolean;
+    system?: boolean;
+}): void;
+/** Test-only physical mapping reader; lcn -1 represents sparse clusters. */
+export declare function readWindowsFileExtents(filePath: string): {
+    vcn: bigint;
+    lcn: bigint;
+    clusters: bigint;
+}[];

package/node_modules/@openclaw/fs-safe/dist/windows-test-hooks.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { requireNativeBinding } from "./native.js";
+function call(operation) {
+    if (process.platform !== "win32") {
+        throw new FsSafeError("unsupported-platform", "Windows test fixtures require Windows");
+    }
+    try {
+        return operation();
+    }
+    catch (cause) {
+        if (cause instanceof FsSafeError)
+            throw cause;
+        throw new FsSafeError("helper-failed", "Windows test fixture operation failed", { cause });
+    }
+}
+/** Test-only handle that omits delete sharing. */
+export function holdWindowsSharingLock(filePath) {
+    return call(() => {
+        const native = requireNativeBinding();
+        if (!native.holdWindowsSharingLock)
+            throw new FsSafeError("helper-unavailable", "Windows sharing fixture unavailable");
+        const owner = native.holdWindowsSharingLock(path.toNamespacedPath(filePath));
+        let closed = false;
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            call(() => owner.close());
+        };
+        return Object.freeze({ close, [Symbol.dispose]: close });
+    });
+}
+/** Test-only attribute updates preserve unspecified bits on the opened object. */
+export function setWindowsFileAttributes(filePath, attrs) {
+    call(() => {
+        const native = requireNativeBinding();
+        if (!native.setWindowsFileAttributes)
+            throw new FsSafeError("helper-unavailable", "Windows attribute fixture unavailable");
+        native.setWindowsFileAttributes(path.toNamespacedPath(filePath), attrs);
+    });
+}
+/** Test-only physical mapping reader; lcn -1 represents sparse clusters. */
+export function readWindowsFileExtents(filePath) {
+    return call(() => {
+        const native = requireNativeBinding();
+        if (!native.readWindowsFileExtents)
+            throw new FsSafeError("helper-unavailable", "Windows extent fixture unavailable");
+        return native.readWindowsFileExtents(path.toNamespacedPath(filePath));
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/write-file-handle.d.ts

@@ -10,4 +10,5 @@ export declare function writeAllToFile(target: FileHandle | number, data: string
     encoding?: BufferEncoding;
     position?: number;
     assertBeforeMutation?: () => void;
+    synchronous?: boolean;
 }): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/write-file-handle.js

@@ -31,16 +31,18 @@ export async function writeAllToFile(target, data, options = {}) {
         const length = Math.min(WRITE_CHUNK_BYTES, buffer.byteLength - offset);
         const position = options.position === undefined ? null : options.position + offset;
         options.assertBeforeMutation?.();
-        const written = typeof target === "number"
-            ? await new Promise((resolve, reject) => {
-                fs.write(target, buffer, offset, length, position, (error, bytesWritten) => {
-                    if (error)
-                        reject(error);
-                    else
-                        resolve(bytesWritten);
-                });
-            })
-            : (await target.write(buffer, offset, length, position)).bytesWritten;
+        const written = typeof target === "number" && options.synchronous
+            ? fs.writeSync(target, buffer, offset, length, position)
+            : typeof target === "number"
+                ? await new Promise((resolve, reject) => {
+                    fs.write(target, buffer, offset, length, position, (error, bytesWritten) => {
+                        if (error)
+                            reject(error);
+                        else
+                            resolve(bytesWritten);
+                    });
+                })
+                : (await target.write(buffer, offset, length, position)).bytesWritten;
         if (written <= 0) {
             throw new FsSafeError("helper-failed", "file write made no progress");
         }

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

@@ -79,11 +79,12 @@ concurrent namespace changes.
 | `sameFileContentsSync`, `SameFileContentsOptions` | [Exact file comparison](file-contents.md) | Compare borrowed regular-file descriptors byte for byte through EOF with bounded memory and an optional per-file byte limit, preserving both cursors and lifetimes. |
 | `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. |
+| `createRootFileOpenBatchSync`, `RootFileOpenBatchSync` | [Synchronous open batches](reading.md#synchronous-open-batches) | Reuse native Windows root handles for synchronous file opens while retaining fresh file checks. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
 | `retainEntryForPublication`, `RetainedEntryPublication`, `RetainEntryForPublicationOptions`, `EntryPublicationReceipt`, `EntryPublicationResult`, `EntryPublicationIssue`, `PublicationIdentity`, `PublicationParent` | [One-way entry publication](entry-publication.md) | Native no-replace directory/regular-file/symlink export, including Windows NTFS junctions, under caller-exclusive namespace; explicit transition receipts, close-only disposal, no source CAS. |
 | `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. |
 | `copyRootFileSync`, `createRootFileCopyBatchSync`, `RootFileCopyBatchSync`, `CopyRootFileSyncOptions`, `CopiedRootFileSync` | [copy.md](copy.md#synchronous-guarded-file-copies) | Synchronous guarded exclusive file copy, optionally cloned and bound to an expected source identity, returning an owned destination descriptor and both identities. |
-| `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
+| `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality; unsafe Number components never match. Use bigint stats for exact Windows IDs. |
 | `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, 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. |

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

@@ -185,6 +185,15 @@ policy to the complete archive, including entries that extraction would strip
 or skip. Known UTF-8 and Unicode Path names are checked during physical admission;
 legacy names retain backend-selected decoding and undergo the same collision
 check before callbacks or selected bytes are returned.
+Native legacy decoding is CP437 when neither the UTF-8 flag nor a valid Unicode
+Path override declares UTF-8, even if the raw bytes also happen to form valid
+UTF-8. Invalid flagged UTF-8 and invalid Unicode Path CRC/encoding fail closed;
+the native metadata boundary enforces these checks before decoder normalization.
+Native ZIP inspection also retains rejection of malformed Unicode Comment
+checksums and UTF-8, including in entries unrelated to a requested payload.
+Comment CRCs follow the native decoder's historical decoded-comment semantics;
+valid sequential Unicode overrides retain their decoder order. Public physical
+admission continues to reject duplicate critical Unicode Path fields.
 
 ZIP end-record admission searches the bounded comment window for signatures
 while retaining complete comment-length and ambiguity checks. Dense signature
@@ -244,6 +253,9 @@ remaining components are skipped before the filter callback, but still count
 toward `maxEntries` and undergo traversal validation. JavaScript TAR extraction
 copies the admitted payload range to this accepted output path, so depth checks,
 collision checks, writes, and mode application agree.
+ZIP directories naming the relative archive root (for example `./`) follow the
+same skip rule on both backends. Portable preflight retains their relative `./`
+spelling; a literal absolute `/` entry is still rejected.
 
 An `entryFilter` sees the validated **canonical effective archive path before
 stripping**, entry kind, and declared size. On every JavaScript and native
@@ -348,6 +360,10 @@ A failure before publication preserves a pre-existing file, and rejection does
 not grant authority to delete a substituted file or alias. Failed extraction does not
 restore overwritten contents. Active destination mutations and their guarded
 cleanup still finish before rejection; no later destination mutation begins.
+On supported native POSIX paths, each active destination ancestor uses its retained
+descriptor plus fresh named-identity and physical-path observations at every guard
+boundary. These checks are never cached or reduced to the deepest directory alone.
+Other paths retain the full pathname checks.
 Portable ZIP output is not eligible for publication until its stream closes or
 the defensive `FileHandle` close succeeds. If that fallback close rejects,
 `extractArchive()` propagates the error and publishes no entry from the staged

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

@@ -12,10 +12,13 @@ import {
   configureFsSafeNative,
   configureFsSafeLocks,
   getFsSafeNativeConfig,
+  getFsSafeNativeStatus,
   getFsSafeLockConfig,
   type FsSafeLockConfig,
   type FsSafeNativeConfig,
   type FsSafeNativeMode,
+  type FsSafeNativeStatus,
+  type FsSafeNativeStatusReason,
 } from "@openclaw/fs-safe/config";
 ```
 
@@ -42,7 +45,7 @@ Set the process-global loading policy. Configure once at startup, before the fir
 | `require` | Operations that need the binding raise `FsSafeError("helper-unavailable")` when it cannot load. |
 
 Fallbacks include guarded JavaScript, the bundled TAR/gzip WASM parser, and the
-[packaged Windows security scripts](install.md#windows-security-fallback).
+[packaged Windows security helper](install.md#windows-security-fallback).
 Windows command fallbacks remain subject to normal system execution policy.
 
 ## `getFsSafeNativeConfig()`
@@ -53,6 +56,73 @@ function getFsSafeNativeConfig(): FsSafeNativeConfig;
 
 Return the effective configuration: programmatic overrides win, then env vars, then the package default (`auto`).
 
+## `getFsSafeNativeStatus(options?)`
+
+```ts
+function getFsSafeNativeStatus(options?: { probe?: boolean }): Promise<FsSafeNativeStatus>;
+
+type FsSafeNativeStatusReason =
+  | "not-probed" | "loaded" | "disabled" | "unsupported-target"
+  | "package-missing" | "load-failed" | "capability-missing";
+
+type FsSafeNativeStatus = {
+  mode: FsSafeNativeMode;
+  modeSource: "programmatic configuration" | "FS_SAFE_NATIVE_MODE" | "OPENCLAW_FS_SAFE_NATIVE_MODE" | "default";
+  reason: FsSafeNativeStatusReason;
+  loaded: boolean;
+  target: string;
+  packageName?: string;
+  packageVersion?: string;
+  loadErrorCode?: string;
+  guidance?: string;
+};
+```
+
+| Field | Meaning |
+|---|---|
+| `mode` | Effective `auto`, `off`, or `require` policy. |
+| `modeSource` | The winning programmatic setting, environment variable **name**, or default. |
+| `reason` | Cached loader outcome; `not-probed` until a load is attempted, unless the effective mode is `off` (`disabled`). |
+| `loaded` | `true` exactly when `reason` is `loaded`. This confirms the loader's core capability check, not every operation's capabilities or kernel-atomic behavior. |
+| `target` | Runtime platform/architecture/libc, such as `win32-x64-msvc` or `linux-x64-gnu`; also supplied for unsupported targets. |
+| `packageName` | Expected native platform package; absent for unsupported targets. |
+| `packageVersion` | Exact pinned version from fs-safe's manifest, when a platform package exists. |
+| `loadErrorCode` | Present only for `load-failed`: an allowlisted loader code, or `UNKNOWN`. |
+| `guidance` | Cause-specific next steps, shared with fallback warnings; absent for `not-probed` and `loaded`. |
+
+The function returns a promise and loads its status module on the first call,
+keeping the `config` import lightweight. The default, `{ probe: false }`, reads
+the cached outcome without loading the addon. `{ probe: true }` attempts the same
+lazy load as a native operation, unless
+the mode is `off`. It never changes the configured mode or performs filesystem
+mutations. Failed loads are reported even in `require` mode, without throwing.
+`package-missing` identifies an unresolved platform package; a missing dependency
+inside an installed package is `load-failed`. `capability-missing` means the
+loader's core required capability is absent. Individual operations can still
+lack capabilities when this API reports `loaded`.
+
+For a doctor or startup health check:
+
+```ts
+import { getFsSafeNativeStatus } from "@openclaw/fs-safe/config";
+
+const native = await getFsSafeNativeStatus({ probe: true });
+if (native.loaded) {
+  console.log(`Native filesystem support loaded for ${native.target}`);
+} else {
+  console.log(`Native filesystem support: ${native.reason}`);
+  if (native.guidance) console.log(native.guidance);
+}
+```
+
+Status is per module instance. A real Worker has its own configuration, loader
+cache, and status; checking the main thread does not probe its Workers. Restart
+the process or Worker after repairing an installation: successes and failures
+are cached, and neither repeated probes nor mode changes retry a failed load.
+No field contains filesystem paths, raw native error messages, or environment
+variable values. See [fallback troubleshooting](native-helper.md#troubleshooting-fallback-warnings)
+for the individual causes and next steps.
+
 ## `configureFsSafeLocks(config)`
 
 ```ts