@openclaw/feishu 2026.9.6 → 2026.9.8

package/node_modules/@openclaw/fs-safe/dist/bounded-read.js

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+const READ_CHUNK_BYTES = 64 * 1024;
+// Preserve one-read performance through the default Root byte budget.
+const MAX_INITIAL_READ_BYTES = 16 * 1024 * 1024;
+function createInitialBuffer(maxBytes, size, allocate = Buffer.allocUnsafe) {
+    // A size hint can describe a huge sparse file or an already exhausted fd.
+    return allocate(Math.min(maxBytes, size, MAX_INITIAL_READ_BYTES) + 1);
+}
+function createScratchBuffer(maxBytes, allocate = Buffer.allocUnsafe) {
+    return allocate(Math.min(READ_CHUNK_BYTES, maxBytes + 1));
+}
+function growReadBuffer(buffer, maxBytes, allocate = Buffer.allocUnsafe) {
+    // Grow only after consuming the whole buffer, never from an unchecked size hint.
+    const capacity = Math.min(maxBytes + 1, Math.max(READ_CHUNK_BYTES, buffer.length * 2));
+    const grown = allocate(capacity);
+    buffer.copy(grown);
+    return grown;
+}
+function finishReadBuffer(buffer, total, allocate) {
+    if (total === 0)
+        return Buffer.alloc(0);
+    const result = buffer.subarray(0, total);
+    if (total >= buffer.length / 2)
+        return result;
+    if (!allocate)
+        return Buffer.from(result);
+    const compact = allocate(total);
+    result.copy(compact);
+    return compact;
+}
+function addReadBytes(total, bytesRead, maxBytes, createLimitError) {
+    const next = total + bytesRead;
+    if (next > maxBytes) {
+        if (createLimitError)
+            throw createLimitError();
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${next})`);
+    }
+    return next;
+}
+export async function readBoundedAsync(maxBytes, readChunk, options = {}) {
+    normalizeMaxBytes(maxBytes);
+    let total = 0;
+    const { observeRegularFileSize, createLimitError } = options;
+    const allocate = options.unpooled ? Buffer.allocUnsafeSlow : undefined;
+    const size = options.initialSize ?? observeRegularFileSize?.();
+    let buffer = size === undefined ? createScratchBuffer(maxBytes, allocate) : createInitialBuffer(maxBytes, size, allocate);
+    if (size !== undefined) {
+        const bytesRead = await readChunk(buffer, buffer.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, 0, allocate);
+        // Short reads can occur before EOF. Only use the size shortcut on this
+        // initial read; virtual files can report zero or stale sizes thereafter.
+        const currentSize = bytesRead < buffer.length ? observeRegularFileSize?.() : undefined;
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
+        if (currentSize !== undefined && currentSize > 0 && bytesRead >= currentSize)
+            return finishReadBuffer(buffer, total, allocate);
+    }
+    while (true) {
+        if (total === buffer.length)
+            buffer = growReadBuffer(buffer, maxBytes, allocate);
+        const remaining = buffer.subarray(total);
+        const bytesRead = await readChunk(remaining, remaining.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, total, allocate);
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
+    }
+}
+/**
+ * Reads from the handle's current offset without closing it. A bounded read
+ * consumes at most maxBytes + 1 bytes so growth after an earlier stat cannot
+ * force an unbounded allocation.
+ */
+export async function readFileHandleBounded(handle, maxBytes) {
+    normalizeMaxBytes(maxBytes);
+    const fd = "fd" in handle && typeof handle.fd === "number" ? handle.fd : undefined;
+    return await readBoundedAsync(maxBytes, async (scratch, length) => {
+        return (await handle.read(scratch, 0, length, null)).bytesRead;
+    }, { observeRegularFileSize: fd === undefined ? undefined : () => regularFileSize(fd) });
+}
+function regularFileSize(fd) {
+    try {
+        const stat = fs.fstatSync(fd);
+        return stat.isFile() && Number.isSafeInteger(stat.size) && stat.size >= 0
+            ? stat.size : undefined;
+    }
+    catch {
+        // Size is only an optimization hint; retain the reader's original errors.
+        return undefined;
+    }
+}
+function readDescriptorChunk(fd, scratch, length) {
+    return new Promise((resolve, reject) => {
+        fs.read(fd, scratch, 0, length, null, (error, bytesRead) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(bytesRead);
+        });
+    });
+}
+/** Async bounded read from a numeric descriptor. The caller owns the descriptor. */
+export async function readFileDescriptorBounded(fd, maxBytes) {
+    normalizeMaxBytes(maxBytes);
+    return await readBoundedAsync(maxBytes, async (scratch, length) => {
+        return await readDescriptorChunk(fd, scratch, length);
+    }, { observeRegularFileSize: () => regularFileSize(fd) });
+}
+export function readBoundedSync(maxBytes, readChunk, options = {}) {
+    normalizeMaxBytes(maxBytes);
+    let total = 0;
+    const { observeRegularFileSize, createLimitError } = options;
+    const size = options.initialSize ?? observeRegularFileSize?.();
+    let buffer = size === undefined ? createScratchBuffer(maxBytes) : createInitialBuffer(maxBytes, size);
+    if (size !== undefined) {
+        const bytesRead = readChunk(buffer, buffer.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, 0);
+        const currentSize = bytesRead < buffer.length ? observeRegularFileSize?.() : undefined;
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
+        if (currentSize !== undefined && currentSize > 0 && bytesRead >= currentSize)
+            return finishReadBuffer(buffer, total);
+    }
+    while (true) {
+        if (total === buffer.length)
+            buffer = growReadBuffer(buffer, maxBytes);
+        const remaining = buffer.subarray(total);
+        const bytesRead = readChunk(remaining, remaining.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, total);
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
+    }
+}
+/** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
+export function readFileDescriptorBoundedSync(fd, maxBytes) {
+    return readBoundedSync(maxBytes, (buffer, length) => fs.readSync(fd, buffer, 0, length, null), {
+        // Small budgets already bound the first allocation without a size lookup.
+        initialSize: maxBytes <= READ_CHUNK_BYTES ? maxBytes : undefined,
+        observeRegularFileSize: () => regularFileSize(fd),
+    });
+}

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

@@ -0,0 +1,3 @@
+export declare function normalizeMaxBytes(value: number | undefined, options?: {
+    defaultValue?: number;
+}): number | undefined;

package/node_modules/@openclaw/fs-safe/dist/byte-budget.js

@@ -0,0 +1,9 @@
+export function normalizeMaxBytes(value, options = {}) {
+    const selected = value === undefined ? options.defaultValue : value;
+    if (selected === undefined || selected === Number.POSITIVE_INFINITY)
+        return selected;
+    if (!Number.isSafeInteger(selected) || selected < 0) {
+        throw new RangeError("maxBytes must be a non-negative safe integer or Infinity");
+    }
+    return selected;
+}

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

@@ -0,0 +1,2 @@
+/** Snapshot intrinsic view bounds without copying the borrowed payload. */
+export declare function snapshotByteView(bytes: Uint8Array): Uint8Array;

package/node_modules/@openclaw/fs-safe/dist/byte-view.js

@@ -0,0 +1,13 @@
+const ByteView = Uint8Array;
+const typedArray = Object.getPrototypeOf(ByteView.prototype);
+const viewLength = Object.getOwnPropertyDescriptor(typedArray, "byteLength").get;
+const viewOffset = Object.getOwnPropertyDescriptor(typedArray, "byteOffset").get;
+const viewBuffer = Object.getOwnPropertyDescriptor(typedArray, "buffer").get;
+/** Snapshot intrinsic view bounds without copying the borrowed payload. */
+export function snapshotByteView(bytes) {
+    const length = Reflect.apply(viewLength, bytes, []);
+    // Preserve empty, detached, and out-of-bounds views as zero-byte inputs.
+    if (length === 0)
+        return new ByteView(0);
+    return new ByteView(Reflect.apply(viewBuffer, bytes, []), Reflect.apply(viewOffset, bytes, []), length);
+}

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

@@ -0,0 +1,19 @@
+export type CloneFileMetadata = {
+    dev: number;
+    type: number;
+    mtimeSec: number;
+    mtimeNs: number;
+    ctimeSec: number;
+    ctimeNs: number;
+    uid: number;
+    gid: number;
+    mode: number;
+    ino: bigint;
+    size: bigint;
+    cloneId: bigint;
+};
+/** Batched APFS metadata snapshots; absent on unsupported files or filesystems.
+ * On macOS, these snapshots require the native helper.
+ * These are point-in-time facts, not authorization or a guarantee against later edits.
+ */
+export declare function readCloneFileMetadata(files: readonly string[]): Promise<(CloneFileMetadata | undefined)[]>;

package/node_modules/@openclaw/fs-safe/dist/clone-metadata.js

@@ -0,0 +1,36 @@
+import { assertAbsolutePathInput } from "./absolute-path.js";
+import { getNativeBinding, requireNativeBinding } from "./native.js";
+/** Batched APFS metadata snapshots; absent on unsupported files or filesystems.
+ * On macOS, these snapshots require the native helper.
+ * These are point-in-time facts, not authorization or a guarantee against later edits.
+ */
+export async function readCloneFileMetadata(files) {
+    const paths = files.map(assertAbsolutePathInput);
+    const native = process.platform === "darwin" ? requireNativeBinding() : getNativeBinding();
+    if (!native)
+        return paths.map(() => undefined);
+    const results = await native.readCloneFileMetadata(paths);
+    return results.map((result) => {
+        if (!result ||
+            result.length !== 100 ||
+            result.readUInt32LE(0) !== 100 ||
+            result.readUInt32LE(4) !== 0x82038c0a ||
+            result.readUInt32LE(16) !== 0x200 ||
+            result.readUInt32LE(20) !== 0x100)
+            return undefined;
+        return {
+            dev: result.readUInt32LE(24),
+            type: result.readUInt32LE(28),
+            mtimeSec: Number(result.readBigInt64LE(32)),
+            mtimeNs: Number(result.readBigInt64LE(40)),
+            ctimeSec: Number(result.readBigInt64LE(48)),
+            ctimeNs: Number(result.readBigInt64LE(56)),
+            uid: result.readUInt32LE(64),
+            gid: result.readUInt32LE(68),
+            mode: result.readUInt32LE(72),
+            ino: result.readBigUInt64LE(76),
+            size: result.readBigUInt64LE(84),
+            cloneId: result.readBigUInt64LE(92),
+        };
+    });
+}

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

@@ -0,0 +1,2 @@
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";

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

@@ -0,0 +1,2 @@
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

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

@@ -0,0 +1 @@
+export type ContainmentGuarantee = "kernel-atomic" | "best-effort";

package/node_modules/@openclaw/fs-safe/dist/containment.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@openclaw/fs-safe/dist/copy-file-input.d.ts

@@ -0,0 +1,21 @@
+import { type BigIntStats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import { type CopyCloneMode } from "./copy-policy.js";
+import { type NativeBinding } from "./native.js";
+import { type NativeFileCopyResult } from "./native-binding.js";
+export type CopyFileInput = {
+    kind: "file";
+    handle: FileHandle;
+    size: number;
+    clone: CopyCloneMode;
+    signal?: AbortSignal;
+    verifySource(): Promise<void>;
+};
+export declare function resolveFileCopyCloneMode(mode?: CopyCloneMode): CopyCloneMode;
+export declare function assertCopySourceCurrent(source: {
+    handle: FileHandle;
+    realPath: string;
+}, identity: BigIntStats): Promise<void>;
+export declare function writeCopyFileToFd(fd: number, input: CopyFileInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;
+export declare function createNativeCopyFile(native: NativeBinding, input: CopyFileInput, parentFd: number, basename: string, maxBytes: number | undefined, sync: boolean): Promise<NativeFileCopyResult | undefined>;
+export declare function assertNativeCopyCompleted(input: CopyFileInput, copied?: NativeFileCopyResult): void;

package/node_modules/@openclaw/fs-safe/dist/copy-file-input.js

@@ -0,0 +1,71 @@
+import fs, {} from "node:fs";
+import { resolveCopyCloneMode } from "./copy-policy.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { captureNativeFdClose } from "./native-binding.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { transferFileHandle } from "./file-handle-transfer.js";
+export function resolveFileCopyCloneMode(mode) {
+    const clone = resolveCopyCloneMode(mode, "never");
+    if (clone === "always" && !getNativeBinding()?.copyFileExclusive) {
+        throw new FsSafeError("helper-unavailable", "native file cloning is unavailable");
+    }
+    return clone;
+}
+export async function assertCopySourceCurrent(source, identity) {
+    await inspectFileIdentity(() => fs.fstatSync(source.handle.fd, { bigint: true }), identity);
+    await inspectFileIdentity(() => {
+        const current = fs.lstatSync(source.realPath, { bigint: true });
+        if (current.isSymbolicLink() || !current.isFile()) {
+            throw new FsSafeError("path-mismatch", "copy source path changed");
+        }
+        return current;
+    }, identity);
+}
+export async function writeCopyFileToFd(fd, input, maxBytes, assertBeforeMutation) {
+    await transferFileHandle(input.handle, fd, {
+        maxBytes, sizeHint: input.size, signal: input.signal, assertBeforeMutation,
+    });
+}
+export async function createNativeCopyFile(native, input, parentFd, basename, maxBytes, sync) {
+    input.signal?.throwIfAborted();
+    if (!native.copyFileExclusive) {
+        if (input.clone === "always") {
+            throw new FsSafeError("helper-unavailable", "native file cloning is unavailable");
+        }
+        return undefined;
+    }
+    captureNativeFdClose(native);
+    const nativeSignal = input.signal ? AbortSignal.any([input.signal]) : undefined;
+    try {
+        // The caller adopts this descriptor before observing a later cancellation.
+        return await native.copyFileExclusive(input.handle.fd, parentFd, basename, input.clone, maxBytes !== undefined && Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal, sync);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "Cancelled" || code === "ABORT_ERR")
+            input.signal?.throwIfAborted();
+        if (code === "too-large") {
+            throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`, { cause: error });
+        }
+        if (code === "ENOTSUP" && input.clone !== "always")
+            return undefined;
+        if (code === "ENOTSUP") {
+            throw new FsSafeError("unsupported-platform", "native file cloning is unsupported", { cause: error });
+        }
+        throw new FsSafeError("helper-failed", "native file copy failed", { cause: error });
+    }
+    finally {
+        if (nativeSignal)
+            nativeSignal.onabort = null;
+    }
+}
+export function assertNativeCopyCompleted(input, copied) {
+    if (copied?.errorCode) {
+        if (copied.errorCode === "Cancelled" || copied.errorCode === "ABORT_ERR")
+            input.signal?.throwIfAborted();
+        const unsupported = ["ENOTSUP", "EOPNOTSUPP", "ENOSYS", "EXDEV", "EINVAL"].includes(copied.errorCode);
+        throw new FsSafeError(copied.errorCode === "too-large" ? "too-large" : unsupported ? "unsupported-platform" : "helper-failed", copied.errorMessage ?? "native file copy failed", { cause: Object.assign(new Error(copied.errorMessage ?? "native file copy failed"), { code: copied.errorCode }) });
+    }
+    input.signal?.throwIfAborted();
+}

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

@@ -0,0 +1,2 @@
+export type CopyCloneMode = "auto" | "always" | "never";
+export declare function resolveCopyCloneMode(mode: CopyCloneMode | undefined, defaultMode: CopyCloneMode): CopyCloneMode;

package/node_modules/@openclaw/fs-safe/dist/copy-policy.js

@@ -0,0 +1,8 @@
+import { FsSafeError } from "./errors.js";
+export function resolveCopyCloneMode(mode, defaultMode) {
+    const policy = mode === undefined ? defaultMode : mode;
+    if (policy !== "auto" && policy !== "always" && policy !== "never") {
+        throw new FsSafeError("invalid-path", "copy clone policy must be auto, always, or never");
+    }
+    return policy;
+}

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

@@ -0,0 +1,18 @@
+import type { BigIntStats } from "node:fs";
+import type { PinnedWriteParams, PublishedWriteIdentity } from "./pinned-write-types.js";
+export type RootCopyPublicationReceipt = Readonly<PublishedWriteIdentity & {
+    path: string;
+}>;
+export declare function createCopyPublicationObserver(path: string, notify?: (receipt: RootCopyPublicationReceipt) => void): {
+    onPublished(identity: PublishedWriteIdentity): void;
+    rethrowObserverFailure(error: unknown): void;
+};
+export declare const onCopyPublication: unique symbol;
+export declare const onCopySourceAdmission: unique symbol;
+export type CopyPublicationOptions = {
+    [onCopyPublication]?: PinnedWriteParams["verifyPublished"];
+    [onCopySourceAdmission]?: (identity: BigIntStats, realPath: string) => {
+        mode: number;
+        verify(): void;
+    };
+};

package/node_modules/@openclaw/fs-safe/dist/copy-publication.js

@@ -0,0 +1,29 @@
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+export function createCopyPublicationObserver(path, notify) {
+    let rejected;
+    return {
+        onPublished(identity) {
+            const receipt = Object.freeze({ path, dev: identity.dev, ino: identity.ino });
+            try {
+                assertSynchronousCallbackResult(notify?.(receipt), "onDestinationPublished");
+            }
+            catch (error) {
+                rejected = { error };
+                throw error;
+            }
+        },
+        rethrowObserverFailure(error) {
+            if (rejected && (error === rejected.error ||
+                (error instanceof FsSafeError && error.cause === rejected.error && error.details?.phase === "publish"))) {
+                throw rejected.error;
+            }
+        },
+    };
+}
+// Internal composition hook; the descriptor is borrowed until the callback returns.
+// Kept off RootCopyOptions and all public package exports.
+export const onCopyPublication = Symbol("onCopyPublication");
+// Reuse the copy's admitted descriptor identity before any bytes are staged.
+// Internal callers can bind prior observations and select its publication mode.
+export const onCopySourceAdmission = Symbol("onCopySourceAdmission");

package/node_modules/@openclaw/fs-safe/dist/copy-tree-portable.d.ts

@@ -0,0 +1,8 @@
+import type { NativeBinding } from "./native-binding.js";
+import { openStagedDirectory } from "./staged-directory.js";
+/** Byte-copy adapter for the shared immutable-source, caller-owned namespace contract. */
+export declare function copyOwnedTree(source: ReturnType<typeof openStagedDirectory>, destination: string, options: {
+    signal?: AbortSignal;
+    concurrency: number;
+    copyFileContents?: NativeBinding["copyFileContents"];
+}): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/copy-tree-portable.js

@@ -0,0 +1,245 @@
+import { setMaxListeners } from "node:events";
+import fs from "node:fs";
+import fsp, {} from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { assertStagedDirectoryCurrent, exactIdentityMatches, openStagedDirectory, } from "./staged-directory.js";
+function timestampSeconds(nanoseconds) {
+    // Dates discard sub-millisecond precision; negative numbers mean "now" in
+    // Node's utimes API. Numeric strings retain fractional, pre-epoch timestamps.
+    return String(Number(nanoseconds / 1000000000n) + Number(nanoseconds % 1000000000n) / 1e9);
+}
+/** Byte-copy adapter for the shared immutable-source, caller-owned namespace contract. */
+export async function copyOwnedTree(source, destination, options) {
+    const callerSignal = options.signal ? AbortSignal.any([options.signal]) : undefined;
+    const cancellation = new AbortController();
+    const signal = cancellation.signal;
+    setMaxListeners(options.concurrency, signal);
+    const pending = new Set();
+    const finishing = new Set();
+    const buffers = [];
+    let failure = undefined;
+    function recordFailure(value) {
+        failure ??= { value };
+        cancellation.abort(failure);
+    }
+    if (callerSignal)
+        callerSignal.onabort = () => recordFailure(callerSignal.reason);
+    async function schedule(operation, children) {
+        signal.throwIfAborted();
+        const task = operation()
+            .catch((error) => {
+            recordFailure(error);
+        })
+            .finally(() => {
+            pending.delete(task);
+            children.delete(task);
+        });
+        pending.add(task);
+        children.add(task);
+        if (pending.size >= options.concurrency)
+            await Promise.race(pending);
+        signal.throwIfAborted();
+    }
+    async function copyFile(from, to, stat) {
+        const input = await fsp.open(from, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        let output;
+        try {
+            const opened = await input.stat({ bigint: true });
+            if (!opened.isFile() || !exactIdentityMatches(stat, opened)) {
+                throw new FsSafeError("path-mismatch", "copy source changed while opening");
+            }
+            output = await fsp.open(to, "wx", 0o600);
+            if (options.copyFileContents) {
+                // napi-rs owns onabort. Each admitted file gets a separate signal; the
+                // shared failure signal is private, so callers cannot intercept its relay.
+                const fileCancellation = new AbortController();
+                const abortFile = () => fileCancellation.abort();
+                signal.addEventListener("abort", abortFile, { once: true });
+                try {
+                    signal.throwIfAborted();
+                    await options.copyFileContents(input.fd, output.fd, fileCancellation.signal);
+                }
+                finally {
+                    signal.removeEventListener("abort", abortFile);
+                    fileCancellation.signal.onabort = null;
+                }
+            }
+            else {
+                const buffer = buffers.pop() ??
+                    Buffer.allocUnsafe(process.platform === "win32" ? 1024 * 1024 : 128 * 1024);
+                try {
+                    let position = 0;
+                    while (true) {
+                        signal.throwIfAborted();
+                        const { bytesRead } = await input.read(buffer, 0, buffer.length, position);
+                        if (bytesRead === 0)
+                            break;
+                        let written = 0;
+                        while (written < bytesRead) {
+                            signal.throwIfAborted();
+                            const { bytesWritten } = await output.write(buffer, written, bytesRead - written, position + written);
+                            if (bytesWritten === 0)
+                                throw new Error("copy write made no progress");
+                            written += bytesWritten;
+                        }
+                        position += bytesRead;
+                    }
+                }
+                finally {
+                    buffers.push(buffer);
+                }
+            }
+            signal.throwIfAborted();
+            if (process.platform !== "win32")
+                await output.chmod(Number(stat.mode & 4095n));
+            await output.utimes(timestampSeconds(stat.atimeNs), timestampSeconds(stat.mtimeNs));
+        }
+        catch (error) {
+            recordFailure(error);
+        }
+        if (output) {
+            try {
+                await output.close();
+            }
+            catch (error) {
+                recordFailure(error);
+            }
+        }
+        try {
+            await input.close();
+        }
+        catch (error) {
+            recordFailure(error);
+        }
+    }
+    async function copyDirectory(from, to, parentChildren) {
+        signal.throwIfAborted();
+        const stat = await fsp.lstat(from, { bigint: true });
+        // Exclusive admission prevents merging a pre-existing directory, including
+        // any destination left by an unsuccessful native clone.
+        await fsp.mkdir(to, { mode: 0o700 });
+        const target = openStagedDirectory(to);
+        const children = new Set();
+        let original;
+        try {
+            original = openStagedDirectory(from);
+            if (!exactIdentityMatches(stat, original.receipt.identity)) {
+                throw new FsSafeError("path-mismatch", "copy source directory changed while opening");
+            }
+            for (const entry of await fsp.readdir(from, { withFileTypes: true })) {
+                signal.throwIfAborted();
+                assertStagedDirectoryCurrent(target.receipt);
+                assertStagedDirectoryCurrent(original.receipt);
+                const childSource = path.join(from, entry.name);
+                const childTarget = path.join(to, entry.name);
+                const child = await fsp.lstat(childSource, { bigint: true });
+                if (child.isDirectory()) {
+                    await copyDirectory(childSource, childTarget, children);
+                }
+                else if (child.isFile()) {
+                    await schedule(() => copyFile(childSource, childTarget, child), children);
+                }
+                else if (child.isSymbolicLink()) {
+                    const link = process.platform === "win32"
+                        ? await fsp.readlink(childSource)
+                        : await fsp.readlink(childSource, { encoding: "buffer" });
+                    let type;
+                    if (process.platform === "win32") {
+                        // Older Node releases infer link type from the destination, where a
+                        // relative directory target may not exist yet. Inspect the source.
+                        // lstat does not expose the Windows link's directory attribute, so
+                        // an unresolved source cannot be recreated with a proven type.
+                        try {
+                            type = (await fsp.stat(childSource)).isDirectory() ? "dir" : "file";
+                        }
+                        catch (error) {
+                            if (error instanceof Error &&
+                                "code" in error &&
+                                (error.code === "ENOENT" || error.code === "ENOTDIR" || error.code === "ELOOP")) {
+                                throw new FsSafeError("unsupported-platform", "byte copying cannot determine the type of an unresolved Windows symbolic link", { cause: error });
+                            }
+                            throw error;
+                        }
+                    }
+                    signal.throwIfAborted();
+                    await fsp.symlink(link, childTarget, type);
+                }
+                else {
+                    throw new FsSafeError("not-file", "tree copying does not support special files");
+                }
+            }
+        }
+        catch (error) {
+            recordFailure(error);
+            throw error;
+        }
+        finally {
+            // Traversal can advance into siblings while this directory's own files
+            // settle. Children retain their parents and finish metadata bottom-up.
+            const completion = (async () => {
+                try {
+                    await Promise.all(children);
+                    signal.throwIfAborted();
+                    if (original) {
+                        assertStagedDirectoryCurrent(original.receipt);
+                        assertStagedDirectoryCurrent(target.receipt);
+                        if (process.platform !== "win32")
+                            fs.fchmodSync(target.fd, Number(stat.mode & 4095n));
+                        await fsp.utimes(to, timestampSeconds(stat.atimeNs), timestampSeconds(stat.mtimeNs));
+                        assertStagedDirectoryCurrent(target.receipt);
+                    }
+                }
+                catch (error) {
+                    recordFailure(error);
+                }
+                if (original) {
+                    try {
+                        fs.closeSync(original.fd);
+                    }
+                    catch (error) {
+                        recordFailure(error);
+                    }
+                }
+                try {
+                    fs.closeSync(target.fd);
+                }
+                catch (error) {
+                    recordFailure(error);
+                }
+            })()
+                .catch((error) => {
+                recordFailure(error);
+            })
+                .finally(() => {
+                finishing.delete(completion);
+                parentChildren?.delete(completion);
+            });
+            finishing.add(completion);
+            parentChildren?.add(completion);
+            // Bound traversed-but-unsettled directories as well as file workers;
+            // ancestors stay open along the current traversal path.
+            if (finishing.size >= options.concurrency)
+                await Promise.race(finishing);
+        }
+        signal.throwIfAborted();
+    }
+    try {
+        callerSignal?.throwIfAborted();
+        await copyDirectory(source.receipt.realPath, destination);
+        await Promise.all(finishing);
+        signal.throwIfAborted();
+    }
+    catch (error) {
+        recordFailure(error);
+    }
+    finally {
+        await Promise.all(finishing);
+        if (callerSignal)
+            callerSignal.onabort = null;
+    }
+    if (failure)
+        throw failure.value;
+    options.signal?.throwIfAborted();
+    signal.throwIfAborted();
+}