@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,390 @@
+import { randomUUID } from "node:crypto";
+import fsSync, { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertSyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { guardedRename } from "./guarded-mutation.js";
+import { assertSourceStillMatches, cleanupCopiedEntry, createCleanupCopiedEntryState, entryIdentity, inspectSourceDirectory, inspectSourceEntry, sameIdentity, sourceChangedError, } from "./move-path-cleanup.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
+import { cleanupPinnedFilePath } from "./file-cleanup.js";
+import { createMoveStageOwner } from "./move-path-stage.js";
+import { admitStandalonePublicationPath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+export function moveCopyFallbackReasonForRenameError(error, platform = process.platform) {
+    const code = error?.code;
+    if (code === "EXDEV") {
+        return "cross-device";
+    }
+    if (code === "EPERM" && platform === "win32") {
+        return "windows-rename-denied";
+    }
+    return undefined;
+}
+const MAX_HARDLINK_PREFLIGHT_ENTRIES = 50_000;
+function hardlinkedSourceError(sourcePath) {
+    return new FsSafeError("hardlink", `Refusing to move hardlinked file: ${sourcePath}`);
+}
+function hardlinkWalkTooLargeError() {
+    return new FsSafeError("too-large", `Source hardlink preflight exceeds ${MAX_HARDLINK_PREFLIGHT_ENTRIES} entries`);
+}
+async function preflightSourceHardlinks(sourcePath) {
+    const pending = [sourcePath];
+    let discovered = 1;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const stat = fsSync.lstatSync(current);
+        if (stat.isFile() && stat.nlink > 1) {
+            throw hardlinkedSourceError(current);
+        }
+        if (!stat.isDirectory()) {
+            continue;
+        }
+        const directory = await fs.opendir(current);
+        for await (const entry of directory) {
+            discovered += 1;
+            if (discovered > MAX_HARDLINK_PREFLIGHT_ENTRIES) {
+                throw hardlinkWalkTooLargeError();
+            }
+            pending.push(path.join(current, entry.name));
+        }
+    }
+}
+function isSameOrDescendant(parentPath, candidatePath) {
+    const relative = path.relative(parentPath, candidatePath);
+    return (relative === "" ||
+        (!path.isAbsolute(relative) && !relative.startsWith(`..${path.sep}`) && relative !== ".."));
+}
+async function assertCopyDestinationOutsideSource(sourcePath, targetPath, expectedIdentity) {
+    const sourceStat = inspectSourceEntry(sourcePath, () => fsSync.lstatSync(sourcePath, { bigint: true }));
+    const sourceIdentity = entryIdentity(sourceStat);
+    if (expectedIdentity && !sameIdentity(expectedIdentity, sourceIdentity)) {
+        throw sourceChangedError(sourcePath);
+    }
+    const normalizedSource = path.resolve(sourcePath);
+    const normalizedTarget = path.resolve(targetPath);
+    const sourceParentReal = realpathSync.native(path.dirname(normalizedSource));
+    const targetParentReal = realpathSync.native(path.dirname(normalizedTarget));
+    const sourceCandidate = path.join(sourceParentReal, path.basename(normalizedSource));
+    const targetCandidate = path.join(targetParentReal, path.basename(normalizedTarget));
+    const sourceBoundary = sourceStat.isDirectory()
+        ? realpathSync.native(sourcePath)
+        : sourceCandidate;
+    const unsafeTarget = sourceStat.isDirectory()
+        ? isSameOrDescendant(sourceBoundary, targetCandidate)
+        : path.relative(sourceBoundary, targetCandidate) === "";
+    if (unsafeTarget) {
+        throw new FsSafeError("invalid-path", "Move destination must not be inside the source");
+    }
+    return sourceIdentity;
+}
+function modeBits(mode) {
+    return Number(mode & 511n);
+}
+async function chmodDirectoryPinned(directoryPath, mode) {
+    if (process.platform === "win32") {
+        // Node cannot portably open a Windows directory for descriptor-bound
+        // chmod. POSIX modes are not enforced there, so do not fall back to a
+        // pathname operation that could follow a replacement symlink.
+        return;
+    }
+    const handle = await fs.open(directoryPath, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW);
+    try {
+        await handle.chmod(mode);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeAll(handle, buffer, bytesRead) {
+    let offset = 0;
+    while (offset < bytesRead) {
+        const { bytesWritten } = await handle.write(buffer, offset, bytesRead - offset);
+        if (bytesWritten <= 0)
+            throw new FsSafeError("helper-failed", "move copy made no progress");
+        offset += bytesWritten;
+    }
+}
+async function copyRegularFilePinned(params) {
+    let openedIdentity;
+    let sourceHandle;
+    try {
+        sourceHandle = await fs.open(params.from, resolveReadOpenFlags());
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ELOOP" || code === "ENOENT" || code === "ENOTDIR") {
+            throw sourceChangedError(params.from);
+        }
+        throw error;
+    }
+    try {
+        const inspectOpenedSource = () => inspectSourceEntry(params.from, () => {
+            const stat = fsSync.fstatSync(sourceHandle.fd, { bigint: true });
+            if (params.rejectHardlinks && stat.nlink > 1n)
+                throw hardlinkedSourceError(params.from);
+            if (!stat.isFile())
+                throw sourceChangedError(params.from);
+            return stat;
+        });
+        const openedStat = inspectOpenedSource();
+        openedIdentity = entryIdentity(openedStat);
+        const openAdvancedWindowsCtime = process.platform === "win32" &&
+            params.identity.dev === openedIdentity.dev &&
+            params.identity.ino === openedIdentity.ino &&
+            params.identity.mode === openedIdentity.mode &&
+            params.identity.nlink === openedIdentity.nlink &&
+            params.identity.size === openedIdentity.size &&
+            params.identity.mtimeNs === openedIdentity.mtimeNs &&
+            openedIdentity.ctimeNs >= params.identity.ctimeNs;
+        if (!sameIdentity(params.identity, openedIdentity) && !openAdvancedWindowsCtime) {
+            throw sourceChangedError(params.from);
+        }
+        await assertSourceStillMatches(params.from, openedIdentity);
+        const parentGuard = await createAsyncDirectoryGuard(path.dirname(params.to), { bigint: true });
+        const destinationHandle = await fs.open(params.to, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, modeBits(params.mode) || 0o666);
+        let destinationIdentity;
+        try {
+            destinationIdentity = fsSync.fstatSync(destinationHandle.fd, { bigint: true });
+            params.onCreated?.(destinationIdentity);
+            const scratch = Buffer.allocUnsafe(64 * 1024);
+            while (true) {
+                const { bytesRead } = await sourceHandle.read(scratch, 0, scratch.length, null);
+                if (bytesRead === 0) {
+                    break;
+                }
+                await writeAll(destinationHandle, scratch, bytesRead);
+            }
+            // Re-check the opened source before the staged tree can be committed. If
+            // it changed while we copied, the caller should retry the move.
+            if (!sameIdentity(openedIdentity, inspectOpenedSource())) {
+                throw sourceChangedError(params.from);
+            }
+            await destinationHandle.chmod(modeBits(params.mode));
+        }
+        catch (error) {
+            await cleanupPinnedFilePath({
+                pathname: params.to, handle: destinationHandle, identity: destinationIdentity, parentGuard,
+            });
+            throw error;
+        }
+        finally {
+            await destinationHandle.close();
+        }
+    }
+    finally {
+        await sourceHandle.close();
+    }
+    return openedIdentity;
+}
+async function copyEntryWithManifest(from, to, options, expectedIdentity) {
+    const sourceStat = inspectSourceEntry(from, () => fsSync.lstatSync(from, { bigint: true }));
+    const identity = entryIdentity(sourceStat);
+    if (expectedIdentity && !sameIdentity(expectedIdentity, identity)) {
+        throw sourceChangedError(from);
+    }
+    if (sourceStat.isSymbolicLink()) {
+        const target = await fs.readlink(from);
+        const targetType = process.platform === "win32" && fsSync.statSync(from).isDirectory() ? "junction" : undefined;
+        await fs.symlink(target, to, targetType);
+        options.onCreated?.(fsSync.lstatSync(to, { bigint: true }));
+        // readlink() is path-based; verify the symlink we copied is still the one
+        // we inspected before letting the staged destination become visible.
+        await assertSourceStillMatches(from, identity);
+        return { ...identity, kind: "leaf" };
+    }
+    if (sourceStat.isDirectory()) {
+        const directoryIdentity = Object.freeze({ dev: sourceStat.dev, ino: sourceStat.ino });
+        await fs.mkdir(to, { mode: modeBits(sourceStat.mode) || 0o755 });
+        options.onCreated?.(fsSync.lstatSync(to, { bigint: true }));
+        const children = [];
+        const childNames = [];
+        const directory = await fs.opendir(from);
+        for await (const entry of directory) {
+            if (options.budget && ++options.budget.discovered > MAX_HARDLINK_PREFLIGHT_ENTRIES) {
+                throw hardlinkWalkTooLargeError();
+            }
+            childNames.push(entry.name);
+        }
+        for (const child of childNames) {
+            children.push({
+                name: child,
+                manifest: await copyEntryWithManifest(path.join(from, child), path.join(to, child), {
+                    sourceHardlinks: options.sourceHardlinks, budget: options.budget,
+                    aliases: options.aliases,
+                }),
+            });
+        }
+        // Directory traversal is path-based in Node. Treat a changed parent as a
+        // stale move before committing so swapped-in outside trees are not imported.
+        await assertSourceStillMatches(from, identity);
+        inspectSourceDirectory(from, directoryIdentity);
+        // mkdir() honors process umask. Restore the source mode before commit so
+        // EXDEV fallback preserves directory permissions like fs.cp did.
+        await chmodDirectoryPinned(to, modeBits(sourceStat.mode));
+        return { ...identity, children, directoryIdentity, kind: "directory" };
+    }
+    if (!sourceStat.isFile()) {
+        throw new Error(`Refusing to move non-file path with copy fallback: ${from}`);
+    }
+    if (options.sourceHardlinks === "reject" && sourceStat.nlink > 1n) {
+        throw hardlinkedSourceError(from);
+    }
+    const aliasKey = options.aliases && identity.nlink > 1n ? `${identity.dev}:${identity.ino}` : undefined;
+    const alias = aliasKey ? options.aliases.get(aliasKey) : undefined;
+    if (alias && !sameIdentity(alias, identity))
+        throw sourceChangedError(from);
+    const copiedIdentity = await copyRegularFilePinned({
+        from,
+        identity,
+        mode: sourceStat.mode,
+        rejectHardlinks: options.sourceHardlinks === "reject",
+        to,
+        onCreated: options.onCreated,
+    });
+    // A permitted Windows open advances every name's ctime. Share its receipt
+    // only after the preceding fingerprint and this complete copy were verified.
+    if (alias)
+        return Object.assign(alias, copiedIdentity);
+    const manifest = { ...copiedIdentity, kind: "leaf" };
+    if (aliasKey)
+        options.aliases.set(aliasKey, manifest);
+    return manifest;
+}
+function assertSynchronousResult(returned, name) {
+    if (returned !== undefined) {
+        // TypeScript permits async functions for () => void; consume their rejection.
+        void Promise.resolve(returned).catch(() => { });
+        throw new TypeError(`${name} must return undefined synchronously`);
+    }
+}
+export async function movePathWithCopyFallback(options) {
+    const from = admitStandalonePublicationPath(options.from, "move source uses a Windows filesystem namespace alias");
+    const to = admitStandalonePublicationPath(options.to, "move destination uses a Windows filesystem namespace alias");
+    const sourcePath = path.resolve(from);
+    const targetPath = path.resolve(to);
+    assertNoWindowsPathAlias(sourcePath, "filesystem", "move source uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(targetPath, "filesystem", "move destination uses a Windows filesystem namespace alias");
+    const sourceHardlinks = options.sourceHardlinks;
+    // Keep the initiating owner's callbacks across preparation and copy fallback.
+    const callerRenameAssert = options.assertBeforeRename;
+    const callerMutationAssert = options.assertBeforeMutation;
+    const callerPublished = options.onDestinationPublished;
+    let assertionRejected = false;
+    let destinationPublished = false;
+    const assertBeforeMutation = callerMutationAssert == null ? undefined : () => {
+        assertSynchronousResult(callerMutationAssert(), "assertBeforeMutation");
+    };
+    const assertBeforeRename = () => {
+        try {
+            assertSynchronousResult(callerRenameAssert?.(), "assertBeforeRename");
+            assertBeforeMutation?.();
+        }
+        catch (error) {
+            assertionRejected = true;
+            throw error;
+        }
+    };
+    let publicationReceipt;
+    const onSourceInspected = callerPublished
+        ? (identity) => {
+            publicationReceipt = Object.freeze({
+                path: targetPath,
+                dev: identity.dev,
+                ino: identity.ino,
+            });
+        }
+        : undefined;
+    const onRenamed = () => {
+        destinationPublished = true;
+        if (publicationReceipt) {
+            assertSynchronousResult(callerPublished?.(publicationReceipt), "onDestinationPublished");
+        }
+    };
+    const rejectHardlinks = sourceHardlinks === "reject";
+    if (rejectHardlinks) {
+        await preflightSourceHardlinks(sourcePath);
+    }
+    if (!rejectHardlinks) {
+        try {
+            await guardedRename({
+                from: sourcePath,
+                to: targetPath,
+                assertBeforeRename,
+                onSourceInspected,
+                onRenamed,
+            });
+            return;
+        }
+        catch (error) {
+            // An owner's EXDEV/EPERM refusal is not permission to copy instead.
+            if (assertionRejected || destinationPublished || !moveCopyFallbackReasonForRenameError(error)) {
+                throw error;
+            }
+        }
+    }
+    else {
+        // A pathname preflight cannot make nlink and rename one atomic operation.
+        // Commit a fresh inode through the copy path so a post-scan hardlink can
+        // never become the published target; the copy loop fences nlink again.
+    }
+    const sourceIdentity = await assertCopyDestinationOutsideSource(sourcePath, targetPath);
+    const sourceParentPath = path.dirname(sourcePath);
+    const sourceParent = assertBeforeMutation || callerRenameAssert || callerPublished
+        ? await createAsyncDirectoryGuard(realpathSync.native(sourceParentPath), { bigint: true })
+        : undefined;
+    const assertSourceParent = sourceParent ? () => {
+        try {
+            if (realpathSync.native(sourceParentPath) !== sourceParent.realPath)
+                throw sourceChangedError(sourcePath);
+            assertSyncDirectoryGuard(sourceParent);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP" ||
+                (error instanceof FsSafeError && (error.code === "path-mismatch" || error.code === "not-file"))) {
+                throw sourceChangedError(sourcePath);
+            }
+            throw error;
+        }
+    } : undefined;
+    const assertBeforeCleanup = assertSourceParent ? () => {
+        assertBeforeMutation?.();
+        assertSourceParent();
+    } : undefined;
+    const targetDir = path.dirname(targetPath);
+    const staged = path.join(targetDir, `.fs-safe-move-${process.pid}-${randomUUID()}.tmp`);
+    const stage = await createMoveStageOwner(staged);
+    try {
+        const manifest = await copyEntryWithManifest(sourcePath, staged, {
+            sourceHardlinks: rejectHardlinks ? "reject" : "allow",
+            onCreated: stage.record,
+            ...(!rejectHardlinks && process.platform === "win32" ? { aliases: new Map() } : {}),
+            ...(rejectHardlinks ? { budget: { discovered: 1 } } : {}),
+        }, sourceIdentity);
+        const cleanupState = createCleanupCopiedEntryState(sourcePath, manifest);
+        await assertCopyDestinationOutsideSource(sourcePath, targetPath, manifest);
+        if (manifest.kind === "directory")
+            inspectSourceDirectory(sourcePath, manifest.directoryIdentity);
+        await guardedRename({
+            from: staged,
+            to: targetPath,
+            assertBeforeRename: () => { assertBeforeRename(); stage.assertCurrent(); },
+            onSourceInspected,
+            onRenamed: () => {
+                stage.published();
+                onRenamed();
+            },
+        });
+        assertSourceParent?.();
+        const cleanupResult = await cleanupCopiedEntry(sourcePath, manifest, cleanupState, assertBeforeCleanup);
+        if (cleanupResult === "stale") {
+            throw sourceChangedError(sourcePath);
+        }
+    }
+    finally {
+        if (!destinationPublished) {
+            await stage.cleanup();
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+import { FsSafeError } from "./errors.js";
+export declare class MutationAuthorityError extends FsSafeError {
+    readonly rejection: unknown;
+    constructor(rejection: unknown);
+}
+export declare function assertSynchronousCallbackResult(returned: unknown, name: string): void;
+export declare function composeMutationAssertions(defaultAssertion?: () => void, callAssertion?: () => void): (() => void) | undefined;
+export declare function rethrowMutationAuthorityError(error: unknown): never;

package/node_modules/@openclaw/fs-safe/dist/mutation-authority.js

@@ -0,0 +1,41 @@
+import { types } from "node:util";
+import { FsSafeError } from "./errors.js";
+export class MutationAuthorityError extends FsSafeError {
+    rejection;
+    constructor(rejection) {
+        super("denied-path", "mutation authority rejected the operation", { cause: rejection });
+        this.rejection = rejection;
+    }
+}
+export function assertSynchronousCallbackResult(returned, name) {
+    if (returned !== null &&
+        (typeof returned === "object" || typeof returned === "function") &&
+        typeof returned.then === "function") {
+        // TypeScript permits async functions for () => void. Do not admit their work.
+        void Promise.resolve(returned).catch(() => undefined);
+        throw new TypeError(`${name} must be synchronous`);
+    }
+    // A generator returns its iterator before running the callback body.
+    if (types.isGeneratorObject(returned)) {
+        throw new TypeError(`${name} must be synchronous`);
+    }
+}
+export function composeMutationAssertions(defaultAssertion, callAssertion) {
+    if (!defaultAssertion && !callAssertion)
+        return undefined;
+    return () => {
+        try {
+            assertSynchronousCallbackResult(defaultAssertion?.(), "assertBeforeMutation");
+            assertSynchronousCallbackResult(callAssertion?.(), "assertBeforeMutation");
+        }
+        catch (error) {
+            throw new MutationAuthorityError(error);
+        }
+    };
+}
+export function rethrowMutationAuthorityError(error) {
+    if (error instanceof MutationAuthorityError)
+        throw error.rejection;
+    // Cleanup failures and indeterminate publication receipts must retain their context.
+    throw error;
+}

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

@@ -0,0 +1,199 @@
+import type { RetainedFileResult } from "./retained-file-types.js";
+export interface NativeRetainedFile {
+    readonly admission: RetainedFileResult | {
+        status: "retained";
+        identity: string;
+    };
+    settle(remove: boolean): RetainedFileResult;
+}
+import type { TarMeterLimits } from "./archive-limits.js";
+import type { ArchiveMemberKind } from "./archive-plan.js";
+import type { CopyCloneMode } from "./copy-policy.js";
+import type { WindowsAceFlags } from "./owner-dacl.js";
+export interface NativeFileHash {
+    bytes: number;
+    digest: string;
+}
+export interface NativeFileIdentity {
+    dev: number;
+    ino: number;
+    mode: number;
+    nlink: number;
+    size: number;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
+export interface NativeDirectoryObservation {
+    dev: bigint;
+    ino: bigint;
+    realPath: string;
+}
+export interface NativeDirectoryFdObservation extends NativeDirectoryObservation {
+    mode: bigint;
+    nlink: bigint;
+}
+export interface NativeArchiveEntry {
+    index: number;
+    path: string;
+    kind: ArchiveMemberKind;
+    size: number;
+    mode: number;
+}
+export interface NativeArchivePlanEntry extends NativeArchiveEntry {
+}
+export interface NativeCopyResult {
+    fd: number;
+    bytes: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface NativeFileCopyResult {
+    fd: number;
+    method: "clone" | "copy-file-range" | "copy";
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface NativeOpenBeneathResult {
+    fd: number;
+    containment: "kernel-atomic" | "best-effort";
+}
+export interface NativeOwnedTreeRemovalResult {
+    outcome?: "removed" | "preserved";
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface NativeWindowsAccessControlEntry {
+    sid: string;
+    mask: number;
+    aceType: string;
+    flags: WindowsAceFlags;
+}
+export interface NativeWindowsSecurityFacts {
+    ownerSid: string;
+    currentUserSid: string;
+    ownerClass: string;
+    worldWritable: boolean;
+    groupWritable: boolean;
+    worldReadable: boolean;
+    groupReadable: boolean;
+    fallbackRequired: boolean;
+    daclPresent: boolean;
+    isLocal: boolean;
+    aceListComplete: boolean;
+    unsupportedAceTypes: number[];
+    aces: NativeWindowsAccessControlEntry[];
+}
+export interface NativeWindowsDescriptorSecurityFacts {
+    /** Canonical lowercase 32-bit volume serial and 64-bit file-index projection used by Node. */
+    identity: string;
+    security: NativeWindowsSecurityFacts;
+}
+export interface NativeWindowsDirectoryReceipt {
+    /** Canonical 64-bit volume serial and all 128 file-ID bits, in Windows byte order. */
+    identity: string;
+}
+export interface NativeDarwinAclFacts {
+    state: "absent" | "empty" | "present";
+}
+type NativeTwoPathArgs = [
+    sourceRootFd: number,
+    sourceRelPath: string,
+    targetRootFd: number,
+    targetRelPath: string
+];
+export interface NativeBinding {
+    /** Windows-only, private handle custody; no borrowed/runtime descriptors. */
+    retainWindowsFile?(directory: string, basename: string, parentDev: bigint, parentIno: bigint, dev: bigint, ino: bigint, size: bigint, mtimeNs: bigint, ctimeNs: bigint, sha256: string, maxBytes: number): NativeRetainedFile;
+    watchRegister?(root: string, limit: number, callback: (batch: import("./watch-native.js").NativeWatchWireBatch) => void, persistent: boolean): number;
+    watchConfigure?(id: number, anchors: string[], exclusions: string[]): void;
+    watchAdd?(id: number, directory: {
+        root: string;
+        relative: string;
+        rootDev: bigint;
+        rootIno: bigint;
+        dev: bigint;
+        ino: bigint;
+    }): void;
+    watchTestEvent?(id: number, path: string, flags: number): void;
+    watchUnregister?(id: number): void;
+    watchThreadCount?(): number;
+    watchMemoryStats?(): {
+        registrations: number;
+        pendingSets: number;
+        payloadsLive: number;
+        payloadsCreated: number;
+        payloadsDestroyed: number;
+        threadsafeFunctionsLive: number;
+        threadsafeFunctionsCreated: number;
+        threadsafeFunctionsDestroyed: number;
+    };
+    /** Internal: consumes only a descriptor returned by this binding. */
+    closeOwnedFd(fd: number): void;
+    /** 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. */
+    canonicalizePath?(path: string, ordinary: boolean): {
+        path?: string;
+        errno?: number;
+    };
+    /** 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. */
+    observeDirectoryFd?(fd: number, expectedPath: string): NativeDirectoryFdObservation;
+    /** 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<{
+        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<{
+        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>;
+    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;
+    stagedFileMatches?(parentFd: number, basename: string, fileFd: number): 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, sync: boolean): Promise<NativeFileCopyResult>;
+    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;
+    /** Direct-child mkdir; true is receipt provenance only, never cleanup ownership. */
+    mkdirChildBeneath?(parentFd: number, basename: string, mode: number): boolean;
+    mkdirBeneath(rootFd: number, relPath: string, mode: number): void;
+    openBeneath(rootFd: number, relPath: string, flags: number): NativeOpenBeneathResult;
+    readArchiveEntryNative(path: string, kind: string, requested: string, maxBytes: number, limits: TarMeterLimits, signal: AbortSignal): Promise<Buffer>;
+    readOwnerAndDacl(path: string): NativeWindowsSecurityFacts;
+    /** Internal Windows-only inspection of the exact borrowed Node descriptor. */
+    inspectWindowsSecureFileHandle?(fd: number): NativeWindowsDescriptorSecurityFacts;
+    ownedTreeRemovalAvailable?(parentFd: number): boolean;
+    removeOwnedTree?(parentFd: number, basename: string, directoryFd: number): Promise<NativeOwnedTreeRemovalResult>;
+    removeOwnedTreeSync?(parentFd: number, basename: string, directoryFd: number): NativeOwnedTreeRemovalResult;
+    renameNoReplace(...args: NativeTwoPathArgs): 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>;
+}
+export declare function captureNativeFdClose(binding: NativeBinding): (fd: number) => void;
+export {};

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

@@ -0,0 +1,8 @@
+import { FsSafeError } from "./errors.js";
+export function captureNativeFdClose(binding) {
+    if (typeof binding.closeOwnedFd !== "function") {
+        throw new FsSafeError("helper-unavailable", "native descriptor ownership is unavailable");
+    }
+    // Retained descriptors must remain disposable after native configuration changes.
+    return binding.closeOwnedFd.bind(binding);
+}

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

@@ -0,0 +1,16 @@
+export type FsSafeNativeMode = "auto" | "off" | "require";
+export type FsSafeNativeConfig = {
+    mode: FsSafeNativeMode;
+};
+/** @deprecated Compatibility bridge for 0.4 upgrades. Use {@link FsSafeNativeConfig}. */
+export type FsSafePythonConfig = {
+    mode: FsSafeNativeMode;
+    pythonPath?: string;
+};
+export declare function configureFsSafeNative(config: Partial<FsSafeNativeConfig>): void;
+/**
+ * @deprecated Compatibility bridge for 0.4 upgrades. Use configureFsSafeNative.
+ */
+export declare function configureFsSafePython(config: Partial<FsSafePythonConfig>): void;
+export declare function getFsSafeNativeConfig(): FsSafeNativeConfig;
+export declare function __resetFsSafeNativeConfigForTest(): void;