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

package/node_modules/@openclaw/fs-safe/dist/local-file-descriptor.js

@@ -1,3 +1,4 @@
+import { numberStats } from "./exact-identity.js";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
@@ -5,7 +6,7 @@ import { recordFileOpenFailure, recordPreOpenFileChange } from "./opened-file-fa
 import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError, } from "./path.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { fileNotFoundError, hardlinkedPathNotAllowedError } from "./root-errors.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const OPEN_READ_FLAGS = resolveReadOpenFlags();
 const OPEN_READ_FOLLOW_FLAGS = resolveReadOpenFlags({ followSymlinks: true });
@@ -19,7 +20,7 @@ export async function openLocalFileDescriptor(filePath, options) {
     // Reject directories before opening so we never surface EISDIR to callers (e.g. tool
     // results that get sent to messaging channels). See openclaw/openclaw#31186.
     try {
-        preOpenStat = await inspectFileIdentity(() => {
+        preOpenStat = inspectFileIdentitySync(() => {
             const stat = fsSync.lstatSync(filePath, { bigint: true });
             observedBeforeOpen = true;
             if (stat.isSymbolicLink() && options?.symlinks !== "follow-within-root") {
@@ -37,13 +38,14 @@ export async function openLocalFileDescriptor(filePath, options) {
         }
         // Only an initial lookup failure falls through; a failed re-inspection aborts.
     }
-    if (preOpenStat) {
-        await fsSafeTestHooks?.afterPreOpenLstat?.(filePath);
+    if (preOpenStat && fsSafeTestHooks?.afterPreOpenLstat) {
+        await fsSafeTestHooks.afterPreOpenLstat(filePath);
     }
     const openFlags = (options?.symlinks === "follow-within-root"
         ? OPEN_READ_FOLLOW_FLAGS
         : OPEN_READ_FLAGS) | (options?.readWrite ? fsSync.constants.O_RDWR : 0);
-    await fsSafeTestHooks?.beforeOpen?.(filePath, openFlags);
+    if (fsSafeTestHooks?.beforeOpen)
+        await fsSafeTestHooks.beforeOpen(filePath, openFlags);
     let handle;
     try {
         handle = await fs.open(filePath, openFlags).catch((error) => recordFileOpenFailure(isNotFoundPathError(error) ? fileNotFoundError() : error, filePath));
@@ -59,19 +61,28 @@ export async function openLocalFileDescriptor(filePath, options) {
         throw err;
     }
     try {
-        await fsSafeTestHooks?.afterOpen?.(filePath, handle);
-        const stat = fsSync.fstatSync(handle.fd);
-        if (!stat.isFile()) {
-            throw new FsSafeError("not-file", "not a file");
-        }
+        if (fsSafeTestHooks?.afterOpen)
+            await fsSafeTestHooks.afterOpen(filePath, handle);
         // Keep numeric Stats for the public receipt, never for identity verification.
         let openedIdentity;
-        const identity = await inspectFileIdentity(() => (openedIdentity = fsSync.fstatSync(handle.fd, { bigint: true })), preOpenStat && !preOpenStat.isSymbolicLink() ? preOpenStat : undefined).catch(async (error) => {
-            if ([0, 1].includes(stat.nlink)) {
+        let identity;
+        try {
+            identity = inspectFileIdentitySync(() => {
+                openedIdentity = fsSync.fstatSync(handle.fd, { bigint: true });
+                if (!openedIdentity.isFile())
+                    throw new FsSafeError("not-file", "not a file");
+                return openedIdentity;
+            }, preOpenStat && !preOpenStat.isSymbolicLink() ? preOpenStat : undefined);
+        }
+        catch (error) {
+            if (openedIdentity && [0n, 1n].includes(openedIdentity.nlink)) {
                 await recordPreOpenFileChange(error, handle, filePath, preOpenStat, openedIdentity);
             }
             throw error;
-        });
+        }
+        if (!identity.isFile())
+            throw new FsSafeError("not-file", "not a file");
+        const stat = numberStats(identity);
         if (options?.hardlinks === "reject" && stat.nlink > 1) {
             throw hardlinkedPathNotAllowedError();
         }

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

@@ -81,6 +81,9 @@ export interface NativeOwnedTreeRemovalResult {
     errorCode?: string;
     errorMessage?: string;
 }
+export interface NativeEmptyTreeRemovalResult extends Omit<NativeOwnedTreeRemovalResult, "outcome"> {
+    outcome?: "removed" | "preserved" | "not-empty";
+}
 export interface NativeRootRemovalEntry {
     dev: bigint;
     ino: bigint;
@@ -101,6 +104,7 @@ export interface NativeWindowsAccessControlEntry {
 export interface NativeWindowsSecurityFacts {
     ownerSid: string;
     currentUserSid: string;
+    currentAppContainerSid?: string | null;
     ownerClass: string;
     worldWritable: boolean;
     groupWritable: boolean;
@@ -124,6 +128,8 @@ export interface NativeWindowsDirectoryReceipt {
 }
 export interface NativeDarwinAclFacts {
     state: "absent" | "empty" | "present";
+    inheritsToFiles?: boolean;
+    inheritsToDirectories?: boolean;
 }
 type NativeTwoPathArgs = [
     sourceRootFd: number,
@@ -132,6 +138,37 @@ type NativeTwoPathArgs = [
     targetRelPath: string
 ];
 export interface NativeBinding {
+    readCopyMetadata?(fd: number): Buffer;
+    restoreCopyMetadata?(fd: number, snapshot: Buffer): void;
+    restoreCopyFileTimes?(fd: number, atimeNs: bigint, mtimeNs: bigint): void;
+    copyLinkExclusive?(sourceParent: number, sourceName: string, parent: number, name: string, dev: bigint, ino: bigint, preserveMetadata: boolean, mode: number): {
+        dev: bigint;
+        ino: bigint;
+    };
+    publishCopyLink?(parent: number, name: string, destination: string, dev: bigint, ino: bigint): void;
+    removeCopyLink?(parent: number, name: string, dev: bigint, ino: bigint): void;
+    createCopySymlink?(parent: number, name: string, target: Buffer, mode: number, atimeNs?: bigint, mtimeNs?: bigint): {
+        dev: bigint;
+        ino: bigint;
+        errorCode?: string;
+        errorMessage?: string;
+    };
+    tryAcquireWriteLease?(fd: number): boolean;
+    isFileWriteLeaseHeld?(fd: number): boolean;
+    releaseFileWriteLease?(fd: number): void;
+    holdWindowsSharingLock?(path: string): {
+        close(): void;
+    };
+    setWindowsFileAttributes?(path: string, attrs: {
+        readOnly?: boolean;
+        hidden?: boolean;
+        system?: boolean;
+    }): void;
+    readWindowsFileExtents?(path: string): {
+        vcn: bigint;
+        lcn: bigint;
+        clusters: bigint;
+    }[];
     rootRemovalStat?(parent: number, name: string): NativeRootRemovalEntry;
     rootRemovalUnlink?(parent: number, name: string, dev: bigint, ino: bigint, directory: boolean): void;
     openRootRemovalDirectory?(parent: number, name: string, dev: bigint, ino: bigint): NativeRootRemovalDirectory;
@@ -169,6 +206,11 @@ export interface NativeBinding {
     };
     /** Internal: consumes only a descriptor returned by this binding. */
     closeOwnedFd(fd: number): void;
+    createPipe?(): {
+        reader: number;
+        writer: number;
+        atomicCloseOnExec: boolean;
+    };
     /** Internal Darwin-only synchronous inspection; the caller retains its fd. */
     inspectDarwinAcl?(fd: number, inheritanceTarget?: "file" | "directory"): NativeDarwinAclFacts;
     /** POSIX system canonicalization; confinement and identity policy stay with callers. */
@@ -176,6 +218,10 @@ export interface NativeBinding {
         path?: string;
         errno?: number;
     };
+    /** Internal Windows normalized name resolution after a denied DOS-name query. */
+    resolveWindowsCanonicalPath?(path: string): string | null;
+    /** Internal immutable primary-token membership, cached across Workers. */
+    isWindowsAppContainer?(): boolean;
     /** Internal: exact directory identity and canonical path from one no-follow handle. */
     observeDirectory?(path: string): NativeDirectoryObservation;
     /** Internal POSIX-only exact name/descriptor observation; the caller retains its fd. */
@@ -183,66 +229,87 @@ export interface NativeBinding {
     /** Linux/Windows byte transfer; callers retain both admitted descriptors until settlement. */
     copyFileContents?(sourceFd: number, targetFd: number, signal?: AbortSignal): Promise<void>;
     /** Internal: same private, immutable input ownership as the ZIP buffer reader. */
-    openTarBufferNative(buffer: Buffer, kind: string, limits: TarMeterLimits, signal?: AbortSignal): Promise<{
+    openTarBufferNative?(buffer: Buffer, kind: string, limits: TarMeterLimits, signal?: AbortSignal): Promise<{
         readonly entries: NativeArchiveEntry[];
         readEntry(index: number, maxBytes: number, signal?: AbortSignal): Promise<Buffer>;
     }>;
     /** Internal: input remains private, unpooled and immutable until the reader is released. */
-    openZipBufferNative(buffer: Buffer, limits: TarMeterLimits, signal?: AbortSignal): Promise<{
+    openZipBufferNative?(buffer: Buffer, limits: TarMeterLimits, signal?: AbortSignal): Promise<{
         readonly entries: NativeArchiveEntry[];
         readEntry(index: number, maxBytes: number, signal?: AbortSignal): Promise<Buffer>;
     }>;
-    readCloneFileMetadata(paths: string[]): Promise<(Buffer | null)[]>;
-    probeTreeClone(parentFd: number): "apfs" | "btrfs" | "refs" | "xfs" | "zfs" | null;
-    cloneTree(sourceFd: number | null, parentFd: number, basename: string, concurrency: number, signal?: AbortSignal): Promise<void>;
+    readCloneFileMetadata?(paths: string[]): Promise<(Buffer | null)[]>;
+    probeTreeClone?(parentFd: number): "apfs" | "btrfs" | "refs" | "xfs" | "zfs" | null;
+    cloneTree?(sourceFd: number | null, parentFd: number, basename: string, concurrency: number, signal?: AbortSignal): Promise<void>;
     openStagedSymlink?(parentFd: number, basename: string): number;
     stagedSymlinkTarget?(parentFd: number, basename: string, linkFd: number): string;
     stagedSymlinkMatches?(parentFd: number, basename: string, linkFd: number): boolean;
     publishStagedSymlink?(parentFd: number, basename: string, linkFd: number, destination: string): void;
     removeStagedSymlink?(parentFd: number, basename: string, linkFd: number): "removed" | "name-absent" | "preserved";
     createStagedFile?(parentFd: number, basename: string): number;
+    stagedFileMetadata?(parentFd: number, basename: string, fd: number): {
+        mode: bigint;
+        nlink: bigint;
+    } | null;
     stagedFileMatches?(parentFd: number, basename: string, fileFd: number): boolean;
+    stagedDirectoryMatches?(fd: number, path: string, dev: bigint, ino: bigint): boolean;
     removeStagedFile?(parentFd: number, basename: string, fileFd: number): "removed" | "name-absent" | "preserved";
     copyFileExclusive?(sourceFd: number, parentFd: number, basename: string, clone: CopyCloneMode, maxBytes: number | undefined, signal: AbortSignal | undefined): Promise<NativeFileCopyResult>;
     copyFileExclusiveSync?(sourceFd: number, parentFd: number, basename: string, clone: CopyCloneMode, maxBytes: number | undefined): NativeFileCopyResult;
-    cloneFileExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): number;
-    copyFileRangeExclusive(sourceFd: number, targetRootFd: number, targetRelPath: string): Promise<NativeCopyResult>;
-    createPrivateDirectory(path: string): void;
+    cloneFileExclusive?(sourceFd: number, targetRootFd: number, targetRelPath: string): number;
+    copyFileRangeExclusive?(sourceFd: number, targetRootFd: number, targetRelPath: string): Promise<NativeCopyResult>;
+    createPrivateDirectory?(path: string): void;
     /** Internal Windows creation receipts use full FILE_ID_INFO, never Node's projection. */
     inspectWindowsDirectory?(path: string, requirePrivate: boolean): NativeWindowsDirectoryReceipt;
     createPrivateDirectoryWithParentIdentity?(path: string, expectedParentIdentity: string): NativeWindowsDirectoryReceipt;
     /** Protects an already-private borrowed Node file; descriptor ownership stays with Node. */
     protectPrivateWindowsFile?(fd: number, path: string, expectedParentIdentity: string): NativeWindowsDirectoryReceipt;
     verifyPrivateWindowsFile?(fd: number, path: string, expectedFileIdentity: string, expectedParentIdentity: string, expectedLinks: number): void;
-    extractArchiveNative(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], limits: TarMeterLimits, signal: AbortSignal): Promise<void>;
-    fstatIdentity(fd: number): NativeFileIdentity;
-    inspectArchiveNative(path: string, kind: string, limits: TarMeterLimits, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
-    linkBeneath(...args: NativeTwoPathArgs): void;
+    extractArchiveNative?(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], limits: TarMeterLimits, signal: AbortSignal): Promise<void>;
+    fstatIdentity?(fd: number): NativeFileIdentity;
+    inspectArchiveNative?(path: string, kind: string, limits: TarMeterLimits, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
+    linkBeneath?(...args: NativeTwoPathArgs): void;
     /** Direct-child mkdir; true is receipt provenance only, never cleanup ownership. */
     mkdirChildBeneath?(parentFd: number, basename: string, mode: number): boolean;
     mkdirOpenChildBeneath?(parentFd: number, basename: string, mode: number, flags: number): {
         fd: number;
         created: boolean;
     };
-    mkdirBeneath(rootFd: number, relPath: string, mode: number): void;
-    openBeneath(rootFd: number, relPath: string, flags: number): NativeOpenBeneathResult;
-    readOwnerAndDacl(path: string): NativeWindowsSecurityFacts;
+    createTempDirectoryBeneath?(parentFd: number, basename: string): {
+        fd: number;
+        searchOnly: boolean;
+    };
+    verifyRootDirectory?(pathname: string, dev: bigint, ino: bigint): null | {
+        errorCode?: string;
+        errorMessage?: string;
+        errorErrno?: number;
+        closeErrorCode?: string;
+        closeErrorMessage?: string;
+        closeErrorErrno?: number;
+        fallbackFd?: number;
+    };
+    mkdirBeneath?(rootFd: number, relPath: string, mode: number): void;
+    openBeneath?(rootFd: number, relPath: string, flags: number): NativeOpenBeneathResult;
+    openPublicationMetadata?(parentFd: number, basename: string): number;
+    readOwnerAndDacl?(path: string): NativeWindowsSecurityFacts;
     /** Internal Windows-only inspection of the exact borrowed Node descriptor. */
     inspectWindowsSecureFileHandle?(fd: number): NativeWindowsDescriptorSecurityFacts;
     ownedTreeRemovalAvailable?(parentFd: number): boolean;
+    tryRemoveEmptyOwnedTree?(parentFd: number, basename: string, directoryFd: number): NativeEmptyTreeRemovalResult;
     removeOwnedTree?(parentFd: number, basename: string, directoryFd: number): Promise<NativeOwnedTreeRemovalResult>;
     removeOwnedTreeSync?(parentFd: number, basename: string, directoryFd: number): NativeOwnedTreeRemovalResult;
     /** Local filesystem admission for one-way cooperative entry publication. */
     retainWindowsEntryPublication?(sourcePath: string, name: string, sourceDev: bigint, sourceIno: bigint, targetPath: string, targetName: string, targetDev: bigint, targetIno: bigint, dev: bigint, ino: bigint, kind: "file" | "directory" | "symlink"): NativeWindowsEntryPublication;
     entryPublicationFilesystem?(parentFd: number): string;
     publishRetainedEntryNoReplace?(sourceParentFd: number, sourceBasename: string, sourceFd: number, targetParentFd: number, targetBasename: string): NativePublicationTransition;
-    renameNoReplace(...args: NativeTwoPathArgs): void;
+    renameNoReplace?(...args: NativeTwoPathArgs): void;
     /** Linux auto-mode fallback through already-admitted direct-child parents. */
     moveNoReplaceFallback?(...args: [...paths: NativeTwoPathArgs, expectedSourceDev: bigint, expectedSourceIno: bigint]): void;
     /** Identity-fenced retained-directory rename capability. */
     renameNoReplaceWithIdentity?(...args: [...paths: NativeTwoPathArgs, expectedSourceDev: bigint, expectedSourceIno: bigint]): void;
-    renameReplace(...args: NativeTwoPathArgs): void;
-    sha256File(fd: number, maxBytes?: number, signal?: AbortSignal): Promise<NativeFileHash>;
+    renameReplace?(...args: NativeTwoPathArgs): void;
+    sha256File?(fd: number, maxBytes?: number, signal?: AbortSignal, ownsPosition?: boolean): Promise<NativeFileHash>;
 }
+export type CapableNativeBinding<K extends keyof NativeBinding> = NativeBinding & Required<Pick<NativeBinding, K>>;
 export declare function captureNativeFdClose(binding: NativeBinding): (fd: number) => void;
 export {};

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

@@ -4,5 +4,10 @@ export type FsSafeNativeConfig = {
 };
 export declare function configureFsSafeNative(config: Partial<FsSafeNativeConfig>): void;
 export declare function getFsSafeNativeConfig(): FsSafeNativeConfig;
+/** Internal provenance; keep the public configuration shape unchanged. */
+export declare function getNativeModeSetting(): {
+    mode: FsSafeNativeMode;
+    source: "programmatic configuration" | "FS_SAFE_NATIVE_MODE" | "OPENCLAW_FS_SAFE_NATIVE_MODE" | "default";
+};
 export declare function isFsSafeNativeRequired(): boolean;
 export declare function __resetFsSafeNativeConfigForTest(): void;

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

@@ -26,6 +26,17 @@ export function getFsSafeNativeConfig() {
             "auto",
     };
 }
+/** Internal provenance; keep the public configuration shape unchanged. */
+export function getNativeModeSetting() {
+    if (overrideConfig.mode !== undefined)
+        return { mode: overrideConfig.mode, source: "programmatic configuration" };
+    for (const source of ["FS_SAFE_NATIVE_MODE", "OPENCLAW_FS_SAFE_NATIVE_MODE"]) {
+        const mode = parseMode(process.env[source]);
+        if (mode !== undefined)
+            return { mode, source };
+    }
+    return { mode: "auto", source: "default" };
+}
 export function isFsSafeNativeRequired() {
     return (overrideConfig.mode ??
         parseMode(process.env.FS_SAFE_NATIVE_MODE) ??

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

@@ -2,23 +2,25 @@ import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { isNativeStatIdentity, statIdentityFromNative } from "./native-stat-identity.js";
 export function getNativeDirectoryObservationBackend(enabled = true) {
     if (!enabled)
         return undefined;
-    const binding = getNativeBinding();
+    const binding = getNativeBinding("observeDirectory");
     return binding && typeof binding.observeDirectory === "function"
         ? binding
         : undefined;
 }
 function validateNativeDirectoryObservation(observation) {
-    if (!observation || typeof observation.dev !== "bigint" || observation.dev < 0n ||
-        typeof observation.ino !== "bigint" || observation.ino < 0n ||
+    if (!observation || !isNativeStatIdentity(observation.dev) ||
+        !isNativeStatIdentity(observation.ino) ||
         typeof observation.realPath !== "string" ||
         observation.realPath.includes("\0") ||
         (!path.isAbsolute(observation.realPath) && !path.win32.isAbsolute(observation.realPath))) {
         throw new FsSafeError("path-mismatch", "native directory observation is invalid");
     }
-    return observation;
+    const dev = statIdentityFromNative(observation.dev), ino = statIdentityFromNative(observation.ino);
+    return dev === observation.dev && ino === observation.ino ? observation : { ...observation, dev, ino };
 }
 /** Exact identity, type, and canonical path captured from one retained handle. */
 export function inspectNativeDirectoryObservation(backend, pathname, expected, platform = process.platform) {

package/node_modules/@openclaw/fs-safe/dist/native-fallback-warning.d.ts

@@ -1,3 +1,4 @@
+import { type NativeBinding } from "./native.js";
 /** Warn once per capability, without including caller paths or native error text. */
-export declare function warnNativeFallback(feature: string, limitation: string): void;
+export declare function warnNativeFallback(feature: string, limitation: string, ...capabilities: (keyof NativeBinding)[]): void;
 export declare function __resetNativeFallbackWarningsForTest(): void;

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

@@ -1,10 +1,34 @@
+import { getNativeFallbackDiagnostic } from "./native.js";
+import { getNativeModeSetting } from "./native-config.js";
+import { nativeGuidance } from "./native-guidance.js";
 const warnedFeatures = new Set();
+function fallbackReason(capabilities) {
+    const diagnostic = getNativeFallbackDiagnostic(...capabilities);
+    const expected = diagnostic.packageName === undefined
+        ? `No native package is published for ${diagnostic.target}.`
+        : `Expected ${diagnostic.packageName}@${diagnostic.packageVersion}.`;
+    const guidance = nativeGuidance(diagnostic.reason, getNativeModeSetting().source);
+    switch (diagnostic.reason) {
+        case "disabled":
+            return `native support is disabled by ${diagnostic.source} (disabled). ${expected} ${guidance}`;
+        case "unsupported-target":
+            return `the target ${diagnostic.target} is unsupported (unsupported-target). ${expected} ${guidance}`;
+        case "package-missing":
+            return `the selected native package could not be resolved (package-missing). ${expected} ${guidance}`;
+        case "load-failed":
+            return `the native package could not be loaded (load-failed: ${diagnostic.code}). ${expected} ${guidance}`;
+        case "capability-missing":
+            return `the native package lacks requested functions (capability-missing: ${diagnostic.capabilities.join(", ")}). ${expected} ${guidance}`;
+        default:
+            return `the requested native operation is unavailable (${diagnostic.reason}). ${expected}`;
+    }
+}
 /** Warn once per capability, without including caller paths or native error text. */
-export function warnNativeFallback(feature, limitation) {
+export function warnNativeFallback(feature, limitation, ...capabilities) {
     if (warnedFeatures.has(feature))
         return;
     warnedFeatures.add(feature);
-    process.emitWarning(`${feature} is using its portable fallback because native support is unavailable or disabled. ${limitation}`, { code: "FS_SAFE_NATIVE_FALLBACK", type: "FsSafeWarning" });
+    process.emitWarning(`${feature} is using its portable fallback because ${fallbackReason(capabilities)} ${limitation}`, { code: "FS_SAFE_NATIVE_FALLBACK", type: "FsSafeWarning" });
 }
 export function __resetNativeFallbackWarningsForTest() {
     warnedFeatures.clear();

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

@@ -0,0 +1,3 @@
+import type { getNativeModeSetting } from "./native-config.js";
+/** Shared, path-free next steps for status reports and fallback warnings. */
+export declare function nativeGuidance(reason: string, modeSource: ReturnType<typeof getNativeModeSetting>["source"]): string | undefined;

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

@@ -0,0 +1,21 @@
+/** Shared, path-free next steps for status reports and fallback warnings. */
+export function nativeGuidance(reason, modeSource) {
+    switch (reason) {
+        case "disabled": {
+            const enable = modeSource === "programmatic configuration"
+                ? 'call configureFsSafeNative({ mode: "auto" }) or configureFsSafeNative({ mode: "require" })'
+                : `set ${modeSource}=auto or ${modeSource}=require`;
+            return `If native loading is intended, ${enable}; keep intentional off settings.`;
+        }
+        case "unsupported-target":
+            return "Portable mode is expected on this target.";
+        case "package-missing":
+            return "Reinstall with optional dependencies included: npm --include=optional, or pnpm without --no-optional / optional=false. Check the lockfile and registry mirror.";
+        case "load-failed":
+            return "Check Node architecture, Linux libc compatibility, package dependencies, and OS code-integrity policy. Reinstalling identical bytes may not help.";
+        case "capability-missing":
+            return "Use matching fs-safe and platform-package versions; some targets intentionally provide only a subset of capabilities.";
+        default:
+            return undefined;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/native-move-fallback.d.ts

@@ -1,3 +1,3 @@
 import type { BigIntStats } from "node:fs";
 import type { NativeBinding } from "./native-binding.js";
-export declare function nativeMoveNoReplace(binding: NativeBinding, paths: Parameters<NativeBinding["renameNoReplace"]>, expected: BigIntStats | undefined, allowFallback: boolean, operation?: string): "link-unlink" | undefined;
+export declare function nativeMoveNoReplace(binding: NativeBinding, paths: Parameters<NonNullable<NativeBinding["renameNoReplace"]>>, expected: BigIntStats | undefined, allowFallback: boolean, operation?: string): "link-unlink" | undefined;

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

@@ -1,4 +1,5 @@
 import { FsSafeError } from "./errors.js";
+import { assertNativeCapabilities } from "./native.js";
 import { cachedNoReplaceUnavailable, noReplaceUnavailable, rememberNoReplaceUnavailable, } from "./native-noreplace.js";
 function fallbackError(error, operation) {
     const code = error?.code;
@@ -24,6 +25,7 @@ function fallbackError(error, operation) {
     return error;
 }
 export function nativeMoveNoReplace(binding, paths, expected, allowFallback, operation = "move") {
+    assertNativeCapabilities(binding, "renameNoReplace");
     const [sourceFd, source, targetFd, target] = paths;
     let unavailable = cachedNoReplaceUnavailable(binding, sourceFd, operation);
     if (!unavailable) {

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

@@ -1,5 +1,4 @@
 import fsSync, {} from "node:fs";
-import fs from "node:fs/promises";
 import path from "node:path";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { getNativeBinding } from "./native.js";
@@ -32,21 +31,21 @@ export function removeNativeCreatedFileIfStillPinned(params) {
     }
 }
 export async function createNativeExclusiveFile(targetPath, mode) {
-    const binding = getNativeBinding();
+    const binding = getNativeBinding("openBeneath");
     if (!binding) {
         return undefined;
     }
     const closeFd = captureNativeFdClose(binding);
     const parentPath = path.dirname(targetPath);
     const basename = path.basename(targetPath);
-    const parent = await fs.open(parentPath, fsSync.constants.O_RDONLY |
+    const parentFd = fsSync.openSync(parentPath, fsSync.constants.O_RDONLY |
         (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0));
     let fd;
     let created;
     try {
         let opened;
         try {
-            opened = binding.openBeneath(parent.fd, basename, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL));
+            opened = binding.openBeneath(parentFd, basename, nativeOpenFlags(fsSync.constants.O_WRONLY | fsSync.constants.O_CREAT | fsSync.constants.O_EXCL));
         }
         catch (error) {
             // The parent open above and every post-create operation remain untagged.
@@ -94,7 +93,7 @@ export async function createNativeExclusiveFile(targetPath, mode) {
             }
             removeNativeCreatedFileIfStillPinned({
                 parentPath,
-                parentFd: parent.fd,
+                parentFd,
                 basename,
                 created,
             });
@@ -102,6 +101,9 @@ export async function createNativeExclusiveFile(targetPath, mode) {
         throw error;
     }
     finally {
-        await parent.close().catch(() => undefined);
+        try {
+            fsSync.closeSync(parentFd);
+        }
+        catch { /* Preserve the creation outcome. */ }
     }
 }

package/node_modules/@openclaw/fs-safe/dist/native-parent-admission.d.ts

@@ -1,15 +1,20 @@
 import { type BigIntStats, type Stats } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
-import type { FileIdentityStat } from "./file-identity.js";
-import type { NativeBinding } from "./native.js";
+import { type FileIdentityStat } from "./file-identity.js";
+import { type NativeBinding } from "./native.js";
 import { describeStagedDirectory } from "./staged-directory.js";
 type RootIdentity = Pick<FileIdentityStat, "dev" | "ino">;
+type NativeRootHandle = {
+    readonly fd: number;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+};
 export type NativeRootAdmission = {
     directoryFlags?: number;
     exactRoot: boolean;
     reportCloseErrors?: boolean;
     operation: string;
-    root: FileHandle;
+    root: NativeRootHandle;
     rootPath: string;
 };
 export type NativeParentAdmission = {
@@ -23,6 +28,41 @@ export type NativeParentAdmission = {
     stagedDirectory?: ReturnType<typeof describeStagedDirectory>;
 };
 export declare function sameNativeIdentity(left: RootIdentity, right: RootIdentity): boolean;
+/** Short native mutations need a retained descriptor, not a Node FileHandle. */
+export declare function openExactNativeRootSync(binding: NativeBinding, params: {
+    rootPath: string;
+    rootIdentity: {
+        dev: bigint;
+        ino: bigint;
+    };
+}): {
+    fd: number;
+    stat: BigIntStats;
+    close(): void;
+    [Symbol.dispose](): void;
+};
+export declare function openExactNativeRootAdmissionSync(binding: NativeBinding, params: {
+    rootPath: string;
+    rootIdentity: {
+        dev: bigint;
+        ino: bigint;
+    };
+    operation: string;
+    reportCloseErrors?: boolean;
+}): {
+    directoryFlags: number;
+    exactRoot: boolean;
+    reportCloseErrors: boolean | undefined;
+    operation: string;
+    root: {
+        fd: number;
+        stat: BigIntStats;
+        close(): void;
+        [Symbol.dispose](): void;
+    };
+    rootPath: string;
+};
+export declare function borrowNativeRootParent(admission: ReturnType<typeof openExactNativeRootAdmissionSync>): NativeParentAdmission;
 export declare function openNativeRootAdmission(binding: NativeBinding, params: {
     rootPath: string;
     rootIdentity?: RootIdentity;
@@ -32,5 +72,5 @@ export declare function openNativeRootAdmission(binding: NativeBinding, params:
 }): Promise<NativeRootAdmission>;
 export declare function openNativeParentAdmission(binding: NativeBinding, rootAdmission: Omit<NativeRootAdmission, "root"> & {
     root: Pick<FileHandle, "fd">;
-}, relativeParentPath: string, observation?: "native-directory"): Promise<NativeParentAdmission>;
+}, relativeParentPath: string, observation?: "native-directory" | "native-publication"): Promise<NativeParentAdmission>;
 export {};