@openclaw/openshell-sandbox 2026.10.2 → 2026.10.5-beta.2

package/dist/index.js

@@ -189,29 +189,24 @@ var OpenShellFsBridge = class {
 		return entries;
 	}
 	async writeFile(params) {
-		const target = this.resolveTarget(params);
-		const hostPath = target.hostPath;
-		this.ensureWritable(target, "write files");
-		const buffer = Buffer.isBuffer(params.data) ? params.data : Buffer.from(params.data, params.encoding ?? "utf8");
-		await (await root(target.mountHostRoot)).write(relativeToRoot(target, hostPath), buffer, {
-			mkdir: params.mkdir,
-			mutationSymlinks: "reject"
-		});
-		await this.backend.syncLocalPathToRemote(hostPath, target.containerPath);
+		await this.writeLocalFile(params, "write");
 	}
 	async createFileExclusive(params) {
+		return this.writeLocalFile(params, "create");
+	}
+	async writeLocalFile(params, method) {
 		const target = this.resolveTarget(params);
 		const hostPath = target.hostPath;
-		this.ensureWritable(target, "create files");
+		this.ensureWritable(target, method === "create" ? "create files" : "write files");
 		const buffer = Buffer.isBuffer(params.data) ? params.data : Buffer.from(params.data, params.encoding ?? "utf8");
 		const root$2 = await root(target.mountHostRoot);
 		try {
-			await root$2.create(relativeToRoot(target, hostPath), buffer, {
-				mkdir: params.mkdir !== false,
+			await root$2[method](relativeToRoot(target, hostPath), buffer, {
+				mkdir: method === "create" ? params.mkdir !== false : params.mkdir,
 				mutationSymlinks: "reject"
 			});
 		} catch (error) {
-			if (error instanceof FsSafeError && error.code === "already-exists") return "exists";
+			if (method === "create" && error instanceof FsSafeError && error.code === "already-exists") return "exists";
 			throw error;
 		}
 		await this.backend.syncLocalPathToRemote(hostPath, target.containerPath);
@@ -366,25 +361,25 @@ var OpenShellFsBridge = class {
 		}
 		const cwd = params.cwd ? path.resolve(params.cwd) : workspaceRoot;
 		const hostPath = path.isAbsolute(input) ? path.resolve(input) : path.resolve(cwd, input);
-		for (const mount of readOnlyMounts) if (isPathInside(mount.hostPath, hostPath)) {
+		for (const mount of [
+			...readOnlyMounts,
+			{
+				hostPath: workspaceRoot,
+				containerPath: workspaceContainerRoot
+			},
+			...hasAgentMount ? [{
+				hostPath: agentRoot,
+				containerPath: agentContainerRoot
+			}] : []
+		]) if (isPathInside(mount.hostPath, hostPath)) {
 			const relative = path.relative(mount.hostPath, hostPath).split(path.sep).join(path.posix.sep);
-			return expectResolvedContainerTarget(resolveContainerTarget(path.posix.join(mount.containerPath, relative)), input);
-		}
-		if (isPathInside(workspaceRoot, hostPath)) {
-			const relative = path.relative(workspaceRoot, hostPath).split(path.sep).join(path.posix.sep);
-			return expectResolvedContainerTarget(resolveContainerTarget(path.posix.join(workspaceContainerRoot, relative)), input);
-		}
-		if (hasAgentMount && isPathInside(agentRoot, hostPath)) {
-			const relative = path.relative(agentRoot, hostPath).split(path.sep).join(path.posix.sep);
-			return expectResolvedContainerTarget(resolveContainerTarget(path.posix.join(agentContainerRoot, relative)), input);
+			const target = resolveContainerTarget(path.posix.join(mount.containerPath, relative));
+			if (!target) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${input}`);
+			return target;
 		}
 		throw new Error(`Path escapes sandbox root (${workspaceRoot}): ${params.filePath}`);
 	}
 };
-function expectResolvedContainerTarget(target, input) {
-	if (!target) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${input}`);
-	return target;
-}
 async function removeLocalRootPath(params) {
 	const root$4 = await root(params.target.mountHostRoot);
 	const relativePath = relativeToRoot(params.target, params.target.hostPath);
@@ -529,16 +524,6 @@ async function stageDirectoryContents(params) {
 const openShellWorkspaceOperations = new KeyedAsyncQueue();
 let openShellDetachedCreateSupport;
 const MATERIALIZED_SKILLS_REMOTE_PARTS = [".openclaw", "sandbox-skills"];
-function buildOpenShellDirectoryUploadArgs(params) {
-	return [
-		"sandbox",
-		"upload",
-		"--no-git-ignore",
-		params.sandboxName,
-		params.localPath,
-		`${normalizeRemotePath(params.remotePath)}/`
-	];
-}
 const REMOTE_MANAGED_ROOTS_EMPTY_SCRIPT = "for root in \"$@\"; do if [ -d \"$root\" ] && [ -n \"$(ls -A \"$root\")\" ]; then printf \"1\\n\"; exit 0; fi; done; printf \"0\\n\"";
 const OPEN_SHELL_GUEST_MUTATION_PYTHON = `
 import os, sys
@@ -973,19 +958,27 @@ var OpenShellSandboxBackendImpl = class {
 			target.root,
 			path.posix.dirname(target.relativePath) === "." ? "" : path.posix.dirname(target.relativePath)
 		] });
+		await this.uploadFileToRemote(localPath, remotePath);
+	}
+	async uploadFileToRemote(localPath, remotePath) {
+		await this.runCli([
+			"sandbox",
+			"upload",
+			"--no-git-ignore",
+			this.params.execContext.sandboxName,
+			localPath,
+			remotePath
+		], "openshell sandbox upload failed");
+	}
+	async runCli(args, failureMessage, timeoutMs) {
 		const result = await runOpenShellCli({
 			context: this.params.execContext,
-			args: [
-				"sandbox",
-				"upload",
-				"--no-git-ignore",
-				this.params.execContext.sandboxName,
-				localPath,
-				remotePath
-			],
-			cwd: this.params.createParams.workspaceDir
+			args,
+			cwd: this.params.createParams.workspaceDir,
+			...timeoutMs === void 0 ? {} : { timeoutMs }
 		});
-		if (result.code !== 0) throw new Error(result.stderr.trim() || "openshell sandbox upload failed");
+		if (failureMessage && result.code !== 0) throw new Error(result.stderr.trim() || failureMessage);
+		return result;
 	}
 	async runPinnedRemotePathMutation(params) {
 		return await this.runRemoteShellScript({
@@ -1034,15 +1027,11 @@ var OpenShellSandboxBackendImpl = class {
 		}
 	}
 	async ensureSandboxExistsInner() {
-		const getResult = await runOpenShellCli({
-			context: this.params.execContext,
-			args: [
-				"sandbox",
-				"get",
-				this.params.execContext.sandboxName
-			],
-			cwd: this.params.createParams.workspaceDir
-		});
+		const getResult = await this.runCli([
+			"sandbox",
+			"get",
+			this.params.execContext.sandboxName
+		]);
 		if (getResult.code === 0) {
 			if (this.params.legacyRuntimeAdopted) {
 				const phase = await this.resolveLegacyRuntimePhase();
@@ -1073,13 +1062,7 @@ var OpenShellSandboxBackendImpl = class {
 				"infinity"
 			] : ["--", "true"]
 		];
-		const createResult = await runOpenShellCli({
-			context: this.params.execContext,
-			args: createArgs,
-			cwd: this.params.createParams.workspaceDir,
-			timeoutMs: Math.max(this.params.execContext.config.timeoutMs, 3e5)
-		});
-		if (createResult.code !== 0) throw new Error(createResult.stderr.trim() || "openshell sandbox create failed");
+		await this.runCli(createArgs, "openshell sandbox create failed", Math.max(this.params.execContext.config.timeoutMs, 3e5));
 		this.remoteSeedPending = true;
 	}
 	async supportsDetachedSandboxCreation() {
@@ -1093,16 +1076,11 @@ var OpenShellSandboxBackendImpl = class {
 		let support = openShellDetachedCreateSupport?.key === cliIdentity ? openShellDetachedCreateSupport.promise : void 0;
 		if (!support) {
 			support = (async () => {
-				const result = await runOpenShellCli({
-					context: this.params.execContext,
-					args: [
-						"sandbox",
-						"create",
-						"--help"
-					],
-					cwd: this.params.createParams.workspaceDir
-				});
-				if (result.code !== 0) throw new Error(result.stderr.trim() || "openshell sandbox create capability check failed");
+				const result = await this.runCli([
+					"sandbox",
+					"create",
+					"--help"
+				], "openshell sandbox create capability check failed");
 				return /^\s*--detach(?:\s|$)/mu.test(result.stdout);
 			})();
 			openShellDetachedCreateSupport = {
@@ -1120,20 +1098,16 @@ var OpenShellSandboxBackendImpl = class {
 	async resolveLegacyRuntimePhase() {
 		const pageSize = 100;
 		for (let offset = 0;; offset += pageSize) {
-			const listResult = await runOpenShellCli({
-				context: this.params.execContext,
-				args: [
-					"sandbox",
-					"list",
-					"--limit",
-					String(pageSize),
-					"--offset",
-					String(offset),
-					"--output",
-					"json"
-				],
-				cwd: this.params.createParams.workspaceDir
-			});
+			const listResult = await this.runCli([
+				"sandbox",
+				"list",
+				"--limit",
+				String(pageSize),
+				"--offset",
+				String(offset),
+				"--output",
+				"json"
+			]);
 			if (listResult.code !== 0) throw this.buildLegacyRuntimeUnavailableError(listResult.stderr.trim());
 			const page = parseOpenShellSandboxPhasePage(listResult.stdout, this.params.execContext.sandboxName);
 			if (!page) throw this.buildLegacyRuntimeUnavailableError("OpenShell returned malformed sandbox lifecycle data.");
@@ -1203,18 +1177,13 @@ var OpenShellSandboxBackendImpl = class {
 				rootDir: resolveOpenShellTmpRoot(),
 				prefix: "openclaw-openshell-sync-"
 			}, async ({ dir: tmpDir }) => {
-				const result = await runOpenShellCli({
-					context: this.params.execContext,
-					args: [
-						"sandbox",
-						"download",
-						this.params.execContext.sandboxName,
-						root.remote,
-						tmpDir
-					],
-					cwd: this.params.createParams.workspaceDir
-				});
-				if (result.code !== 0) throw new Error(result.stderr.trim() || "openshell sandbox download failed");
+				await this.runCli([
+					"sandbox",
+					"download",
+					this.params.execContext.sandboxName,
+					root.remote,
+					tmpDir
+				], "openshell sandbox download failed");
 				const preservedShadows = [];
 				const failures = [];
 				try {
@@ -1276,18 +1245,7 @@ var OpenShellSandboxBackendImpl = class {
 				targetDir: stagedRoot,
 				excludeDirs: DEFAULT_OPEN_SHELL_MIRROR_EXCLUDE_DIRS
 			});
-			for (const entry of (await fsPromises.readdir(stagedRoot)).toSorted()) {
-				const result = await runOpenShellCli({
-					context: this.params.execContext,
-					args: buildOpenShellDirectoryUploadArgs({
-						sandboxName: this.params.execContext.sandboxName,
-						localPath: path.join(stagedRoot, entry),
-						remotePath
-					}),
-					cwd: this.params.createParams.workspaceDir
-				});
-				if (result.code !== 0) throw new Error(result.stderr.trim() || "openshell sandbox upload failed");
-			}
+			for (const entry of (await fsPromises.readdir(stagedRoot)).toSorted()) await this.uploadFileToRemote(path.join(stagedRoot, entry), `${normalizeRemotePath(remotePath)}/`);
 		});
 	}
 	async remoteManagedRootsEmpty() {

package/node_modules/@openclaw/fs-safe/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## 0.25.0 - 2026-10-08
+
+### Highlights
+
+- **Faster synchronous plugin captures:** 16% faster than pre-change main on a measured 6,000-file tree; the new `createRootFileCopyBatchSync` API on `advanced` also reuses directory admissions across copies. ([#878](https://github.com/openclaw/fs-safe/pull/878), [#849](https://github.com/openclaw/fs-safe/pull/849))
+- **Guest workspace publication:** works on gVisor and other Linux filesystems that reject `RENAME_NOREPLACE`. ([#876](https://github.com/openclaw/fs-safe/pull/876))
+- **Root-backed sidecar locks:** native asynchronous release and exit cleanup no longer strand locks after their Root moves. ([#879](https://github.com/openclaw/fs-safe/pull/879))
+- **Guest cross-device moves:** preserve the admitted file permissions. ([#869](https://github.com/openclaw/fs-safe/pull/869))
+
+### Features
+
+- **Guarded copy batches:** `createRootFileCopyBatchSync` on `advanced` reuses directory admissions across synchronous copies on canonical POSIX paths while rechecking ancestor and file identities for every copy; single-file copies also reuse admission within the operation. ([#849](https://github.com/openclaw/fs-safe/pull/849))
+
+### Fixes
+
+- **Root-backed file locks:** native asynchronous release and exit cleanup follow the created lock's retained identity after its Root moves, preserving replacement files and reporting ownership mismatches. ([#879](https://github.com/openclaw/fs-safe/pull/879)) Thanks @axiom-ncis.
+- **Temp directory diagnostics:** name rejected roots and ancestors, explain ownership, mode, or symlink failures, and provide safe recovery guidance, including for root-run appliances. Thanks @joequant. ([#877](https://github.com/openclaw/fs-safe/pull/877))
+- **Guest directory publication:** publish staged workspaces when Linux filesystems reject `RENAME_NOREPLACE`, with checked file link/unlink fallback and directory rename that can only replace a concurrently created empty directory. ([#876](https://github.com/openclaw/fs-safe/pull/876)) Thanks @valkyriweb.
+- **Guest cross-device moves:** preserve the admitted source file's permissions instead of leaving the destination with a broader default mode. ([#869](https://github.com/openclaw/fs-safe/pull/869))
+- **Move receipts:** publication receipts capture the source identity after synchronous authorization callbacks return, so a source replaced during authorization is reported accurately. ([#868](https://github.com/openclaw/fs-safe/pull/868))
+- **Atomic copy fallback:** report a failed restoration as a failure even when the underlying error carries a restored receipt. ([#851](https://github.com/openclaw/fs-safe/pull/851))
+- **Archive read limits:** keep the validated entry-read byte limit fixed when callers mutate the options during a read. ([#852](https://github.com/openclaw/fs-safe/pull/852))
+- **Watch on macOS:** reconcile notifications for changes to the watched Root itself immediately instead of waiting for the periodic scan. ([#858](https://github.com/openclaw/fs-safe/pull/858))
+- **`pathScope` tilde names:** keep literal `~` directory names inside scoped file and existing-path lookups instead of expanding them. ([#856](https://github.com/openclaw/fs-safe/pull/856))
+
+### Performance
+
+- **Guarded file copies:** reuse checked canonical POSIX roots during initial path admission, reducing repeated path-resolution work in synchronous plugin source captures without changing per-file identity or race checks.
+- **Root walks:** reuse normalized directory prefixes, cutting a 50k-file walk by 5.6% and its sampled allocation by about 9% while keeping every filesystem and identity check. ([#870](https://github.com/openclaw/fs-safe/pull/870))
+- **Atomic writes:** non-durable async POSIX writes skip a redundant mode change when the staged file already has the requested permissions. ([#871](https://github.com/openclaw/fs-safe/pull/871))
+- **Guarded mutations:** fewer promise allocations around synchronous guard checks, with directory identity checks unchanged. ([#857](https://github.com/openclaw/fs-safe/pull/857))
+- **Archive publication:** fewer promise allocations in archive guard checks, without removing identity or containment checks. ([#864](https://github.com/openclaw/fs-safe/pull/864))
+- **Watch:** Linux and Windows watch passes skip macOS stream-path preparation. ([#860](https://github.com/openclaw/fs-safe/pull/860))
+- **Permission diagnostics:** bound escaping work for large error messages without changing the displayed excerpts. ([#859](https://github.com/openclaw/fs-safe/pull/859))
+
 ## 0.24.2 - 2026-10-07
 
 ### Fixes

package/node_modules/@openclaw/fs-safe/README.md

@@ -22,7 +22,7 @@ await fs.write("../escape.txt", "x");            // throws FsSafeError("outside-
 
 That's the whole pitch. `root()` is the product; the rest of the package — JSON stores, atomic writes, secret files, archive extraction, temp workspaces — is supporting cast for the same boundary.
 
-Full docs and reference at **[fs-safe.io](https://fs-safe.io)**.
+Full docs and reference at **[fs-safe.io](https://fs-safe.io)**. For synchronous plugin captures, [guarded file copies and batches](docs/copy.md#synchronous-guarded-file-copies) return owned destination descriptors while preserving per-file checks.
 
 ## Contents
 

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

@@ -1,4 +1,4 @@
-export { copyRootFileSync, type CopyRootFileSyncOptions, type CopiedRootFileSync } from "./copy-root-file-sync.js";
+export { copyRootFileSync, createRootFileCopyBatchSync, type RootFileCopyBatchSync, type CopyRootFileSyncOptions, type CopiedRootFileSync } from "./copy-root-file-sync.js";
 export { createAsyncLock } from "./async-lock.js";
 export { createDirectory, createDirectorySync, createFileSync, type CreateDirectoryOptions, type CreateFileOptions, type OwnedFileDescriptorSync, } from "./create.js";
 export { copyFileHandle, copyFileDescriptorSync, type CopyFileHandleOptions } from "./file-handle-transfer.js";

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

@@ -1,4 +1,4 @@
-export { copyRootFileSync } from "./copy-root-file-sync.js";
+export { copyRootFileSync, createRootFileCopyBatchSync } from "./copy-root-file-sync.js";
 // Advanced composition surface. These exports are less stable than the focused
 // public subpaths; prefer root/json/store/temp/archive unless you are building a
 // higher-level primitive.

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

@@ -65,7 +65,7 @@ export async function finalizeArchivePublication(params) {
     const check = () => params.deadline?.check();
     const assertGuards = async (guards) => {
         for (const guard of [params.destinationGuard, ...guards, params.sourceGuard]) {
-            await assertDirectoryIdentityGuard(guard);
+            assertDirectoryIdentityGuard(guard);
             check();
         }
     };

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

@@ -98,15 +98,15 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
             assertSourceDirectory(ancestor);
     };
     const assertGuards = async () => {
-        await assertDirectoryIdentityGuard(destinationGuard);
+        assertDirectoryIdentityGuard(destinationGuard);
         check();
         for (const ancestor of ancestors) {
-            await assertDirectoryIdentityGuard(ancestor.guard);
+            assertDirectoryIdentityGuard(ancestor.guard);
             check();
             await ancestor.owner.verify(check);
             check();
         }
-        await assertDirectoryIdentityGuard(sourceGuard);
+        assertDirectoryIdentityGuard(sourceGuard);
         check();
     };
     const walk = async (sourceDir) => {
@@ -184,7 +184,7 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
                                 await owner.apply(mode, { check, beforeChmod: async () => {
                                         await assertGuards();
                                         assertSourceAncestors();
-                                        await assertDirectoryIdentityGuard(guard);
+                                        assertDirectoryIdentityGuard(guard);
                                         check();
                                         await assertResolvedInsideDestination({
                                             destinationRealDir, targetPath: destinationPath, originalPath,

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

@@ -213,7 +213,8 @@ async function readNativeBufferEntry(native, buffer, kind, requested, displayPat
     }
 }
 export async function readArchiveEntry(archivePath, entryPath, options) {
-    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0) {
+    const maxBytes = options.maxBytes;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
         throw new RangeError("maxBytes must be a non-negative safe integer");
     }
     const kind = options.kind ?? resolveArchiveKind(archivePath);
@@ -228,7 +229,7 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
         admitZipBuffer(buffer, resolveExtractLimits(), entry => { zipEntries.push(entry); });
     const native = getNativeBinding();
     if (native)
-        return await readNativeBufferEntry(native, buffer, kind, requestedEntry, entryPath, options.maxBytes, zipEntries);
-    return kind === "zip" ? await readZipEntry(buffer, requestedEntry, options.maxBytes, zipEntries)
-        : await readTarEntry(buffer, requestedEntry, options.maxBytes, kind);
+        return await readNativeBufferEntry(native, buffer, kind, requestedEntry, entryPath, maxBytes, zipEntries);
+    return kind === "zip" ? await readZipEntry(buffer, requestedEntry, maxBytes, zipEntries)
+        : await readTarEntry(buffer, requestedEntry, maxBytes, kind);
 }

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

@@ -5,7 +5,7 @@ import { ArchiveSecurityError } from "./archive-errors.js";
 export type ArchiveDirectoryGuard = AsyncDirectoryGuard<BigIntStats>;
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
 export declare function createDirectoryIdentityGuard(dir: string): Promise<ArchiveDirectoryGuard>;
-export declare function assertDirectoryIdentityGuard(guard: ArchiveDirectoryGuard): Promise<void>;
+export declare function assertDirectoryIdentityGuard(guard: ArchiveDirectoryGuard): void;
 export declare function prepareArchiveDestinationGuard(destDir: string): Promise<ArchiveDirectoryGuard>;
 export declare function prepareArchiveDestinationDir(destDir: string): Promise<string>;
 export declare function assertResolvedInsideDestination(params: {

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

@@ -1,7 +1,7 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { assertDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
 import { ownExtractionDestinationMutation, } from "./archive-deadline.js";
 import { ArchiveSecurityError, } from "./archive-errors.js";
 import { FsSafeError } from "./errors.js";
@@ -38,9 +38,9 @@ export async function createDirectoryIdentityGuard(dir) {
         throw err;
     }
 }
-export async function assertDirectoryIdentityGuard(guard) {
+export function assertDirectoryIdentityGuard(guard) {
     try {
-        await assertAsyncDirectoryGuard(guard);
+        assertDirectoryGuard(guard, "native");
     }
     catch (err) {
         if (err instanceof FsSafeError || isNotFoundPathError(err)) {
@@ -200,7 +200,7 @@ async function prepareOutputPath(params, assertGuards, privateWorkingMode = fals
         if (existingDestinationGuard && assertGuards)
             await assertGuards();
         else {
-            await assertDirectoryIdentityGuard(destinationGuard);
+            assertDirectoryIdentityGuard(destinationGuard);
             checkExtractionDeadline(params.deadline);
             await assertGuards?.();
         }
@@ -213,46 +213,30 @@ async function prepareOutputPath(params, assertGuards, privateWorkingMode = fals
         originalPath: params.originalPath,
     });
     checkExtractionDeadline(params.deadline);
-    if (params.isDirectory) {
-        await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", params.outPath);
+    const relativePath = params.isDirectory ? relPath : path.posix.dirname(relPath);
+    if (params.isDirectory || relativePath !== ".") {
+        const directoryPath = params.isDirectory ? params.outPath : path.dirname(params.outPath);
+        await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", directoryPath);
         checkExtractionDeadline(params.deadline);
         await ownExtractionDestinationMutation(params.deadline, async () => {
             await assertOutputGuards();
             checkExtractionDeadline(params.deadline);
-            await mkdirArchiveOutput({
-                targetRoot,
-                relativePath: relPath,
-                originalPath: params.originalPath,
-            });
-            checkExtractionDeadline(params.deadline);
-            await assertDirectoryIdentityGuard(destinationGuard);
+            await mkdirArchiveOutput({ targetRoot, relativePath, originalPath: params.originalPath });
             checkExtractionDeadline(params.deadline);
-            await assertResolvedInsideDestination({
-                destinationRealDir: params.destinationRealDir,
-                targetPath: params.outPath,
-                originalPath: params.originalPath,
-            });
-            checkExtractionDeadline(params.deadline);
-        });
-        return;
-    }
-    const parentRel = path.posix.dirname(relPath);
-    if (parentRel !== ".") {
-        await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", path.dirname(params.outPath));
-        checkExtractionDeadline(params.deadline);
-        await ownExtractionDestinationMutation(params.deadline, async () => {
-            await assertOutputGuards();
-            checkExtractionDeadline(params.deadline);
-            await mkdirArchiveOutput({
-                targetRoot,
-                relativePath: parentRel,
-                originalPath: params.originalPath,
-            });
-            checkExtractionDeadline(params.deadline);
-            await assertDirectoryIdentityGuard(destinationGuard);
+            assertDirectoryIdentityGuard(destinationGuard);
             checkExtractionDeadline(params.deadline);
+            if (params.isDirectory) {
+                await assertResolvedInsideDestination({
+                    destinationRealDir: params.destinationRealDir,
+                    targetPath: params.outPath,
+                    originalPath: params.originalPath,
+                });
+                checkExtractionDeadline(params.deadline);
+            }
         });
     }
+    if (params.isDirectory)
+        return;
     await assertResolvedInsideDestination({
         destinationRealDir: params.destinationRealDir,
         targetPath: path.dirname(params.outPath),
@@ -292,12 +276,12 @@ export async function withStagedArchiveDestination(params) {
     const stagingGuard = await createDirectoryIdentityGuard(stagingDir);
     try {
         await fs.chmod(stagingDir, ARCHIVE_STAGING_MODE).catch(() => undefined);
-        await assertDirectoryIdentityGuard(stagingGuard);
+        assertDirectoryIdentityGuard(stagingGuard);
         return await params.run(stagingDir);
     }
     finally {
         try {
-            await assertDirectoryIdentityGuard(stagingGuard);
+            assertDirectoryIdentityGuard(stagingGuard);
             await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
         }
         catch {

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

@@ -0,0 +1,17 @@
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+export type CopyPath = {
+    rootPath: string;
+    absolutePath: string;
+};
+declare function admitUncachedCopyPath(input: CopyPath, create?: boolean, admittedRoot?: AnyAsyncDirectoryGuard): {
+    path: string;
+    parent: AnyAsyncDirectoryGuard;
+    assertCurrent: () => void;
+    rootCanonicalPath: string | undefined;
+};
+/** Metadata custody lasts only for the owning copy or explicit batch. */
+export declare function createCopyPathAdmissionCache(): {
+    admit: (input: CopyPath, create?: boolean) => ReturnType<typeof admitUncachedCopyPath>;
+    clear(): void;
+};
+export {};

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

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertSyncDirectoryGuard, captureDirectoryGuard, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { realpathSync } from "./realpath.js";
+import { resolveRootPathSync, ROOT_PATH_ALIAS_POLICIES } from "./root-path.js";
+function admitUncachedCopyPath(input, create = false, admittedRoot) {
+    if (!path.isAbsolute(input.rootPath) || !path.isAbsolute(input.absolutePath)) {
+        throw new FsSafeError("invalid-path", "copy roots and paths must be absolute");
+    }
+    const root = admittedRoot ?? captureDirectoryGuard(realpathSync(input.rootPath), "native", { bigint: true });
+    // Canonical POSIX callers already own a freshly checked root. Keep the
+    // resolver's lexical/symlink walk, but do not rediscover that root each time.
+    const rootCanonicalPath = admittedRoot?.realPath;
+    const resolve = () => {
+        const parent = create ? resolveRootPathSync({
+            ...input, rootCanonicalPath, absolutePath: path.dirname(input.absolutePath), boundaryLabel: "copy parent",
+            rejectSymlinks: true, rejectFinalSymlink: true,
+        }) : undefined;
+        const selected = resolveRootPathSync({
+            ...input, rootCanonicalPath, boundaryLabel: "copy", rejectSymlinks: !create, rejectFinalSymlink: !create,
+            policy: create ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
+        });
+        if (parent && path.dirname(selected.canonicalPath) !== parent.canonicalPath) {
+            throw new FsSafeError("path-mismatch", "copy destination parent changed");
+        }
+        return selected;
+    };
+    const selected = resolve();
+    const parent = captureDirectoryGuard(path.dirname(selected.canonicalPath), "native", { bigint: true });
+    const assertCurrent = () => {
+        assertSyncDirectoryGuard(root);
+        assertSyncDirectoryGuard(parent);
+        const current = resolve();
+        if (current.rootCanonicalPath !== root.realPath || current.canonicalPath !== selected.canonicalPath) {
+            throw new FsSafeError("path-mismatch", "copy path changed during operation");
+        }
+        assertSyncDirectoryGuard(root);
+        assertSyncDirectoryGuard(parent);
+    };
+    assertCurrent();
+    return { path: selected.canonicalPath, parent, assertCurrent, rootCanonicalPath: undefined };
+}
+/** Metadata custody lasts only for the owning copy or explicit batch. */
+export function createCopyPathAdmissionCache() {
+    const roots = new Map();
+    const parents = new Map();
+    const directories = new Map();
+    const assertParent = ({ root, parent, chain }) => {
+        assertSyncDirectoryGuard(root);
+        for (const guard of chain) {
+            inspectDirectoryIdentitySync(guard.dir, { dev: BigInt(guard.stat.dev), ino: BigInt(guard.stat.ino) });
+        }
+        assertSyncDirectoryGuard(parent);
+        assertSyncDirectoryGuard(root);
+    };
+    const admit = (input, create = false) => {
+        // Keep the public resolver for Windows aliases and noncanonical spellings,
+        // including raw dot segments whose traversal must not be normalized away.
+        if (process.platform === "win32" || !path.isAbsolute(input.rootPath) ||
+            !path.isAbsolute(input.absolutePath) || input.rootPath.includes("\0") || input.absolutePath.includes("\0") ||
+            path.resolve(input.rootPath) !== input.rootPath || path.resolve(input.absolutePath) !== input.absolutePath ||
+            !input.absolutePath.startsWith(input.rootPath.endsWith(path.sep) ? input.rootPath : `${input.rootPath}${path.sep}`)) {
+            return admitUncachedCopyPath(input, create);
+        }
+        let root = roots.get(input.rootPath);
+        if (!root) {
+            const canonical = realpathSync(input.rootPath);
+            if (canonical !== input.rootPath)
+                return admitUncachedCopyPath(input, create);
+            root = captureDirectoryGuard(canonical, "native", { bigint: true });
+            roots.set(input.rootPath, root);
+        }
+        assertSyncDirectoryGuard(root);
+        const parentPath = path.dirname(input.absolutePath);
+        let byParent = parents.get(input.rootPath);
+        let admitted = byParent?.get(parentPath);
+        if (!admitted) {
+            // The first file in each parent retains the existing lexical admission.
+            const selected = admitUncachedCopyPath(input, create, root);
+            const chain = [];
+            let cursor = input.rootPath;
+            const relative = path.relative(input.rootPath, parentPath);
+            for (const segment of relative ? relative.split(path.sep) : []) {
+                cursor = path.join(cursor, segment);
+                let guard = directories.get(cursor);
+                if (!guard) {
+                    guard = captureDirectoryGuard(cursor, "native", { bigint: true });
+                    directories.set(cursor, guard);
+                }
+                chain.push(guard);
+            }
+            admitted = { root, parent: chain.at(-1) ?? root, chain };
+            assertParent(admitted);
+            if (selected.path !== input.absolutePath || selected.parent.realPath !== parentPath ||
+                !sameFileIdentity(selected.parent.stat, admitted.parent.stat)) {
+                throw new FsSafeError("path-mismatch", "copy path changed during admission");
+            }
+            byParent ??= new Map();
+            byParent.set(parentPath, admitted);
+            parents.set(input.rootPath, byParent);
+        }
+        const selected = admitted;
+        const assertCurrent = () => {
+            assertParent(selected);
+            // No file observation is cached. Preserve the resolver's symlink errors.
+            if (!create && fs.lstatSync(input.absolutePath, { throwIfNoEntry: false })?.isSymbolicLink()) {
+                admitUncachedCopyPath(input, create);
+                throw new FsSafeError("symlink", "symlink not allowed");
+            }
+        };
+        assertCurrent();
+        return { path: input.absolutePath, parent: selected.parent, assertCurrent, rootCanonicalPath: selected.root.realPath };
+    };
+    return { admit, clear() { roots.clear(); parents.clear(); directories.clear(); } };
+}