@openclaw/fs-safe 0.10.0 → 0.12.0

package/dist/sidecar-lock.js

@@ -37,9 +37,6 @@ function resolveManagerState(key) {
         // Backfill state created by fs-safe versions that predate reclaim guards.
         state.reclaimCleanupRegistered ??= false;
         state.reclaimGuards ??= new Set();
-        for (const held of state.held.values()) {
-            held.refCount ??= 1;
-        }
     }
     return state;
 }
@@ -163,6 +160,8 @@ async function releaseHeldLock(state, normalizedTargetPath, held, options = {})
         await held.releasePromise;
         return true;
     }
+    // Older package copies can add holders after this manager was constructed.
+    held.refCount ??= 1;
     if (options.force) {
         held.refCount = 0;
     }

package/dist/staged-directory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,KAAK,iBAAiB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAYvF;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAQ7E;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CA+BA"}
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,KAAK,iBAAiB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAYvF;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAQ7E;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CA+BA"}

package/dist/staged-directory.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
 export function exactIdentityMatches(expected, actual) {
     return ["dev", "ino"].every((key) => {
         const value = expected[key];
@@ -14,7 +15,7 @@ export function describeStagedDirectory(fd, pathname) {
     }
     const receipt = Object.freeze({
         path: path.resolve(pathname),
-        realPath: fs.realpathSync(pathname),
+        realPath: realpathSync(pathname),
         identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
     });
     assertStagedDirectoryCurrent(receipt);
@@ -23,7 +24,7 @@ export function describeStagedDirectory(fd, pathname) {
 export function assertStagedDirectoryCurrent(receipt) {
     const current = fs.lstatSync(receipt.path, { bigint: true });
     if (!current.isDirectory() || !exactIdentityMatches(receipt.identity, current) ||
-        fs.realpathSync(receipt.path) !== receipt.realPath) {
+        realpathSync(receipt.path) !== receipt.realPath) {
         throw new FsSafeError("path-mismatch", "staging directory pathname changed");
     }
 }
@@ -37,7 +38,7 @@ export function openStagedDirectory(directory) {
     if (!before.isDirectory()) {
         throw new FsSafeError("not-file", "staging parent must be a real directory");
     }
-    if (expected && (!exactIdentityMatches(expected, before) || fs.realpathSync(pathname) !== expected.realPath)) {
+    if (expected && (!exactIdentityMatches(expected, before) || realpathSync(pathname) !== expected.realPath)) {
         throw new FsSafeError("path-mismatch", "stale staging directory receipt");
     }
     const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);

package/dist/temp-target.d.ts

@@ -1,3 +1,4 @@
+import fsSync from "node:fs";
 export type TempFile = {
     dir: string;
     path: string;
@@ -5,6 +6,12 @@ export type TempFile = {
     cleanup: () => Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 };
+type TempFileOptions = {
+    rootDir?: string;
+    prefix: string;
+    fileName?: string;
+    onCleanupError?: (error: unknown) => void;
+};
 export declare function sanitizeTempFileName(fileName: string): string;
 export declare function buildRandomTempFilePath(params: {
     rootDir?: string;
@@ -13,16 +20,11 @@ export declare function buildRandomTempFilePath(params: {
     now?: number;
     uuid?: string;
 }): string;
-export declare function tempFile(params: {
-    rootDir?: string;
-    prefix: string;
-    fileName?: string;
-    onCleanupError?: (error: unknown) => void;
-}): Promise<TempFile>;
-export declare function withTempFile<T>(params: {
-    rootDir?: string;
-    prefix: string;
-    fileName?: string;
-    onCleanupError?: (error: unknown) => void;
-}, fn: (tmpPath: string) => Promise<T>): Promise<T>;
+export declare function createOwnedTempFile(params: TempFileOptions): Promise<{
+    target: TempFile;
+    identity: Readonly<Pick<fsSync.BigIntStats, "dev" | "ino">>;
+}>;
+export declare function tempFile(params: TempFileOptions): Promise<TempFile>;
+export declare function withTempFile<T>(params: TempFileOptions, fn: (tmpPath: string) => Promise<T>): Promise<T>;
+export {};
 //# sourceMappingURL=temp-target.d.ts.map

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyCD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAS7B,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,CAAC;AA8DF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyCD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC;IAC1E,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;CAC7D,CAAC,CA2BD;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEzE;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { suffixWindowsReservedDeviceName } from "./filename.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { assertSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
@@ -57,9 +58,10 @@ function sanitizeExtension(extension) {
     return token ? `.${token}` : "";
 }
 export function sanitizeTempFileName(fileName) {
-    return sanitizeSafePathSegment(path.basename(fileName), "download.bin", {
+    const sanitized = sanitizeSafePathSegment(path.basename(fileName), "download.bin", {
         allowDotPrefix: true,
     });
+    return suffixWindowsReservedDeviceName(sanitized);
 }
 export function buildRandomTempFilePath(params) {
     const rootDir = resolveTempRoot(params.rootDir);
@@ -106,7 +108,7 @@ async function cleanupTempDir(dir, identity, onCleanupError) {
 function resolveTempRoot(rootDir) {
     return path.resolve(rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" }));
 }
-export async function tempFile(params) {
+export async function createOwnedTempFile(params) {
     const rootDir = resolveTempRoot(params.rootDir);
     const prefix = `${sanitizePrefix(params.prefix)}-`;
     const dir = await fs.mkdtemp(path.join(rootDir, prefix));
@@ -124,13 +126,19 @@ export async function tempFile(params) {
         }
     };
     return {
-        dir,
-        path: file(),
-        file,
-        cleanup,
-        [Symbol.asyncDispose]: cleanup,
+        target: {
+            dir,
+            path: file(),
+            file,
+            cleanup,
+            [Symbol.asyncDispose]: cleanup,
+        },
+        identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
     };
 }
+export async function tempFile(params) {
+    return (await createOwnedTempFile(params)).target;
+}
 export async function withTempFile(params, fn) {
     const target = await tempFile(params);
     try {

package/dist/trash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAkLF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAcjB"}
+{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAkLF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAcjB"}

package/dist/trash.js

@@ -3,6 +3,8 @@ import os from "node:os";
 import path from "node:path";
 import { sameFileIdentity } from "./file-identity.js";
 import { guardedRenameSync, guardedRmSync } from "./guarded-mutation.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const TRASH_DESTINATION_COLLISION_CODES = new Set(["EEXIST", "ENOTEMPTY", "ERR_FS_CP_EEXIST"]);
 const TRASH_DESTINATION_RETRY_LIMIT = 4;
@@ -26,7 +28,7 @@ function resolveAllowedTrashRoots(allowedRoots) {
         try {
             // Keep both spellings: broken symlink targets cannot be realpathed and
             // may only compare equal to the caller's lexical allowed root.
-            return [path.resolve(fs.realpathSync.native(root)), lexicalRoot];
+            return [path.resolve(realpathSync.native(root)), lexicalRoot];
         }
         catch {
             return [lexicalRoot];
@@ -36,7 +38,7 @@ function resolveAllowedTrashRoots(allowedRoots) {
 }
 function resolveTrashTargetPath(targetPath) {
     try {
-        return { path: path.resolve(fs.realpathSync.native(targetPath)), resolved: true };
+        return { path: path.resolve(realpathSync.native(targetPath)), resolved: true };
     }
     catch {
         // Broken symlinks are valid trash targets. Fall back to the lexical path,
@@ -75,13 +77,13 @@ function assertTrashTargetGuard(guard) {
 function resolveTrashDir() {
     const homeDir = os.homedir();
     const trashDir = path.join(homeDir, ".Trash");
-    fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+    fs.mkdirSync(recursiveMkdirPath(trashDir), { recursive: true, mode: 0o700 });
     const trashDirStat = fs.lstatSync(trashDir);
     if (!trashDirStat.isDirectory() || trashDirStat.isSymbolicLink()) {
         throw new Error(`Refusing to use non-directory/symlink trash directory: ${trashDir}`);
     }
-    const realHome = path.resolve(fs.realpathSync.native(homeDir));
-    const resolvedTrashDir = path.resolve(fs.realpathSync.native(trashDir));
+    const realHome = path.resolve(realpathSync.native(homeDir));
+    const resolvedTrashDir = path.resolve(realpathSync.native(trashDir));
     if (resolvedTrashDir === realHome || !isSameOrChildPath(resolvedTrashDir, realHome)) {
         throw new Error(`Trash directory escaped home directory: ${trashDir}`);
     }

package/dist/unicode-path.d.ts

@@ -0,0 +1,3 @@
+export declare function lowerCaseNfc(value: string): string;
+export declare function maxNormalizedUtf8Bytes(value: string, includeRaw?: boolean): number;
+//# sourceMappingURL=unicode-path.d.ts.map

package/dist/unicode-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unicode-path.d.ts","sourceRoot":"","sources":["../src/unicode-path.ts"],"names":[],"mappings":"AAEA,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,UAAQ,GAAG,MAAM,CAUhF"}

package/dist/unicode-path.js

@@ -0,0 +1,13 @@
+const NON_ASCII = /[^\x00-\x7f]/;
+export function lowerCaseNfc(value) {
+    return NON_ASCII.test(value) ? value.normalize("NFC").toLowerCase().normalize("NFC") : value.toLowerCase();
+}
+export function maxNormalizedUtf8Bytes(value, includeRaw = false) {
+    const nfc = value.normalize("NFC");
+    const bytes = Buffer.byteLength(nfc, "utf8");
+    const maximum = includeRaw && nfc !== value ? Math.max(bytes, Buffer.byteLength(value, "utf8")) : bytes;
+    // ASCII NFC output also has identical NFD and one UTF-8 byte per code unit.
+    if (bytes === nfc.length)
+        return maximum;
+    return Math.max(maximum, Buffer.byteLength(value.normalize("NFD"), "utf8"));
+}

package/dist/walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AAgFF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CAyDjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CAyD1C"}
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAK7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AA+EF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CA0DjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CA0D1C"}

package/dist/walk.js

@@ -1,6 +1,7 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { realpathSync } from "./realpath.js";
 function validateWalkBudget(name, value) {
     if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
         throw new RangeError(`${name} must be a non-negative safe integer`);
@@ -28,11 +29,10 @@ function shouldStop(result, options) {
 }
 function buildEntry(params) {
     const fullPath = params.fullPath;
-    const relativePath = path.relative(params.rootDir, fullPath) || params.dirent.name;
     return {
         name: params.dirent.name,
         path: fullPath,
-        relativePath,
+        relativePath: params.relativePath,
         depth: params.depth,
         kind: params.kind ?? kindForDirent(params.dirent),
         dirent: params.dirent,
@@ -78,12 +78,12 @@ export function walkDirectorySync(rootDir, options = {}) {
         failedDirs: [],
     };
     const visitedDirs = new Set();
-    function visit(dir, depth) {
+    function visit(dir, relativeDir, depth) {
         if (options.maxDepth !== undefined && depth > options.maxDepth)
             return;
         let realDir;
         try {
-            realDir = fsSync.realpathSync(dir);
+            realDir = realpathSync(dir);
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
@@ -110,20 +110,21 @@ export function walkDirectorySync(rootDir, options = {}) {
             const kind = resolveKind(fullPath, dirent, symlinks);
             if (!kind)
                 continue;
-            const entry = buildEntry({ rootDir: root, fullPath, dirent, depth, kind });
+            const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
+            const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
             if (options.include?.(entry) ?? true) {
                 result.entries.push(entry);
             }
             if (kind === "directory" &&
                 (options.maxDepth === undefined || depth < options.maxDepth) &&
                 (options.descend?.(entry) ?? true)) {
-                visit(fullPath, depth + 1);
+                visit(fullPath, relativePath, depth + 1);
                 if (result.truncated)
                     return;
             }
         }
     }
-    visit(root, 1);
+    visit(root, "", 1);
     return result;
 }
 export async function walkDirectory(rootDir, options = {}) {
@@ -137,12 +138,12 @@ export async function walkDirectory(rootDir, options = {}) {
         failedDirs: [],
     };
     const visitedDirs = new Set();
-    async function visit(dir, depth) {
+    async function visit(dir, relativeDir, depth) {
         if (options.maxDepth !== undefined && depth > options.maxDepth)
             return;
         let realDir;
         try {
-            realDir = fsSync.realpathSync.native(dir);
+            realDir = realpathSync.native(dir);
         }
         catch (error) {
             recordFailedDir(result, root, dir, depth, error);
@@ -169,19 +170,20 @@ export async function walkDirectory(rootDir, options = {}) {
             const kind = resolveKind(fullPath, dirent, symlinks);
             if (!kind)
                 continue;
-            const entry = buildEntry({ rootDir: root, fullPath, dirent, depth, kind });
+            const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
+            const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
             if (options.include?.(entry) ?? true) {
                 result.entries.push(entry);
             }
             if (kind === "directory" &&
                 (options.maxDepth === undefined || depth < options.maxDepth) &&
                 (options.descend?.(entry) ?? true)) {
-                await visit(fullPath, depth + 1);
+                await visit(fullPath, relativePath, depth + 1);
                 if (result.truncated)
                     return;
             }
         }
     }
-    await visit(root, 1);
+    await visit(root, "", 1);
     return result;
 }

package/dist/write-file-handle.d.ts

@@ -1,6 +1,7 @@
 import type { FileHandle } from "node:fs/promises";
 export declare function writeAllToFile(target: FileHandle | number, data: string | Uint8Array, options?: {
     encoding?: BufferEncoding;
+    position?: number;
     assertBeforeMutation?: () => void;
 }): Promise<void>;
 //# sourceMappingURL=write-file-handle.d.ts.map

package/dist/write-file-handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-file-handle.d.ts","sourceRoot":"","sources":["../src/write-file-handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAC7E,OAAO,CAAC,IAAI,CAAC,CAmBf"}
+{"version":3,"file":"write-file-handle.d.ts","sourceRoot":"","sources":["../src/write-file-handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAChG,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/write-file-handle.js

@@ -6,17 +6,18 @@ export async function writeAllToFile(target, data, options = {}) {
     let offset = 0;
     while (offset < buffer.byteLength) {
         const length = Math.min(WRITE_CHUNK_BYTES, buffer.byteLength - offset);
+        const position = options.position === undefined ? null : options.position + offset;
         options.assertBeforeMutation?.();
         const written = typeof target === "number"
             ? await new Promise((resolve, reject) => {
-                fs.write(target, buffer, offset, length, null, (error, bytesWritten) => {
+                fs.write(target, buffer, offset, length, position, (error, bytesWritten) => {
                     if (error)
                         reject(error);
                     else
                         resolve(bytesWritten);
                 });
             })
-            : (await target.write(buffer, offset, length, null)).bytesWritten;
+            : (await target.write(buffer, offset, length, position)).bytesWritten;
         if (written <= 0) {
             throw new FsSafeError("helper-failed", "file write made no progress");
         }

package/docs/advanced.md

@@ -32,6 +32,7 @@ The exports group into a handful of themes. Each documented helper has its own p
 | `resolveWritablePathWithinRoot` | – | Resolve a write target inside a root. |
 | `resolveRootPath`, `resolveRootPathSync`, `ResolvedRootPath`, `ROOT_PATH_ALIAS_POLICIES`, `RootPathAliasPolicy` | – | Resolve a root directory honoring alias policy. |
 | `resolvePathViaExistingAncestorSync` | – | Walk to an existing ancestor for paths whose tail does not yet exist. |
+| `probePathCaseInsensitiveSync`, `ProbePathCaseOptions` | [path-case.md](path-case.md) | Observe local ASCII-case behavior with explicit read-only mode and owned temporary-probe cleanup. |
 
 `ensureDirectoryWithinRoot({ rootDir, requestedPath, scopeLabel, defaultDirName?, mode? })`
 returns `{ ok: true, path }` or `{ ok: false, error: string, diagnostic?: FsSafeError }`.
@@ -66,9 +67,12 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 |---|---|---|
 | `readFileDescriptorBounded`, `readFileDescriptorBoundedSync`, `readFileHandleBounded` | – | Incremental whole-file reads for already-open descriptors/handles. They consume at most `maxBytes + 1`, do not close the input, and throw `FsSafeError("too-large")` on overflow. |
 | `readFileWindowFully`, `readFileWindowFullySync`, `ReadFileWindowOptions` | [positional-read.md](positional-read.md) | Fill a caller-owned buffer at an explicit file position, completing short reads and returning the EOF count without moving or closing the descriptor. |
+| `copyFileHandle`, `CopyFileHandleOptions` | [copy.md](copy.md#borrowed-filehandle-transfers) | Copy caller-owned regular-file handles from position zero with byte limits, settled cancellation, and a synchronous source observer; preserves cursors and leaves publication and cleanup to the caller. |
+| `overwriteFileHandle`, `OverwriteFileHandleOptions` | [in-place-write.md](in-place-write.md) | Overwrite a borrowed read/write handle with prefix-only preparation and best-effort rollback; preserves its inode, cursor, and caller-owned lifetime. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
+| `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |
 | `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
@@ -92,6 +96,8 @@ byte limit. Continuation buffers grow only after filling with actual bytes,
 up to the byte budget plus its probe; file-size hints cannot force that growth.
 Unknown-size inputs start with at most 64 KiB. This avoids per-chunk copies and
 a final concatenation when a file exceeds the initial allocation.
+Regular files that report a size of zero, such as virtual files, continue through
+positive short reads until actual EOF or byte-limit overflow.
 
 The bounded descriptor helpers start at the descriptor's current offset and
 leave ownership with the caller. They are intended for the second half of a
@@ -129,7 +135,7 @@ component is followed by another segment, both helpers throw
 
 | Export | Page | Notes |
 |---|---|---|
-| `safeDirName`, `safePathSegmentHashed`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories from caller-supplied identifiers. |
+| `safeDirName`, `safePathSegmentHashed`, `safePathSegmentHashedV2`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories; use V2 for untrusted identifier mappings. |
 | `sanitizeUntrustedFileName` | [filename.md](filename.md) | Coerce an untrusted string into a safe filename. |
 | `resolveHomeRelativePath` | – | Expand a leading `~` before resolving `.` and `..`; tildes inside relative paths stay literal. |
 

package/docs/archive.md

@@ -126,6 +126,12 @@ untrusted authority rejects explicitly instead of silently accepting a wrong
 mode. Other unsupported search-only routes also fail closed. Windows retains
 its existing bounded lack of POSIX mode enforcement.
 
+Extraction and TAR inspection first copy the admitted source into a private
+staging file. This copy reuses at most 512 KiB of scratch space, reduced for
+small inputs and capped by the archive byte limit plus one overflow-probe byte.
+Each read stays within the remaining budget plus that probe; deadline checks
+surround reads, and short writes finish before the buffer is reused.
+
 Native extraction is deliberately split into two phases. Rust first reports an
 entry manifest without creating paths. TypeScript validates paths, applies
 `stripComponents`, filters, limits, and mode policy, then passes an explicit
@@ -133,7 +139,13 @@ accepted-entry plan back to Rust. Rust owns raw-stream admission, decompression,
 and fd-relative `mkdirBeneath`/exclusive-open writes. This keeps filter policy identical
 between native and JavaScript paths rather than reimplementing it in Rust.
 
-ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless separator and dot-component equivalence is allowed only after validation. Ordinary legacy filename decoding remains backend-selected.
+ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless separator and dot-component equivalence is allowed only after validation. Ordinary legacy filename decoding remains backend-selected. Native ZIP extraction groups nearby metadata reads into at most two 4 KiB read-ahead buffers per admission pass; larger records retain separately bounded reads. Buffered record views remain stable across eviction, and cached work periodically yields for deadline checks.
+
+Within one ZIP entry, identical local and central name bytes reuse the same
+decoded validation. Unicode Path admission is shared only when both the raw names
+and the complete Unicode fields match; different fields still verify their own
+CRC and interpretation. Shared backing memory is checked independently. Decoded
+name validation is not reused across entries or archives.
 
 `stripComponents` removes leading nonempty, non-`.` path components after
 normalizing separators. For example, `./pkg/hello.txt` with
@@ -222,6 +234,13 @@ record and are then cleared; local PAX on unsupported types and GNU sparse
 
 If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). Archive inputs must remain regular files from preview through descriptor admission; POSIX opens are no-follow and nonblocking, so a FIFO swap cannot stall before deadline checks resume. A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline. Non-mutating work rejects promptly when the budget expires. If a live destination mutation is already in flight, rejection waits only for that mutation and any rollback to finish; no later destination mutation can begin.
 
+Extraction captures the destination's lossless filesystem identity before any
+entry filter runs and retains that capability through final publication. If a
+filter or concurrent actor renames or replaces the destination, extraction
+rejects with `destination-symlink-traversal` before publishing into the
+replacement. This check uses bigint device and inode identities so large native
+identifiers cannot compare equal after JavaScript number rounding.
+
 The destination merge is nontransactional: each file is published atomically,
 but completed files and directories can remain when a later copy, post-copy
 check, mode application, or deadline fails. This also applies to
@@ -354,7 +373,9 @@ bypass validation. Decompression remains streaming; no complete decoded archive
 is retained in memory or written to a decoded spool.
 
 The WASM transport has a fixed 64 KiB input buffer, one pending member event,
-and a 256 MiB maximum linear memory per isolated parser instance. Metadata is
+and a 256 MiB maximum linear memory per isolated parser instance. JavaScript
+gzip decoding emits chunks of at most 64 KiB for both staged files and buffered
+inputs, matching that input window. Metadata is
 bounded before allocation; allocation failure rejects. Stream backpressure
 bounds queued chunks, and completion/error destroys the instance's parser
 state. The manifest retains the existing charged budget below; linear memory
@@ -574,7 +595,9 @@ inputs retain the archive subpath's 256 MiB compressed-input ceiling.
 With a native binding it uses the same Rust decoders as extraction, including
 zstd and bzip2 TAR. Without native it retains the JS ZIP/TAR/gzip implementation.
 Archive member reads retain their private in-memory input without a disk
-snapshot. The native ZIP reader retains the private allocation and parsed directory across worker-thread
+snapshot. JavaScript ZIP member reads reuse their completed physical admission
+when loading the decoder, which still checks its decoded names and entry count.
+The native ZIP reader retains the private allocation and parsed directory across worker-thread
 inspection and reading without an extra archive-byte copy.
 Decompression still allocates its bounded output; Node receives that native
 allocation without another copy where external buffers are supported.
@@ -582,8 +605,11 @@ Native TAR retains the fully admitted member offsets alongside the same input
 allocation. Plain TAR copies only the selected payload range after full archive
 validation. Gzip, zstd, and bzip2 replay bounded decompression and still validate
 all framing, trailers, and physical padding before returning. The JavaScript
-TAR/gzip fallback streams views of the private input into the shared WASM parser
-for admission and replay; WASM transport and selected output still require copies.
+TAR/gzip fallback copies each input window into WASM once, consuming member
+events at offsets within that window. After full admission, plain TAR copies the
+selected range directly from its private snapshot; gzip still replays bounded
+decompression through the parser. WASM transport and selected output still
+require copies.
 Returned buffers own their bytes, so changing a result cannot modify an archive
 reader or retain an unrelated part of the input through its backing ArrayBuffer.
 

package/docs/atomic.md

@@ -40,7 +40,7 @@ type ReplaceFileAtomicOptions = {
   content: string | Uint8Array;
   dirMode?: number;                 // parent-directory mode (POSIX; default 0o700)
   mode?: number;                    // new-file mode (default 0o600)
-  preserveExistingMode?: boolean;   // copy existing mode; default false
+  preserveExistingMode?: boolean;   // inherit existing regular-file rwx bits; default false
   tempPrefix?: string;              // default ".fs-safe-replace"
   renameMaxRetries?: number;        // EBUSY retries; default 0
   renameRetryBaseDelayMs?: number;  // exponential base; default 50
@@ -57,6 +57,17 @@ type ReplaceFileAtomicOptions = {
 };
 ```
 
+`preserveExistingMode` snapshots only the ordinary rwx bits (`0o777`) from an
+existing non-symlink regular destination. A final symlink fails with
+`FsSafeError("symlink")`; a directory or other non-regular destination fails
+with `FsSafeError("not-file")`. Set-user-ID, set-group-ID, and sticky bits are
+never inherited. Mode inheritance does not copy ownership, ACLs, extended
+attributes, or exact destination identity. Rename publication creates a new
+inode; an in-place copy fallback can retain metadata already attached to its
+pinned destination. The snapshot does not make replacement a compare-and-swap
+operation, so the destination parent must still be protected from untrusted
+concurrent namespace mutation.
+
 ### `beforeRename`
 
 Runs after the temp file is fully written and before the rename. Use it to take a backup snapshot, capture the about-to-be-replaced contents, or notify an observer. The helper retains the staged descriptor and exact bigint identity across the hook; replacing, deleting, hardlinking, or changing the temp entry to a non-regular file is rejected before publication:
@@ -135,6 +146,11 @@ than `maxRestoreBytes` fails with `too-large` before mutation. A missing
 destination has no original to restore and follows the exclusive-create copy
 fallback.
 
+Restore snapshots use the pinned file's size as an allocation hint, with an
+initial allocation capped at 16 MiB plus the overflow byte. Reads continue
+through short reads and EOF, grow only as data arrives, and enforce the same
+`maxRestoreBytes` budget even if the destination grows after its size was read.
+
 ### Sync variant
 
 `replaceFileAtomicSync` accepts the same base options, a synchronous

package/docs/config.md

@@ -65,6 +65,7 @@ type FsSafeLockConfig = {
 Set process-wide defaults for sidecar lock options. This does **not** turn locking on globally; callers still need to pass `lock: true` or a lock options object for the specific JSON store/resource that needs cross-process coordination.
 
 `staleRecovery` defaults to `"fail-closed"`. The opt-in `"remove-if-unchanged"` mode requires caller approval and serializes the final snapshot check and unlink with an exclusive `.reclaim` guard. A reclaim guard left by a killed reclaimer fails closed and requires externally coordinated cleanup.
+`staleMs` must be non-negative and not `NaN`; `Infinity` disables age-based staleness.
 
 For a daemon that should wait briefly for normal contention but never delete a
 stale owner without per-lock approval:

package/docs/contributing.md

@@ -42,6 +42,32 @@ Vitest. Tests live in `test/` and follow `*.test.ts`. Run a single file with:
 pnpm test test/archive.test.ts
 ```
 
+Guest filesystem tests and package smoke also need `python3` on Linux and
+macOS. They execute the exported source on synthetic files; Windows checks
+the import surface and leaves POSIX execution to the Linux/macOS lanes.
+After building on Linux, `node scripts/check-pack.mjs --guest-cross-device`
+also proves an installed-package directory move from temporary storage to
+`/dev/shm`; the command requires those locations to be different filesystems.
+
+With Bun 1.4.2 installed, build the host addon and run the native compatibility
+lane in real Bun workers, then exercise the built package with JIT disabled:
+
+```bash
+pnpm native:build
+pnpm test:bun:native
+bun --jitless scripts/bun-native-proof.mjs
+```
+
+Keep the Node/pnpm build toolchain above. CI runs the native compatibility lane
+on Linux, macOS, and Windows. The built-package proof checks `auto`/`require`,
+native-off loading policy, and a separate installation without the addon.
+
+`pnpm test:bun` runs the entire Node-oriented suite as a diagnostic. On released
+Bun, its explicit native-off and missing-helper cases include unsupported
+permission/path behavior described in [install](install.md#bun-runtime); this
+command is not a passing compatibility gate. Node CI retains every fallback
+assertion. Neither lane rewrites `off` to `auto` or marks defects as expected passes.
+
 Use `vi.mock` sparingly. Most tests should drive real disk operations in a `mkdtemp`-created scratch directory, asserting on observable behavior. The library has [test hooks](testing.md) for the rare cases where you need to inject a TOCTOU race deterministically.
 
 Vitest timeouts do not cancel filesystem promises. Shared fixtures with expensive
@@ -50,7 +76,10 @@ setup use `useSuiteFixture` from `test/helpers/suite-fixture.ts`: setup has a se
 removing directories. Run shared-state corpora sequentially with a deadline per
 payload. Keep child-process liveness limits separate from fixture preparation.
 The Windows CI slow-copy proof runs the real package-copy process-exit test with a
-six-second copy delay, retaining its four-second child deadline:
+16-second copy delay, a 10-second child deadline, a 15-second test deadline, and
+60-second setup and teardown hook budgets. Other hosts retain the ordinary
+six-second delay, four-second child deadline, five-second test deadline, and
+30-second hook budgets:
 
 ```bash
 pnpm build
@@ -123,7 +152,9 @@ collection uses the actual seven collected native tarballs instead. Run it with
 `pnpm package:collect` after assembling all seven real bindings; missing targets
 fail collection. `pnpm package:collect --allow-host-only` exercises the same
 lifecycle boundary locally but proves only the host. Both collection commands
-require the pnpm lifecycle CLI path; direct `node` invocation is unsupported. Archive
+require the pnpm lifecycle CLI path; JavaScript CLIs run through Node and standalone
+`@pnpm/exe` binaries run directly. Shell/cmd shims and PATH fallback are not used;
+direct `node` invocation without lifecycle metadata is unsupported. Archive
 codecs and their dependencies are packed from the installed dependency graph.
 
 PR CI builds and executes four host targets: Linux x64 glibc, Linux x64 musl