@openclaw/openshell-sandbox 2026.10.1-beta.2 → 2026.10.5-beta.1

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,97 @@
 
 ## 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
+
+- **Linux exclusive publication:** `publishFileExclusive` with `rename-noreplace` uses the identity-checked link/unlink move fallback in native `auto` when `RENAME_NOREPLACE` is unsupported, consumes the source on success, and reports `fallback: "link-unlink"` plus precise partial-failure receipts; native `require` stays fail-closed. Link/unlink is not crash-atomic. ([#843](https://github.com/openclaw/fs-safe/pull/843), [openclaw#166246](https://github.com/openclaw/openclaw/issues/166246)) Thanks @MertBasar0.
+- **Native clone descriptors:** native file copies return read-write descriptors, so Linux clones can be read immediately and macOS clones can be written while preserving read-only source modes. ([#844](https://github.com/openclaw/fs-safe/pull/844))
+
+## 0.24.1 - 2026-10-06
+
+### Features
+
+- **Pinned source copies:** `copyRootFileSync` accepts `expectedSourceIdentity` to reject a replaced source before destination creation and returns the verified `sourceIdentity` for every copy method. This refines the `copyRootFileSync` API introduced in 0.24.0. ([#841](https://github.com/openclaw/fs-safe/pull/841))
+
+## 0.24.0 - 2026-10-06
+
+### Highlights
+
+- **No-replace moves on more Linux filesystems:** when filesystems reject `renameat2` with `RENAME_NOREPLACE`, including reported QNAP ZFS shares and some overlay mounts, `auto` falls back safely: directories use plain rename that can at most replace an empty directory, and files use identity-checked link/unlink that cannot overwrite a target. Native `require` fails closed. ([#838](https://github.com/openclaw/fs-safe/pull/838), fixes [openclaw#165617](https://github.com/openclaw/openclaw/issues/165617)) Thanks @StarGazer1995, original reporter @bbs2i58, and @MertBasar0.
+- **Synchronous guarded copies:** new `copyRootFileSync` on `advanced` supports APFS cloning, reflinks, `copy_file_range`, and guarded byte fallback, returning an owned destination descriptor for synchronous capture hashes. ([#839](https://github.com/openclaw/fs-safe/pull/839))
+- **Public capability classification:** new `isNoReplaceUnsupported(error)` identifies unavailable no-replace rename support without matching internal native error codes. ([#838](https://github.com/openclaw/fs-safe/pull/838))
+
+### Features
+
+- **Synchronous root-to-root copy:** `copyRootFileSync` exclusively creates an absent destination under its admitted root, bounds the copy with `maxBytes`, verifies source and destination identities, and returns a disposable descriptor with copy-method and byte-count receipts. ([#839](https://github.com/openclaw/fs-safe/pull/839))
+- **No-replace error classifier:** export `isNoReplaceUnsupported(error)` from the root package and `errors` subpath for stable `helper-unavailable` capability diagnostics. ([#838](https://github.com/openclaw/fs-safe/pull/838))
+
+### Fixes
+
+- **Linux no-replace moves:** `Root.move()` uses retained-parent file link/unlink or directory rename when `RENAME_NOREPLACE` is unsupported in `auto`, rejects file collisions, and preserves publication/source-removal details after partial failures. ([#838](https://github.com/openclaw/fs-safe/pull/838)) Thanks @StarGazer1995, @bbs2i58, and @MertBasar0.
+
+### Performance
+
+- **Synchronous copy acceleration:** reuse the native bounded copy engine for APFS clones, Linux reflinks, and `copy_file_range` before byte copying when `copyRootFileSync` is called with `clone: "auto"`. ([#839](https://github.com/openclaw/fs-safe/pull/839))
+
+### Compatibility
+
+- **Move fallback limits:** native `require` keeps refusing unsupported no-replace moves. In `auto`, the directory fallback can replace a concurrently created empty directory; nonempty directories and non-directory competitors reject. File fallback requires hard-link support and fails closed if links are denied or unsupported. ([#838](https://github.com/openclaw/fs-safe/pull/838))
+- **Synchronous copy contract:** `copyRootFileSync` defaults to `clone: "never"`, requires existing parents and an absent destination, and performs direct exclusive creation. Use a private capture directory; it does not promise atomic publication, crash durability, or a coherent snapshot of concurrent in-place edits. ([#839](https://github.com/openclaw/fs-safe/pull/839))
+
+## 0.23.1 - 2026-10-04
+
+### Highlights
+
+- **gVisor and 9p file creation:** `create()` and other no-replace publication fall back in `auto` mode on filesystems that reject `renameat2` with `RENAME_NOREPLACE`; `require` mode fails closed. ([#834](https://github.com/openclaw/fs-safe/pull/834), fixes [#828](https://github.com/openclaw/fs-safe/issues/828)) Thanks @vishnukool.
+- **Container copy compatibility:** seccomp or LSM policies denying `FICLONE` no longer break `clone: "auto"` copies, for both single files and `copyTree`. ([#829](https://github.com/openclaw/fs-safe/pull/829), [#835](https://github.com/openclaw/fs-safe/pull/835)) Thanks @Mohl, with co-author credit to @foxsky.
+- **macOS watching:** a FIFO at a watched name no longer freezes watching across the process. ([#830](https://github.com/openclaw/fs-safe/pull/830)) Thanks @SebTardif.
+
+### Fixes
+
+- **gVisor file creation:** fall back safely when the filesystem rejects native no-replace publication, clean unpublished stages, and report the missing capability in native-required mode. ([#834](https://github.com/openclaw/fs-safe/pull/834)) Thanks @vishnukool.
+- **ZIP collision checks:** reject directory and file names that differ only by case, Unicode normalization, or a trailing separator before extraction or bounded reads. ([#832](https://github.com/openclaw/fs-safe/pull/832)) Thanks @SebTardif.
+- **macOS entry watch:** prevent a FIFO at a watched name from blocking every watcher in the process. ([#830](https://github.com/openclaw/fs-safe/pull/830)) Thanks @SebTardif.
+- **Disk-full diagnostics:** preserve disk-full (`ENOSPC`) diagnostics and cleanup receipts through combined write and disposal failures instead of reporting a misleading file-type error. ([#833](https://github.com/openclaw/fs-safe/pull/833)) Thanks @steipete.
+- **Linux clone fallback:** copies with `clone: "auto"` fall back to guarded byte copying when container seccomp or LSM policy denies `FICLONE`; `clone: "always"` reports `unsupported-platform` and removes its stage. ([#829](https://github.com/openclaw/fs-safe/pull/829)) Thanks @Mohl, with co-author credit to @foxsky.
+- **Linux tree clone fallback:** `copyTree` with `clone: "auto"` copies bytes when XFS/ZFS file reflinks are unavailable or denied by container policy; `"always"` reports `unsupported-platform` after partial-tree cleanup. ([#835](https://github.com/openclaw/fs-safe/pull/835)) Thanks @steipete.
+
 ## 0.23.0 - 2026-10-02
 
 ### Highlights

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,3 +1,4 @@
+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,3 +1,4 @@
+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-entry.js

@@ -63,13 +63,17 @@ export function stripArchivePath(entryPath, stripComponents) {
 export function createArchiveOutputPathTracker() {
     const seen = new Set();
     return (entryPath, originalPath) => {
-        const normalized = path.posix.normalize(normalizeArchiveEntryPath(entryPath));
+        // Extraction passes stripArchivePath output. Native manifests and physical
+        // admission pass raw names, and path.posix.normalize keeps a directory's
+        // trailing slash, so "A/" and "a" would not share a key.
+        const canonical = stripArchivePath(entryPath, 0)
+            ?? path.posix.normalize(normalizeArchiveEntryPath(entryPath));
         // Archive policy must not depend on the destination volume's case or
         // Unicode-normalization behavior. Otherwise the JavaScript and native
         // writers can disagree about which of two colliding entries wins.
-        const collisionKey = lowerCaseNfc(normalized);
+        const collisionKey = lowerCaseNfc(canonical);
         if (seen.has(collisionKey)) {
-            throw new ArchiveSecurityError("entry-path", `archive entries collide at output path ${formatErrorDetail(normalized)}: ${formatErrorDetail(originalPath)}`);
+            throw new ArchiveSecurityError("entry-path", `archive entries collide at output path ${formatErrorDetail(canonical)}: ${formatErrorDetail(originalPath)}`);
         }
         seen.add(collisionKey);
     };

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 {};