@openclaw/matrix 2026.10.5-beta.4 → 2026.10.10-beta.2

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 {};

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

@@ -1,18 +1,20 @@
 import fsSync, {} from "node:fs";
-import fs from "node:fs/promises";
 import path from "node:path";
-import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { assertSyncDirectoryGuard, inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
 import { inspectNativeDirectoryObservation } from "./native-directory-observation.js";
 import { FsSafeError } from "./errors.js";
+import { hasSafeFileIdentity } from "./file-identity.js";
+import { assertNativeCapabilities } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { realpathSync } from "./realpath.js";
-import { describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
+import { describeNativeStagedDirectory, describePolicyStagedDirectory, describeStagedDirectory, exactIdentityMatches } from "./staged-directory.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
 export function sameNativeIdentity(left, right) {
-    return left.dev === right.dev && left.ino === right.ino;
+    return hasSafeFileIdentity(left) && hasSafeFileIdentity(right) &&
+        BigInt(left.dev) === BigInt(right.dev) && BigInt(left.ino) === BigInt(right.ino);
 }
 function unavailable(message) {
     return new FsSafeError("helper-unavailable", message);
@@ -22,13 +24,67 @@ function assertParentAdmissionAvailable(binding) {
         throw unavailable("native parent directory admission is unavailable");
     }
     captureNativeFdClose(binding);
+    assertNativeCapabilities(binding, "openBeneath");
+}
+/** Short native mutations need a retained descriptor, not a Node FileHandle. */
+export function openExactNativeRootSync(binding, params) {
+    assertParentAdmissionAvailable(binding);
+    assertNoWindowsPathAlias(params.rootPath, "filesystem", "native root uses a Windows filesystem namespace alias");
+    const flags = (nodeDirectorySearchOnlyFlags()?.flags ?? fsSync.constants.O_RDONLY) |
+        (fsSync.constants.O_DIRECTORY ?? 0);
+    const fd = fsSync.openSync(pathForWindowsFilesystem(params.rootPath), flags);
+    let held = true;
+    const close = () => {
+        if (!held)
+            return;
+        held = false;
+        fsSync.closeSync(fd);
+    };
+    try {
+        const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), params.rootIdentity);
+        if (!stat.isDirectory())
+            throw new FsSafeError("path-mismatch", "native root is not a directory");
+        return { fd, stat, close, [Symbol.dispose]: close };
+    }
+    catch (error) {
+        try {
+            close();
+        }
+        catch (closeError) {
+            throw createSuppressedError(closeError, error, "native root admission and close failed");
+        }
+        throw error;
+    }
+}
+export function openExactNativeRootAdmissionSync(binding, params) {
+    return {
+        directoryFlags: (nodeDirectorySearchOnlyFlags()?.flags ?? fsSync.constants.O_RDONLY) | (fsSync.constants.O_DIRECTORY ?? 0),
+        exactRoot: true,
+        reportCloseErrors: params.reportCloseErrors,
+        operation: params.operation,
+        root: openExactNativeRootSync(binding, params),
+        rootPath: params.rootPath,
+    };
+}
+export function borrowNativeRootParent(admission) {
+    const guard = { dir: admission.rootPath, realPath: admission.rootPath, stat: admission.root.stat };
+    assertSyncDirectoryGuard(guard);
+    return { fd: admission.root.fd, guard, close() { } };
 }
 export async function openNativeRootAdmission(binding, params) {
     assertParentAdmissionAvailable(binding);
     const directoryFlags = (params.searchOnly ? nodeDirectorySearchOnlyFlags()?.flags ?? fsSync.constants.O_RDONLY : fsSync.constants.O_RDONLY) |
         (fsSync.constants.O_DIRECTORY ?? 0);
     assertNoWindowsPathAlias(params.rootPath, "filesystem", "native root uses a Windows filesystem namespace alias");
-    const root = await fs.open(pathForWindowsFilesystem(params.rootPath), directoryFlags);
+    let fd = fsSync.openSync(pathForWindowsFilesystem(params.rootPath), directoryFlags);
+    const close = async () => {
+        if (fd < 0)
+            return;
+        const owned = fd;
+        fd = -1;
+        fsSync.closeSync(owned);
+    };
+    const root = { get fd() { return fd; }, close, [Symbol.asyncDispose]: close };
     try {
         const exactRoot = typeof params.rootIdentity?.dev === "bigint" &&
             typeof params.rootIdentity.ino === "bigint";
@@ -38,10 +94,7 @@ export async function openNativeRootAdmission(binding, params) {
             rootMatches = true;
         }
         else if (process.platform === "win32") {
-            if (typeof binding.fstatIdentity !== "function") {
-                throw unavailable("native root directory identity checks are unavailable");
-            }
-            const identity = binding.fstatIdentity(root.fd);
+            const identity = fsSync.fstatSync(root.fd, { bigint: true });
             rootMatches = !params.rootIdentity || sameNativeIdentity(params.rootIdentity, identity);
         }
         else {
@@ -87,7 +140,8 @@ export async function openNativeParentAdmission(binding, rootAdmission, relative
         const parentInput = relativeParentPath
             ? path.join(rootAdmission.rootPath, ...relativeParentPath.split("/"))
             : rootAdmission.rootPath;
-        if (observation === "native-directory" && process.platform === "win32" && rootAdmission.exactRoot &&
+        if ((observation === "native-directory" || observation === "native-publication") &&
+            process.platform === "win32" && rootAdmission.exactRoot &&
             typeof binding.observeDirectory === "function") {
             const stat = inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true }));
             let observed;
@@ -110,17 +164,33 @@ export async function openNativeParentAdmission(binding, rootAdmission, relative
         }
         const parentPath = realpathSync.native(pathForWindowsFilesystem(parentInput));
         assertNoWindowsPathAlias(parentPath, "filesystem", "native parent uses a Windows filesystem namespace alias");
+        if (observation === "native-publication" && process.platform !== "win32" && rootAdmission.exactRoot) {
+            const captured = describeNativeStagedDirectory(binding, parentFd, parentPath);
+            return {
+                fd: parentFd,
+                close: () => closeFd(parentFd),
+                guard: { dir: parentPath, realPath: parentPath, stat: captured.stat },
+                stagedDirectory: captured.directory,
+            };
+        }
+        if (observation === "native-directory" && process.platform !== "win32" && rootAdmission.exactRoot) {
+            const captured = describePolicyStagedDirectory(parentFd, parentPath, binding);
+            captured.disposeObservation?.();
+            return {
+                fd: parentFd,
+                close: () => closeFd(parentFd),
+                guard: { dir: parentPath, realPath: parentPath, stat: captured.stat },
+                stagedDirectory: captured.directory,
+            };
+        }
         const stagedDirectory = process.platform === "win32"
             ? undefined
             : describeStagedDirectory(parentFd, parentPath);
         const parentPathStat = rootAdmission.exactRoot
             ? await inspectDirectoryIdentity(parentPath, inspectFileIdentitySync(() => fsSync.fstatSync(parentFd, { bigint: true })))
-            : fsSync.lstatSync(pathForWindowsFilesystem(parentPath));
+            : fsSync.lstatSync(pathForWindowsFilesystem(parentPath), { bigint: true });
         if (process.platform === "win32" && !rootAdmission.exactRoot) {
-            if (typeof binding.fstatIdentity !== "function") {
-                throw unavailable("native parent directory identity checks are unavailable");
-            }
-            const parentIdentity = binding.fstatIdentity(parentFd);
+            const parentIdentity = fsSync.fstatSync(parentFd, { bigint: true });
             if (parentPathStat.isSymbolicLink() || !sameNativeIdentity(parentPathStat, parentIdentity)) {
                 throw new FsSafeError("path-mismatch", `${rootAdmission.operation} parent changed during resolution`);
             }

package/node_modules/@openclaw/fs-safe/dist/native-pinned-write-windows.d.ts

@@ -1,6 +1,6 @@
-import type { FileHandle } from "node:fs/promises";
+import type { NativeRootAdmission } from "./native-parent-admission.js";
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
-import type { NativeBinding } from "./native.js";
+import { type NativeBinding } from "./native.js";
 import type { PinnedWriteParams } from "./pinned-write-types.js";
-export declare function runPinnedWriteWindows(binding: NativeBinding, params: PinnedWriteParams, root: FileHandle, parentFd: number, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;
+export declare function runPinnedWriteWindows(binding: NativeBinding, params: PinnedWriteParams, root: NativeRootAdmission["root"], parentFd: number, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;