@openclaw/openshell-sandbox 2026.9.3 → 2026.9.5

package/node_modules/@openclaw/fs-safe/dist/archive-zip-preflight.js

@@ -1,44 +1,13 @@
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, resolveExtractLimits, } from "./archive-limits.js";
-import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
-import { validateArchiveEntryPath } from "./archive-entry.js";
+import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
 export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
 export async function loadZipArchiveWithPreflight(buffer, limits) {
     const resolvedLimits = resolveExtractLimits(limits);
     if (buffer.byteLength > resolvedLimits.maxArchiveBytes) {
         throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
     }
-    const entryCount = admitZipBuffer(buffer, resolvedLimits);
-    const JSZip = await importOptionalJsZip();
-    let archive;
-    try {
-        archive = await JSZip.loadAsync(buffer);
-    }
-    catch (error) {
-        throw new ArchiveFormatError(`invalid ZIP archive: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
-    }
-    if (Object.keys(archive.files).length !== entryCount) {
-        throw new ArchiveSecurityError("entry-path", "zip archive contains duplicate or colliding entry names");
-    }
-    for (const name of Object.keys(archive.files))
-        validateArchiveEntryPath(name);
-    return archive;
-}
-async function importOptionalJsZip() {
-    try {
-        const module = await import("jszip");
-        const candidate = typeof module === "function" ? module : module.default;
-        if ((typeof candidate !== "object" && typeof candidate !== "function") ||
-            candidate === null ||
-            typeof candidate.loadAsync !== "function") {
-            throw new Error('Optional archive dependency "jszip" does not expose loadAsync().');
-        }
-        return candidate;
-    }
-    catch (err) {
-        throw missingOptionalArchiveDependencyError("jszip", err);
-    }
-}
-function missingOptionalArchiveDependencyError(packageName, cause) {
-    return new Error(`Optional archive dependency "${packageName}" is not installed. Install it to use ZIP archive helpers from @openclaw/fs-safe/archive.`, { cause });
+    const entries = [];
+    admitZipBuffer(buffer, resolvedLimits, entry => { entries.push(entry); });
+    return await loadAdmittedZipArchive(buffer, entries);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AA6MpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CjF"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIlE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AAiNpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDjF"}

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

@@ -10,7 +10,7 @@ import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchiveP
 import { createPipelineTimeoutError, waitForDeadline, withExtractionDeadline, } from "./archive-deadline.js";
 import { assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, resolveTarMeterLimits, } from "./archive-limits.js";
 import { assertPortableArchiveKind, resolveArchiveKind } from "./archive-kind.js";
-import { prepareArchiveDestinationDir, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+import { prepareArchiveDestinationGuard, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
 import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
 import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
 import { isZipSymlinkEntry, zipEntryDeclaredSize, zipEntryMode, } from "./archive-zip-entry.js";
@@ -22,6 +22,8 @@ import { stageArchiveFileForExtraction } from "./archive-input.js";
 import { getNativeBinding } from "./native.js";
 import { resolveArchiveFilteredEntryPolicy, shouldExtractArchiveEntry, } from "./archive-policy.js";
 import { writeSiblingTempFile } from "./sibling-temp.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
 export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
 export { readArchiveEntry } from "./archive-read.js";
@@ -50,7 +52,7 @@ function resolveZipOutputPath(params) {
     const canonicalPath = stripArchivePath(params.entryPath, 0);
     if (!canonicalPath)
         return null;
-    const relPath = stripArchivePath(canonicalPath, params.strip);
+    const relPath = params.strip === 0 ? canonicalPath : stripArchivePath(canonicalPath, params.strip);
     if (!relPath) {
         return null;
     }
@@ -77,6 +79,8 @@ async function writeZipFileEntry(params) {
             dir: path.dirname(destinationPath),
             chmodDir: false,
             mode: 0o600,
+            syncTempFile: false,
+            syncParentDir: false,
             writeTemp: async (tempPath) => {
                 tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o600);
                 const writable = tempHandle.createWriteStream();
@@ -120,7 +124,8 @@ async function extractZip(params) {
         deadline: params.deadline,
     });
     try {
-        const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
+        const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
+        const destinationRealDir = destinationGuard.realPath;
         params.deadline.check();
         const buffer = await fs.readFile(stagedArchive.path, { signal: params.deadline.signal });
         params.deadline.check();
@@ -134,7 +139,7 @@ async function extractZip(params) {
         await withStagedArchiveDestination({
             destinationRealDir,
             run: async (stagingDir) => {
-                const stagingRealDir = await fs.realpath(stagingDir);
+                const stagingRealDir = realpathSync.native(stagingDir);
                 const acceptedEntries = [];
                 for (const entry of entries) {
                     params.deadline.check();
@@ -185,9 +190,9 @@ async function extractZip(params) {
                 params.deadline.check();
                 await mergePlannedArchiveIntoDestination({
                     entries: acceptedEntries,
+                    durable: params.durable,
                     sourceDir: stagingRealDir,
-                    destinationDir: params.destDir,
-                    destinationRealDir,
+                    destinationGuard,
                     deadline: params.deadline,
                 });
                 params.deadline.check();
@@ -199,19 +204,24 @@ async function extractZip(params) {
     }
 }
 export async function extractArchive(params) {
+    const archivePath = params.archivePath;
+    const destDir = params.destDir;
     const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
-    const kind = params.kind ?? resolveArchiveKind(params.archivePath);
+    const kind = params.kind ?? resolveArchiveKind(archivePath);
     if (!kind) {
-        throw new Error(`unsupported archive: ${params.archivePath}`);
+        throw new Error(`unsupported archive: ${archivePath}`);
     }
     const label = kind === "zip" ? "extract zip" : "extract tar";
     const limits = resolveExtractLimits(params.limits);
     const tarLimits = resolveTarMeterLimits(limits);
     const native = getNativeBinding();
+    assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(destDir, "filesystem", "archive destination uses a Windows filesystem namespace alias");
     // Read the declared public fields before private adapters copy options: class
     // getters and inherited policy must survive identically on every backend.
     const options = {
-        archivePath: params.archivePath, destDir: params.destDir,
+        archivePath, destDir,
+        durable: params.durable,
         stripComponents: params.stripComponents, limits,
         entryModes: params.entryModes, entryFilter: params.entryFilter, onFiltered,
     };
@@ -244,9 +254,10 @@ async function extractWasmTar(params) {
     await inspectTar({ archivePath: params.archivePath, limits: tarLimits, signal: deadline.signal,
         onMember: (entry) => { manifest.push(entry); } });
     deadline.check();
-    const destinationRealDir = await prepareArchiveDestinationDir(options.destDir);
+    const destinationGuard = await prepareArchiveDestinationGuard(options.destDir);
+    const destinationRealDir = destinationGuard.realPath;
     await withStagedArchiveDestination({ destinationRealDir, run: async (stagingPath) => {
-            const stagingDir = await fs.realpath(stagingPath);
+            const stagingDir = realpathSync.native(stagingPath);
             const planEntry = createTarEntryPlanner({ ...options, rootDir: destinationRealDir, limits: params.limits });
             const accepted = manifest.flatMap((entry) => {
                 deadline.check();
@@ -262,14 +273,15 @@ async function extractWasmTar(params) {
                     if (member.kind === "file") {
                         await runPinnedWriteHelper({ rootPath: stagingDir, relativeParentPath: path.posix.dirname(member.path),
                             basename: path.posix.basename(member.path), mkdir: false, mode: 0o600, overwrite: false,
+                            sync: false,
                             maxBytes: member.size, input: { kind: "stream", stream: Readable.from(payload) } });
                     }
                     deadline.check();
                 },
             });
             deadline.check();
-            await mergePlannedArchiveIntoDestination({ entries: accepted, sourceDir: stagingDir,
-                destinationDir: options.destDir, destinationRealDir, deadline });
+            await mergePlannedArchiveIntoDestination({ entries: accepted, sourceDir: stagingDir, destinationGuard,
+                deadline, durable: options.durable });
             deadline.check();
         } });
 }

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

@@ -1,5 +1,12 @@
 import type { FileHandle } from "node:fs/promises";
 type ReadableFileHandle = Pick<FileHandle, "read">;
+export declare function readBoundedAsync(maxBytes: number, readChunk: (scratch: Buffer, length: number) => Promise<number>, options?: {
+    observeRegularFileSize?: () => number | undefined;
+    initialSize?: number;
+    createLimitError?: () => Error;
+    /** Keep the result outside Node's shared small-buffer allocation pool. */
+    unpooled?: boolean;
+}): Promise<Buffer>;
 /**
  * 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
@@ -8,6 +15,11 @@ type ReadableFileHandle = Pick<FileHandle, "read">;
 export declare function readFileHandleBounded(handle: ReadableFileHandle, maxBytes: number): Promise<Buffer>;
 /** Async bounded read from a numeric descriptor. The caller owns the descriptor. */
 export declare function readFileDescriptorBounded(fd: number, maxBytes: number): Promise<Buffer>;
+export declare function readBoundedSync(maxBytes: number, readChunk: (scratch: Buffer, length: number) => number, options?: {
+    observeRegularFileSize?: () => number | undefined;
+    initialSize?: number;
+    createLimitError?: () => Error;
+}): Buffer;
 /** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
 export declare function readFileDescriptorBoundedSync(fd: number, maxBytes: number): Buffer;
 export {};

package/node_modules/@openclaw/fs-safe/dist/bounded-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bounded-read.d.ts","sourceRoot":"","sources":["../src/bounded-read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,KAAK,kBAAkB,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AA+DnD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAMjB;AAyBD,oFAAoF;AACpF,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK7F;AAED,mFAAmF;AACnF,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAalF"}
+{"version":3,"file":"bounded-read.d.ts","sourceRoot":"","sources":["../src/bounded-read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAQnD,KAAK,kBAAkB,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AA8CnD,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/D,OAAO,GAAE;IACP,sBAAsB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,KAAK,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACf,GACL,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAMjB;AAyBD,oFAAoF;AACpF,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK7F;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,EACtD,OAAO,GAAE;IACP,sBAAsB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,KAAK,CAAC;CAC3B,GACL,MAAM,CAoBR;AAED,mFAAmF;AACnF,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMlF"}

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

@@ -2,50 +2,69 @@ import fs from "node:fs";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 const READ_CHUNK_BYTES = 64 * 1024;
-function createScratchBuffer(maxBytes) {
-    const initialReadBytes = Number.isFinite(maxBytes)
-        ? Math.min(READ_CHUNK_BYTES, maxBytes + 1)
-        : READ_CHUNK_BYTES;
-    return Buffer.allocUnsafe(Math.max(1, initialReadBytes));
+// 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 nextReadLength(total, maxBytes, capacity) {
-    return Number.isFinite(maxBytes)
-        ? Math.min(capacity, maxBytes - total + 1)
-        : capacity;
+function createScratchBuffer(maxBytes, allocate = Buffer.allocUnsafe) {
+    return allocate(Math.min(READ_CHUNK_BYTES, maxBytes + 1));
 }
-function appendChunk(params) {
-    const total = params.total + params.bytesRead;
-    if (total > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got at least ${total})`);
+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})`);
     }
-    params.chunks.push(Buffer.from(params.scratch.subarray(0, params.bytesRead)));
-    return total;
+    return next;
 }
-async function readBoundedAsync(maxBytes, readChunk, observeRegularFileSize) {
+export async function readBoundedAsync(maxBytes, readChunk, options = {}) {
     normalizeMaxBytes(maxBytes);
-    const chunks = [];
     let total = 0;
-    const size = observeRegularFileSize?.();
+    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 first = Buffer.allocUnsafe(Math.min(maxBytes, size) + 1);
-        const bytesRead = await readChunk(first, first.length);
+        const bytesRead = await readChunk(buffer, buffer.length);
         if (bytesRead === 0)
-            return first.subarray(0, 0);
-        // Short reads can occur before EOF. Only accept one when a fresh fd size
-        // observation proves we consumed at least the entire current file size.
-        const currentSize = bytesRead < first.length ? observeRegularFileSize?.() : undefined;
-        if (currentSize !== undefined && bytesRead >= currentSize)
-            return first.subarray(0, bytesRead);
-        total = appendChunk({ chunks, scratch: first, bytesRead, total, maxBytes });
+            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);
     }
-    const scratch = createScratchBuffer(maxBytes);
     while (true) {
-        const length = nextReadLength(total, maxBytes, scratch.length);
-        const bytesRead = await readChunk(scratch, length);
-        if (bytesRead === 0) {
-            return Buffer.concat(chunks, total);
-        }
-        total = appendChunk({ chunks, scratch, bytesRead, total, maxBytes });
+        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);
     }
 }
 /**
@@ -58,7 +77,7 @@ export async function readFileHandleBounded(handle, 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;
-    }, fd === undefined ? undefined : () => regularFileSize(fd));
+    }, { observeRegularFileSize: fd === undefined ? undefined : () => regularFileSize(fd) });
 }
 function regularFileSize(fd) {
     try {
@@ -87,20 +106,38 @@ export async function readFileDescriptorBounded(fd, maxBytes) {
     normalizeMaxBytes(maxBytes);
     return await readBoundedAsync(maxBytes, async (scratch, length) => {
         return await readDescriptorChunk(fd, scratch, length);
-    }, () => regularFileSize(fd));
+    }, { observeRegularFileSize: () => regularFileSize(fd) });
 }
-/** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
-export function readFileDescriptorBoundedSync(fd, maxBytes) {
+export function readBoundedSync(maxBytes, readChunk, options = {}) {
     normalizeMaxBytes(maxBytes);
-    const chunks = [];
-    const scratch = createScratchBuffer(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) {
-        const length = nextReadLength(total, maxBytes, scratch.length);
-        const bytesRead = fs.readSync(fd, scratch, 0, length, null);
-        if (bytesRead === 0) {
-            return Buffer.concat(chunks, total);
-        }
-        total = appendChunk({ chunks, scratch, bytesRead, total, maxBytes });
+        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/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.
+ * These are point-in-time facts, not authorization or a guarantee against later edits.
+ */
+export declare function readCloneFileMetadata(files: readonly string[]): Promise<(CloneFileMetadata | undefined)[]>;
+//# sourceMappingURL=clone-metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clone-metadata.d.ts","sourceRoot":"","sources":["../src/clone-metadata.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,OAAO,CAAC,CAAC,iBAAiB,GAAG,SAAS,CAAC,EAAE,CAAC,CA4B5C"}

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

@@ -0,0 +1,32 @@
+import { assertAbsolutePathInput } from "./absolute-path.js";
+import { requireNativeBinding } from "./native.js";
+/** Batched APFS metadata snapshots; absent on unsupported files or filesystems.
+ * 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 results = await requireNativeBinding().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/copy-file-input.d.ts

@@ -0,0 +1,22 @@
+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;
+//# sourceMappingURL=copy-file-input.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"copy-file-input.d.ts","sourceRoot":"","sources":["../src/copy-file-input.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAwB,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAItF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,aAAa,CAM5E;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAChD,QAAQ,EAAE,WAAW,GACpB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,aAAa,EACpB,QAAQ,CAAC,EAAE,MAAM,EACjB,oBAAoB,CAAC,EAAE,MAAM,IAAI,GAChC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CA+B3C;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAWnG"}

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,3 @@
+export type CopyCloneMode = "auto" | "always" | "never";
+export declare function resolveCopyCloneMode(mode: CopyCloneMode | undefined, defaultMode: CopyCloneMode): CopyCloneMode;
+//# sourceMappingURL=copy-policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"copy-policy.d.ts","sourceRoot":"","sources":["../src/copy-policy.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,WAAW,EAAE,aAAa,GACzB,aAAa,CAMf"}

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,15 @@
+import type { PinnedWriteParams, PublishedWriteIdentity } from "./pinned-write.js";
+export type RootCopyPublicationReceipt = Readonly<{
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}>;
+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 type CopyPublicationOptions = {
+    [onCopyPublication]?: PinnedWriteParams["verifyPublished"];
+};
+//# sourceMappingURL=copy-publication.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"copy-publication.d.ts","sourceRoot":"","sources":["../src/copy-publication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAGnF,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb,CAAC,CAAC;AAEH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,0BAA0B,KAAK,IAAI;IAIpD,WAAW,WAAW,sBAAsB,GAAG,IAAI;IAcnD,sBAAsB,QAAQ,OAAO,GAAG,IAAI;EAO/C;AAID,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAC7D,MAAM,MAAM,sBAAsB,GAAG;IACnC,CAAC,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;CAC5D,CAAC"}

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

@@ -0,0 +1,30 @@
+import { FsSafeError } from "./errors.js";
+export function createCopyPublicationObserver(path, notify) {
+    let rejected;
+    return {
+        onPublished(identity) {
+            const receipt = Object.freeze({ path, dev: identity.dev, ino: identity.ino });
+            try {
+                const result = notify?.(receipt);
+                if (result !== null && (typeof result === "object" || typeof result === "function") &&
+                    "then" in result && typeof result.then === "function") {
+                    void Promise.resolve(result).catch(() => undefined);
+                    throw new TypeError("onDestinationPublished must be synchronous");
+                }
+            }
+            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");

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

@@ -0,0 +1,9 @@
+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>;
+//# sourceMappingURL=copy-tree-portable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"copy-tree-portable.d.ts","sourceRoot":"","sources":["../src/copy-tree-portable.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAGL,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAQ/B,0FAA0F;AAC1F,wBAAsB,aAAa,CACjC,MAAM,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,EAC9C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IACP,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACtD,GACA,OAAO,CAAC,IAAI,CAAC,CAiNf"}