@openclaw/openshell-sandbox 2026.8.1-beta.2 → 2026.8.1

package/README.md

@@ -2,7 +2,13 @@
 
 Official NVIDIA OpenShell sandbox backend for OpenClaw.
 
-This plugin lets OpenClaw use OpenShell-managed sandboxes with mirrored local workspaces and SSH command execution.
+This plugin lets OpenClaw use OpenShell-managed local or remote sandboxes with
+SSH command execution. Choose `mirror` mode for a synchronized local workspace
+or `remote` mode for a remote-canonical workspace.
+
+Mirror operations sharing a workspace run sequentially so concurrent agent
+turns cannot overwrite one another. Outbound attachments resolve against the
+configured remote workspace, which defaults to `/sandbox`.
 
 Configuring an OpenShell workspace requires OpenShell `v0.0.88` or newer. The
 plugin supports OpenShell control-plane workspaces through
@@ -22,6 +28,23 @@ Restart the Gateway after installing or updating the plugin.
 
 ## Configure
 
+Install and configure the OpenShell CLI before enabling the backend. As the same
+operating system user that runs the OpenClaw Gateway, verify:
+
+```bash
+openshell --version
+openshell gateway list
+openshell sandbox list
+```
+
+Set `agents.defaults.sandbox.backend` to `"openshell"`, enable
+`plugins.entries.openshell`, and restart the OpenClaw Gateway. OpenShell
+settings belong under `plugins.entries.openshell.config`.
+
+The optional `policy` setting must be the path to a readable OpenShell policy
+YAML file on the Gateway host; it is not a policy name or ID. Use an absolute
+path to avoid resolving it relative to an agent workspace.
+
 Use the OpenShell docs for credentials, workspace mirroring, runtime selection, and troubleshooting:
 
 - https://docs.openclaw.ai/gateway/openshell

package/dist/index.js

@@ -1,15 +1,16 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
-import { buildRemoteWorkdirValidationCommand, buildValidatedExecRemoteCommand, createRemoteShellSandboxFsBridge, createSshSandboxSessionFromConfigText, createWritableRenameTargetResolver, disposeSshSandboxSession, registerSandboxBackend, resolvePreferredOpenClawTmpDir, runPluginCommandWithTimeout, runSshSandboxCommand, sanitizeEnvVars, shellEscape, withTempWorkspace } from "openclaw/plugin-sdk/sandbox";
+import { buildRemoteCommand, buildRemoteWorkdirValidationCommand, buildValidatedExecRemoteCommand, createRemoteShellSandboxFsBridge, createSshSandboxSessionFromConfigText, createWritableRenameTargetResolver, disposeSshSandboxSession, prepareSshSandboxExec, registerSandboxBackend, resolvePreferredOpenClawTmpDir, runPluginCommandWithTimeout, runSshSandboxCommand, sanitizeEnvVars, shellEscape, withTempWorkspace } from "openclaw/plugin-sdk/sandbox";
 import { createHash } from "node:crypto";
 import fsPromises from "node:fs/promises";
 import path from "node:path";
+import { createDeferred, formatPluginConfigIssue, mapPluginConfigIssues } from "openclaw/plugin-sdk/extension-shared";
+import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
+import { FsSafeError, canonicalPathFromExistingAncestor, extractErrorCode, movePathWithCopyFallback } from "openclaw/plugin-sdk/security-runtime";
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { buildPluginConfigSchema } from "openclaw/plugin-sdk/core";
-import { formatPluginConfigIssue, mapPluginConfigIssues } from "openclaw/plugin-sdk/extension-shared";
 import { MAX_TIMER_TIMEOUT_SECONDS } from "openclaw/plugin-sdk/number-runtime";
 import { z } from "zod";
-import { root } from "openclaw/plugin-sdk/file-access-runtime";
-import { FsSafeError, isPathInside, movePathWithCopyFallback } from "openclaw/plugin-sdk/security-runtime";
+import { isPathInside, root } from "openclaw/plugin-sdk/file-access-runtime";
 import pLimit from "p-limit";
 //#region extensions/openshell/src/cli.ts
 function buildOpenShellBaseArgv(config) {
@@ -19,9 +20,6 @@ function buildOpenShellBaseArgv(config) {
 	if (config.workspace) argv.push("--workspace", config.workspace);
 	return argv;
 }
-function buildRemoteCommand(argv) {
-	return argv.map((entry) => shellEscape(entry)).join(" ");
-}
 function applyGatewayEndpointToSshConfig(params) {
 	const endpoint = params.gatewayEndpoint?.trim();
 	if (!endpoint) return params.configText;
@@ -75,6 +73,7 @@ function normalizeProviders(value) {
 	return providers;
 }
 const nonEmptyTrimmedString = (message) => z.string({ error: message }).trim().min(1, { error: message });
+const openShellManagedRemotePath = (fieldName) => nonEmptyTrimmedString(`${fieldName} must be a non-empty string`).regex(/^\/(?:sandbox|agent)(?:\/|$)/, { error: (issue) => String(issue.input).startsWith("/") ? `OpenShell ${fieldName} must stay under /sandbox or /agent` : `OpenShell ${fieldName} must be absolute` }).refine((value) => isManagedOpenShellRemotePath(path.posix.normalize(value)), { error: `OpenShell ${fieldName} must stay under /sandbox or /agent` });
 const openShellWorkspaceName = z.string({ error: "workspace must be a valid OpenShell workspace name" }).trim().min(1, { error: "workspace must be a valid OpenShell workspace name" }).max(19, { error: "workspace must be at most 19 characters" }).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { error: "workspace must contain lowercase alphanumeric characters or single hyphens and must not start or end with a hyphen" });
 const OpenShellPluginConfigSchema = z.strictObject({
 	mode: z.enum(["mirror", "remote"], { error: "mode must be one of mirror, remote" }).optional(),
@@ -87,8 +86,8 @@ const OpenShellPluginConfigSchema = z.strictObject({
 	providers: z.array(z.string({ error: "providers must be an array of strings" }).trim().min(1, { error: "providers must be an array of strings" }), { error: "providers must be an array of strings" }).optional(),
 	gpu: z.boolean({ error: "gpu must be a boolean" }).optional(),
 	autoProviders: z.boolean({ error: "autoProviders must be a boolean" }).optional(),
-	remoteWorkspaceDir: nonEmptyTrimmedString("remoteWorkspaceDir must be a non-empty string").optional(),
-	remoteAgentWorkspaceDir: nonEmptyTrimmedString("remoteAgentWorkspaceDir must be a non-empty string").optional(),
+	remoteWorkspaceDir: openShellManagedRemotePath("remoteWorkspaceDir").optional(),
+	remoteAgentWorkspaceDir: openShellManagedRemotePath("remoteAgentWorkspaceDir").optional(),
 	timeoutSeconds: z.number({ error: `timeoutSeconds must be a number between 1 and ${MAX_TIMER_TIMEOUT_SECONDS}` }).min(1, { error: "timeoutSeconds must be a number >= 1" }).max(MAX_TIMER_TIMEOUT_SECONDS, { error: `timeoutSeconds must be a number <= ${MAX_TIMER_TIMEOUT_SECONDS}` }).optional()
 });
 function isManagedOpenShellRemotePath(value) {
@@ -157,6 +156,24 @@ function resolveOpenShellPluginConfig(value) {
 	};
 }
 //#endregion
+//#region extensions/openshell/src/workspace-roots.ts
+function remotePathDepth(remote) {
+	return remote.split("/").filter(Boolean).length;
+}
+function workspaceRootOwnerOrder(owner) {
+	return owner === "workspace" ? 0 : 1;
+}
+function isOpenShellRemotePathInside(root, candidate) {
+	const relative = path.posix.relative(root, candidate);
+	return relative === "" || relative !== ".." && !relative.startsWith("../") && !path.posix.isAbsolute(relative);
+}
+function orderOpenShellWorkspaceRoots(roots) {
+	return roots.toSorted((a, b) => remotePathDepth(a.remote) - remotePathDepth(b.remote) || workspaceRootOwnerOrder(a.owner) - workspaceRootOwnerOrder(b.owner));
+}
+function resolveOpenShellWorkspaceRoot(roots, candidate) {
+	return roots.toSorted((a, b) => remotePathDepth(b.remote) - remotePathDepth(a.remote) || workspaceRootOwnerOrder(a.owner) - workspaceRootOwnerOrder(b.owner)).find((root) => isOpenShellRemotePathInside(root.remote, candidate));
+}
+//#endregion
 //#region extensions/openshell/src/fs-bridge.ts
 const MATERIALIZED_SKILLS_CONTAINER_PARTS = [
 	".openclaw",
@@ -352,27 +369,43 @@ var OpenShellFsBridge = class {
 			});
 			if (protectedSkillTarget) return protectedSkillTarget;
 		}
-		if (input.startsWith(`${workspaceContainerRoot}/`) || input === workspaceContainerRoot) {
-			const relative = path.posix.relative(workspaceContainerRoot, input) || "";
-			return {
-				hostPath: relative ? path.resolve(workspaceRoot, ...relative.split("/")) : workspaceRoot,
-				relativePath: relative,
-				containerPath: relative ? path.posix.join(workspaceContainerRoot, relative) : workspaceContainerRoot,
-				mountHostRoot: workspaceRoot,
-				writable: this.sandbox.workspaceAccess === "rw",
-				source: "workspace"
-			};
-		}
-		if (hasAgentMount && (input.startsWith(`${agentContainerRoot}/`) || input === agentContainerRoot)) {
-			const relative = path.posix.relative(agentContainerRoot, input) || "";
+		const containerMounts = [{
+			remote: workspaceContainerRoot,
+			owner: "workspace",
+			value: {
+				hostRoot: workspaceRoot,
+				writable: this.sandbox.workspaceAccess === "rw"
+			}
+		}, ...hasAgentMount ? [{
+			remote: agentContainerRoot,
+			owner: "agent",
+			value: {
+				hostRoot: agentRoot,
+				writable: this.sandbox.workspaceAccess === "rw"
+			}
+		}] : []];
+		const resolveContainerTarget = (containerPath) => {
+			const containerMount = resolveOpenShellWorkspaceRoot(containerMounts, containerPath);
+			if (!containerMount) return;
+			const relative = path.posix.relative(containerMount.remote, containerPath) || "";
+			const hostPath = relative ? path.resolve(containerMount.value.hostRoot, ...relative.split("/")) : containerMount.value.hostRoot;
+			if (!isPathInside(containerMount.value.hostRoot, hostPath)) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${input}`);
 			return {
-				hostPath: relative ? path.resolve(agentRoot, ...relative.split("/")) : agentRoot,
-				relativePath: relative ? agentContainerRoot + "/" + relative : agentContainerRoot,
-				containerPath: relative ? path.posix.join(agentContainerRoot, relative) : agentContainerRoot,
-				mountHostRoot: agentRoot,
-				writable: this.sandbox.workspaceAccess === "rw",
-				source: "agent"
+				hostPath,
+				relativePath: containerMount.owner === "agent" ? relative ? containerMount.remote + "/" + relative : containerMount.remote : relative,
+				containerPath: relative ? path.posix.join(containerMount.remote, relative) : containerMount.remote,
+				mountHostRoot: containerMount.value.hostRoot,
+				writable: containerMount.value.writable,
+				source: containerMount.owner
 			};
+		};
+		const containerCwd = params.cwd?.replace(/\\/g, "/");
+		const cwdMount = containerCwd ? resolveOpenShellWorkspaceRoot(containerMounts, containerCwd) : void 0;
+		const containerInput = path.posix.isAbsolute(input) ? input : cwdMount || !params.cwd ? path.posix.resolve(containerCwd ?? workspaceContainerRoot, input) : void 0;
+		if (containerInput) {
+			const target = resolveContainerTarget(containerInput);
+			if (target) return target;
+			if (cwdMount || containerMounts.some((mount) => input === mount.remote || input.startsWith(`${mount.remote}/`))) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${input}`);
 		}
 		const cwd = params.cwd ? path.resolve(params.cwd) : workspaceRoot;
 		const hostPath = path.isAbsolute(input) ? path.resolve(input) : path.resolve(cwd, input);
@@ -387,14 +420,7 @@ var OpenShellFsBridge = class {
 		}
 		if (isPathInside(workspaceRoot, hostPath)) {
 			const relative = path.relative(workspaceRoot, hostPath).split(path.sep).join(path.posix.sep);
-			return {
-				hostPath,
-				relativePath: relative,
-				containerPath: relative ? path.posix.join(workspaceContainerRoot, relative) : workspaceContainerRoot,
-				mountHostRoot: workspaceRoot,
-				writable: this.sandbox.workspaceAccess === "rw",
-				source: "workspace"
-			};
+			return expectResolvedContainerTarget(resolveContainerTarget(path.posix.join(workspaceContainerRoot, relative)), input);
 		}
 		if (skillsRoot && this.sandbox.workspaceAccess === "rw" && isPathInside(skillsRoot, hostPath)) {
 			const relative = path.relative(skillsRoot, hostPath).split(path.sep).join(path.posix.sep);
@@ -409,18 +435,15 @@ var OpenShellFsBridge = class {
 		}
 		if (hasAgentMount && isPathInside(agentRoot, hostPath)) {
 			const relative = path.relative(agentRoot, hostPath).split(path.sep).join(path.posix.sep);
-			return {
-				hostPath,
-				relativePath: relative ? `${agentContainerRoot}/${relative}` : agentContainerRoot,
-				containerPath: relative ? path.posix.join(agentContainerRoot, relative) : agentContainerRoot,
-				mountHostRoot: agentRoot,
-				writable: this.sandbox.workspaceAccess === "rw",
-				source: "agent"
-			};
+			return expectResolvedContainerTarget(resolveContainerTarget(path.posix.join(agentContainerRoot, relative)), input);
 		}
 		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 mkdirLocalRootPath(params) {
 	const relativePath = relativeToRoot(params.target, params.hostPath);
 	if (!relativePath) return;
@@ -585,66 +608,65 @@ function createExcludeMatcher(excludeDirs) {
 }
 const runLimitedFs = pLimit(COPY_TREE_FS_CONCURRENCY);
 async function lstatIfExists(targetPath) {
-	return await runLimitedFs(async () => await fsPromises.lstat(targetPath)).catch(() => null);
+	return await runLimitedFs(fsPromises.lstat, targetPath).catch((error) => {
+		if (extractErrorCode(error) === "ENOENT") return null;
+		throw error;
+	});
 }
-async function copyTreeWithoutSymlinks(params) {
-	const stats = await runLimitedFs(async () => await fsPromises.lstat(params.sourcePath));
-	if (stats.isSymbolicLink()) return;
+async function reconcileMirrorPath(params) {
 	const targetStats = await lstatIfExists(params.targetPath);
-	if (params.preserveTargetSymlinks && targetStats?.isSymbolicLink()) return;
-	if (stats.isDirectory()) {
-		await runLimitedFs(fsPromises.mkdir, params.targetPath, { recursive: true });
-		const entries = await runLimitedFs(async () => await fsPromises.readdir(params.sourcePath));
-		await Promise.all(entries.map(async (entry) => {
-			await copyTreeWithoutSymlinks({
-				sourcePath: path.join(params.sourcePath, entry),
-				targetPath: path.join(params.targetPath, entry),
-				preserveTargetSymlinks: params.preserveTargetSymlinks
-			});
-		}));
-		return;
-	}
-	if (stats.isFile()) {
-		await runLimitedFs(fsPromises.mkdir, path.dirname(params.targetPath), { recursive: true });
-		await runLimitedFs(async () => await fsPromises.copyFile(params.sourcePath, params.targetPath));
-	}
+	if (targetStats && !targetStats.isDirectory() && !targetStats.isFile()) return true;
+	const sourceStats = params.sourcePath ? await runLimitedFs(fsPromises.lstat, params.sourcePath) : null;
+	const sourceDir = sourceStats?.isDirectory() ? params.sourcePath : void 0;
+	const sourceFile = sourceStats?.isFile() ? params.sourcePath : void 0;
+	if (!params.replace && !sourceDir && !sourceFile) return false;
+	if (sourceDir || targetStats?.isDirectory()) {
+		if (targetStats && !targetStats.isDirectory()) await runLimitedFs(fsPromises.rm, params.targetPath, { force: true });
+		const preservedEntries = await reconcileMirrorDirectory({
+			sourceDir,
+			targetDir: params.targetPath,
+			replace: params.replace
+		});
+		if (sourceDir || preservedEntries) return preservedEntries;
+		await runLimitedFs(fsPromises.rmdir, params.targetPath);
+	} else if (targetStats) await runLimitedFs(fsPromises.rm, params.targetPath, { force: true });
+	if (sourceFile) await runLimitedFs(fsPromises.copyFile, sourceFile, params.targetPath);
+	return false;
 }
-async function replaceDirectoryContents(params) {
+async function reconcileMirrorDirectory(params) {
+	const { sourceDir } = params;
 	const isExcluded = createExcludeMatcher(params.excludeDirs);
-	await fsPromises.mkdir(params.targetDir, { recursive: true });
-	const existing = await fsPromises.readdir(params.targetDir);
-	await Promise.all(existing.filter((entry) => !isExcluded(entry)).map(async (entry) => {
-		const targetPath = path.join(params.targetDir, entry);
-		if ((await lstatIfExists(targetPath))?.isSymbolicLink()) return;
-		await runLimitedFs(fsPromises.rm, targetPath, {
-			recursive: true,
-			force: true
-		});
-	}));
-	const sourceEntries = await fsPromises.readdir(params.sourceDir);
-	for (const entry of sourceEntries) {
-		if (isExcluded(entry)) continue;
-		await copyTreeWithoutSymlinks({
-			sourcePath: path.join(params.sourceDir, entry),
-			targetPath: path.join(params.targetDir, entry),
-			preserveTargetSymlinks: true
-		});
+	await runLimitedFs(fsPromises.mkdir, params.targetDir, { recursive: true });
+	const sourceEntries = new Set(sourceDir ? await runLimitedFs(async () => await fsPromises.readdir(sourceDir)) : []);
+	const targetEntries = params.replace ? await runLimitedFs(async () => await fsPromises.readdir(params.targetDir)) : [];
+	const results = await Promise.allSettled([.../* @__PURE__ */ new Set([...sourceEntries, ...targetEntries])].filter((entry) => !isExcluded(entry)).map((entry) => reconcileMirrorPath({
+		sourcePath: sourceDir && sourceEntries.has(entry) ? path.join(sourceDir, entry) : void 0,
+		targetPath: path.join(params.targetDir, entry),
+		replace: params.replace
+	})));
+	let preservedEntries = false;
+	for (const result of results) {
+		if (result.status === "rejected") throw result.reason;
+		preservedEntries ||= result.value;
 	}
+	return preservedEntries;
+}
+async function replaceDirectoryContents(params) {
+	await reconcileMirrorDirectory({
+		...params,
+		replace: true
+	});
 }
 async function stageDirectoryContents(params) {
-	const isExcluded = createExcludeMatcher(params.excludeDirs);
-	await fsPromises.mkdir(params.targetDir, { recursive: true });
-	const sourceEntries = await fsPromises.readdir(params.sourceDir);
-	for (const entry of sourceEntries) {
-		if (isExcluded(entry)) continue;
-		await copyTreeWithoutSymlinks({
-			sourcePath: path.join(params.sourceDir, entry),
-			targetPath: path.join(params.targetDir, entry)
-		});
-	}
+	await reconcileMirrorDirectory({
+		...params,
+		replace: false
+	});
 }
 //#endregion
 //#region extensions/openshell/src/backend.ts
+const openShellWorkspaceOperations = new KeyedAsyncQueue();
+let openShellDetachedCreateSupport;
 const MATERIALIZED_SKILLS_REMOTE_PARTS = [".openclaw", "sandbox-skills"];
 function buildOpenShellDirectoryUploadArgs(params) {
 	return [
@@ -653,9 +675,10 @@ function buildOpenShellDirectoryUploadArgs(params) {
 		"--no-git-ignore",
 		params.sandboxName,
 		params.localPath,
-		normalizeRemotePath(params.remotePath)
+		`${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 PINNED_REMOTE_PATH_MUTATION_SCRIPT = [
 	"set -eu",
 	"die() { echo \"$1\" >&2; exit 1; }",
@@ -761,6 +784,7 @@ const ENSURE_OPEN_SHELL_REMOTE_REAL_DIRECTORY_SCRIPT = [
 	"set -e",
 	"target=\"$1\"",
 	"root=\"${2:-$1}\"",
+	"replace_blocking=\"${3:-0}\"",
 	"case \"$target\" in /*) ;; *) echo \"remote directory must be absolute: $target\" >&2; exit 1 ;; esac",
 	"case \"$root\" in /*) ;; *) echo \"remote root must be absolute: $root\" >&2; exit 1 ;; esac",
 	"target=\"${target%/}\"",
@@ -788,9 +812,15 @@ const ENSURE_OPEN_SHELL_REMOTE_REAL_DIRECTORY_SCRIPT = [
 	"  if [ \"$part\" = \"$relative\" ]; then relative=\"\"; else relative=\"${relative#*/}\"; fi",
 	"  [ -n \"$part\" ] || continue",
 	"  if [ \"$current\" = \"/\" ]; then next=\"/$part\"; else next=\"$current/$part\"; fi",
-	"  if [ -L \"$next\" ]; then echo \"unsafe remote directory symlink: $next\" >&2; exit 1; fi",
+	"  if [ -L \"$next\" ]; then",
+	"    if [ \"$replace_blocking\" != \"1\" ]; then echo \"unsafe remote directory symlink: $next\" >&2; exit 1; fi",
+	"    rm -rf -- \"$next\"",
+	"  elif [ -e \"$next\" ] && [ ! -d \"$next\" ]; then",
+	"    if [ \"$replace_blocking\" != \"1\" ]; then echo \"unsafe remote directory component: $next\" >&2; exit 1; fi",
+	"    rm -rf -- \"$next\"",
+	"  fi",
 	"  if [ -e \"$next\" ]; then",
-	"    if [ ! -d \"$next\" ]; then echo \"unsafe remote directory component: $next\" >&2; exit 1; fi",
+	"    [ -d \"$next\" ] || { echo \"unsafe remote directory component: $next\" >&2; exit 1; }",
 	"  else",
 	"    mkdir -- \"$next\"",
 	"  fi",
@@ -818,20 +848,22 @@ function createOpenShellSandboxBackendManager(params) {
 				args: [
 					"sandbox",
 					"get",
-					entry.containerName
+					entry.containerName,
+					"--output",
+					"json"
 				]
 			});
 			const configuredSource = execContext.config.from;
 			return {
-				running: result.code === 0,
+				running: result.code === 0 && parseOpenShellSandboxPhase(result.stdout) === "Ready",
 				actualConfigLabel: entry.image,
 				configLabelMatch: entry.image === configuredSource
 			};
 		},
-		async removeRuntime({ entry }) {
-			await runOpenShellCli({
+		async removeRuntime({ entry, config }) {
+			const result = await runOpenShellCli({
 				context: {
-					config: params.pluginConfig,
+					config: resolveOpenShellPluginConfigFromConfig(config, params.pluginConfig),
 					sandboxName: entry.containerName
 				},
 				args: [
@@ -840,6 +872,7 @@ function createOpenShellSandboxBackendManager(params) {
 					entry.containerName
 				]
 			});
+			if (result.code !== 0) throw new Error(result.stderr.trim() || "openshell sandbox delete failed");
 		}
 	};
 }
@@ -854,69 +887,25 @@ async function createOpenShellSandboxBackend(params) {
 		config: params.pluginConfig,
 		sandboxName
 	};
-	const impl = new OpenShellSandboxBackendImpl({
+	return new OpenShellSandboxBackendImpl({
 		createParams: params.createParams,
 		execContext,
 		legacyRuntimeAdopted: resolvedSandboxName.legacyRuntimeAdopted,
 		remoteWorkspaceDir: params.pluginConfig.remoteWorkspaceDir,
 		remoteAgentWorkspaceDir: params.pluginConfig.remoteAgentWorkspaceDir
-	});
-	return {
-		id: "openshell",
-		runtimeId: sandboxName,
-		runtimeLabel: sandboxName,
-		workdir: params.pluginConfig.remoteWorkspaceDir,
-		env: params.createParams.cfg.docker.env,
-		mode: params.pluginConfig.mode,
-		configLabel: params.pluginConfig.from,
-		configLabelKind: "Source",
-		workdirValidation: "backend",
-		validateWorkdir: async (workdir) => await impl.validateWorkdir(workdir),
-		discardPreparedWorkdir: (workdir) => impl.discardPreparedWorkdir(workdir),
-		workdirRoots: [params.pluginConfig.remoteWorkspaceDir, params.pluginConfig.remoteAgentWorkspaceDir],
-		buildExecSpec: async ({ command, workdir, env, usePty }) => {
-			const pending = await impl.prepareExec({
-				command,
-				workdir,
-				env,
-				usePty
-			});
-			return {
-				argv: pending.argv,
-				env: buildOpenShellSshExecEnv(),
-				stdinMode: "pipe-open",
-				finalizeToken: pending.token
-			};
-		},
-		finalizeExec: async ({ token }) => {
-			await impl.finalizeExec(token);
-		},
-		runShellCommand: async (command) => await impl.runRemoteShellScript(command),
-		createFsBridge: ({ sandbox }) => params.pluginConfig.mode === "remote" ? createRemoteShellSandboxFsBridge({
-			sandbox,
-			runtime: impl.asHandle()
-		}) : createOpenShellFsBridge({
-			sandbox,
-			backend: impl.asHandle()
-		}),
-		remoteWorkspaceDir: params.pluginConfig.remoteWorkspaceDir,
-		remoteAgentWorkspaceDir: params.pluginConfig.remoteAgentWorkspaceDir,
-		runRemoteShellScript: async (command) => await impl.runRemoteShellScript(command),
-		mkdirpRemotePath: async (remotePath, signal) => await impl.mkdirpRemotePath(remotePath, signal),
-		removeRemotePath: async (remotePath, removeParams) => await impl.removeRemotePath(remotePath, removeParams),
-		renameRemotePath: async (fromRemotePath, toRemotePath, signal) => await impl.renameRemotePath(fromRemotePath, toRemotePath, signal),
-		syncLocalPathToRemote: async (localPath, remotePath) => await impl.syncLocalPathToRemote(localPath, remotePath)
-	};
+	}).asHandle();
 }
 var OpenShellSandboxBackendImpl = class {
 	constructor(params) {
 		this.params = params;
+		this.handle = null;
 		this.ensurePromise = null;
-		this.preparedRemoteWorkspaceForNextExec = null;
 		this.remoteSeedPending = false;
 	}
 	asHandle() {
-		return {
+		if (this.handle) return this.handle;
+		const runRemoteShellScript = (command) => this.params.execContext.config.mode === "mirror" ? this.runWorkspaceOperation(() => this.runRemoteShellScript(command), command.signal) : this.runRemoteShellScript(command);
+		const handle = {
 			id: "openshell",
 			runtimeId: this.params.execContext.sandboxName,
 			runtimeLabel: this.params.execContext.sandboxName,
@@ -927,7 +916,6 @@ var OpenShellSandboxBackendImpl = class {
 			configLabelKind: "Source",
 			workdirValidation: "backend",
 			validateWorkdir: async (workdir) => await this.validateWorkdir(workdir),
-			discardPreparedWorkdir: (workdir) => this.discardPreparedWorkdir(workdir),
 			workdirRoots: [this.params.remoteWorkspaceDir, this.params.remoteAgentWorkspaceDir],
 			remoteWorkspaceDir: this.params.remoteWorkspaceDir,
 			remoteAgentWorkspaceDir: this.params.remoteAgentWorkspaceDir,
@@ -948,124 +936,189 @@ var OpenShellSandboxBackendImpl = class {
 			finalizeExec: async ({ token }) => {
 				await this.finalizeExec(token);
 			},
-			runShellCommand: async (command) => await this.runRemoteShellScript(command),
+			runShellCommand: runRemoteShellScript,
 			createFsBridge: ({ sandbox }) => this.params.execContext.config.mode === "remote" ? createRemoteShellSandboxFsBridge({
 				sandbox,
-				runtime: this.asHandle()
-			}) : createOpenShellFsBridge({
-				sandbox,
-				backend: this.asHandle()
-			}),
-			runRemoteShellScript: async (command) => await this.runRemoteShellScript(command),
-			mkdirpRemotePath: async (remotePath, signal) => await this.mkdirpRemotePath(remotePath, signal),
-			removeRemotePath: async (remotePath, removeParams) => await this.removeRemotePath(remotePath, removeParams),
-			renameRemotePath: async (fromRemotePath, toRemotePath, signal) => await this.renameRemotePath(fromRemotePath, toRemotePath, signal),
-			syncLocalPathToRemote: async (localPath, remotePath) => await this.syncLocalPathToRemote(localPath, remotePath)
+				runtime: handle
+			}) : this.createMirrorFsBridge(sandbox),
+			runRemoteShellScript
 		};
+		this.handle = handle;
+		return handle;
+	}
+	createMirrorFsBridge(sandbox) {
+		const bridge = createOpenShellFsBridge({
+			sandbox,
+			backend: {
+				remoteAgentWorkspaceDir: this.params.remoteAgentWorkspaceDir,
+				mkdirpRemotePath: (remotePath, signal) => this.mkdirpRemotePath(remotePath, signal),
+				removeRemotePath: (remotePath, params) => this.removeRemotePath(remotePath, params),
+				renameRemotePath: (from, to, signal) => this.renameRemotePath(from, to, signal),
+				syncLocalPathToRemote: (localPath, remotePath) => this.syncLocalPathToRemote(localPath, remotePath)
+			}
+		});
+		return {
+			resolvePath: (params) => bridge.resolvePath(params),
+			readFile: (params) => this.runWorkspaceOperation(() => bridge.readFile(params), params.signal),
+			writeFile: (params) => this.runWorkspaceOperation(() => bridge.writeFile(params), params.signal),
+			createFileExclusive: (params) => this.runWorkspaceOperation(() => bridge.createFileExclusive(params), params.signal),
+			mkdirp: (params) => this.runWorkspaceOperation(() => bridge.mkdirp(params), params.signal),
+			remove: (params) => this.runWorkspaceOperation(() => bridge.remove(params), params.signal),
+			rename: (params) => this.runWorkspaceOperation(() => bridge.rename(params), params.signal),
+			stat: (params) => this.runWorkspaceOperation(() => bridge.stat(params), params.signal)
+		};
+	}
+	async runWorkspaceOperation(operation, signal) {
+		signal?.throwIfAborted();
+		const lease = await this.acquireWorkspaceLease();
+		try {
+			signal?.throwIfAborted();
+			return await operation();
+		} finally {
+			lease.release();
+		}
+	}
+	async acquireWorkspaceLease() {
+		const { config, sandboxName } = this.params.execContext;
+		const keys = [`host:${await canonicalPathFromExistingAncestor(this.params.createParams.workspaceDir)}`, `runtime:${JSON.stringify([
+			config.gatewayEndpoint ?? "",
+			config.gateway ?? "",
+			config.workspace ?? process.env.OPENSHELL_WORKSPACE ?? "",
+			sandboxName
+		])}`].toSorted();
+		const releases = [];
+		for (const key of keys) {
+			const acquired = createDeferred();
+			openShellWorkspaceOperations.enqueue(key, () => new Promise(acquired.resolve));
+			releases.push(await acquired.promise);
+		}
+		return { release: () => {
+			for (const release of releases.toReversed()) release();
+		} };
 	}
 	async prepareExec(params) {
 		const remoteWorkdir = params.workdir ?? this.params.remoteWorkspaceDir;
-		const preparedWorkspace = this.consumePreparedRemoteWorkspaceForNextExec(remoteWorkdir);
 		const remoteCommand = buildValidatedExecRemoteCommand({
 			command: params.command,
 			workdir: remoteWorkdir,
-			env: params.env
+			env: {}
 		});
-		await (preparedWorkspace ?? this.prepareRemoteWorkspaceForExec());
-		const sshSession = await createOpenShellSshSession({ context: this.params.execContext });
-		return {
-			argv: [
-				"ssh",
-				"-F",
-				sshSession.configPath,
-				...params.usePty ? [
-					"-tt",
-					"-o",
-					"RequestTTY=force",
-					"-o",
-					"SetEnv=TERM=xterm-256color"
-				] : [
-					"-T",
-					"-o",
-					"RequestTTY=no"
-				],
-				sshSession.host,
-				remoteCommand
-			],
-			token: { sshSession }
-		};
-	}
-	async validateWorkdir(workdir) {
-		const preparedWorkspace = this.prepareRemoteWorkspaceForExec();
-		const reusablePreparation = {
-			workdir,
-			promise: preparedWorkspace
-		};
-		this.preparedRemoteWorkspaceForNextExec = reusablePreparation;
+		const workspaceLease = this.params.execContext.config.mode === "mirror" ? await this.acquireWorkspaceLease() : void 0;
 		try {
-			await preparedWorkspace;
+			await this.ensureSandboxExists();
+			if (workspaceLease) {
+				await this.syncWorkspaceToRemote();
+				this.remoteSeedPending = false;
+			}
 			const sshSession = await createOpenShellSshSession({ context: this.params.execContext });
 			try {
-				const result = await runSshSandboxCommand({
+				const prepared = await prepareSshSandboxExec({
 					session: sshSession,
-					remoteCommand: buildRemoteWorkdirValidationCommand({
-						workdir,
-						root: this.resolveWorkdirValidationRoot(workdir)
-					}),
-					allowFailure: true
+					remoteCommand,
+					env: params.env,
+					tty: params.usePty
 				});
-				const resolvedWorkdir = result.code === 0 ? result.stdout.toString("utf8").trim() : "";
-				if (this.preparedRemoteWorkspaceForNextExec === reusablePreparation) this.preparedRemoteWorkspaceForNextExec = resolvedWorkdir ? {
-					workdir: resolvedWorkdir,
-					promise: preparedWorkspace
-				} : null;
-				return resolvedWorkdir || null;
-			} finally {
+				return {
+					argv: prepared.argv,
+					token: {
+						workspaceLease,
+						cleanup: async () => {
+							try {
+								await prepared.cleanup();
+							} finally {
+								await disposeSshSandboxSession(sshSession);
+							}
+						}
+					}
+				};
+			} catch (error) {
 				await disposeSshSandboxSession(sshSession);
+				throw error;
 			}
 		} catch (error) {
-			if (this.preparedRemoteWorkspaceForNextExec === reusablePreparation) this.preparedRemoteWorkspaceForNextExec = null;
+			workspaceLease?.release();
 			throw error;
 		}
 	}
+	async validateWorkdir(workdir) {
+		if (this.params.execContext.config.mode === "mirror") return await this.runWorkspaceOperation(() => this.validateMirrorWorkdir(workdir));
+		await this.ensureSandboxExists();
+		const sshSession = await createOpenShellSshSession({ context: this.params.execContext });
+		try {
+			const result = await runSshSandboxCommand({
+				session: sshSession,
+				remoteCommand: buildRemoteWorkdirValidationCommand({
+					workdir,
+					root: this.resolveWorkdirValidationRoot(workdir)
+				}),
+				allowFailure: true
+			});
+			return result.code === 0 ? result.stdout.toString("utf8").trim() || null : null;
+		} finally {
+			await disposeSshSandboxSession(sshSession);
+		}
+	}
 	resolveWorkdirValidationRoot(workdir) {
 		try {
 			const normalized = normalizeRemotePath(workdir);
-			return [normalizeRemotePath(this.params.remoteAgentWorkspaceDir), normalizeRemotePath(this.params.remoteWorkspaceDir)].toSorted((a, b) => b.length - a.length).find((root) => isRemotePathInside(root, normalized)) ?? this.params.remoteWorkspaceDir;
+			return resolveOpenShellWorkspaceRoot([{
+				remote: normalizeRemotePath(this.params.remoteWorkspaceDir),
+				owner: "workspace",
+				value: void 0
+			}, {
+				remote: normalizeRemotePath(this.params.remoteAgentWorkspaceDir),
+				owner: "agent",
+				value: void 0
+			}], normalized)?.remote ?? this.params.remoteWorkspaceDir;
 		} catch {
 			return this.params.remoteWorkspaceDir;
 		}
 	}
-	consumePreparedRemoteWorkspaceForNextExec(workdir) {
-		const preparedWorkspace = this.preparedRemoteWorkspaceForNextExec;
-		if (!preparedWorkspace || preparedWorkspace.workdir !== workdir) {
-			this.preparedRemoteWorkspaceForNextExec = null;
-			return null;
-		}
-		this.preparedRemoteWorkspaceForNextExec = null;
-		return preparedWorkspace.promise;
-	}
-	discardPreparedWorkdir(workdir) {
-		if (this.preparedRemoteWorkspaceForNextExec?.workdir === workdir) this.preparedRemoteWorkspaceForNextExec = null;
-	}
-	async prepareRemoteWorkspaceForExec() {
-		await this.ensureSandboxExists();
-		if (this.params.execContext.config.mode === "mirror") {
-			await this.syncWorkspaceToRemote();
-			return;
+	async validateMirrorWorkdir(workdir) {
+		const normalized = normalizeRemotePath(workdir);
+		const roots = this.workspaceUploadRoots();
+		if (!roots.some((root) => isOpenShellRemotePathInside(root.remote, normalized))) return null;
+		const { cfg, skillsWorkspaceDir } = this.params.createParams;
+		if (cfg.workspaceAccess === "rw" && skillsWorkspaceDir) roots.push({
+			remote: resolveRemoteMaterializedSkillsWorkspaceDir(this.params.remoteWorkspaceDir),
+			local: skillsWorkspaceDir,
+			owner: "workspace"
+		});
+		let createdAncestor = false;
+		for (const root of roots.toReversed()) {
+			if (!isOpenShellRemotePathInside(root.remote, normalized)) {
+				createdAncestor ||= isOpenShellRemotePathInside(normalized, root.remote);
+				continue;
+			}
+			if (createdAncestor) return normalized;
+			const relative = path.posix.relative(root.remote, normalized);
+			if (!relative) return normalized;
+			const parts = relative.split("/");
+			if (DEFAULT_OPEN_SHELL_MIRROR_EXCLUDE_DIRS.some((excluded) => excluded === normalizeLowercaseStringOrEmpty(parts[0]))) return null;
+			let local = root.local;
+			for (const part of root.local === skillsWorkspaceDir ? ["", ...parts] : parts) {
+				local = path.join(local, part);
+				if (!(await fsPromises.lstat(local).catch(() => null))?.isDirectory()) return null;
+			}
+			return normalized;
 		}
-		if (!await this.maybeSeedRemoteWorkspace()) await this.syncSkillsWorkspaceToRemote();
+		return createdAncestor ? normalized : null;
 	}
 	async finalizeExec(token) {
+		const workspaceLease = token?.workspaceLease ?? (this.params.execContext.config.mode === "mirror" ? await this.acquireWorkspaceLease() : void 0);
 		try {
 			if (this.params.execContext.config.mode === "mirror") await this.syncWorkspaceFromRemote();
 		} finally {
-			if (token?.sshSession) await disposeSshSandboxSession(token.sshSession);
+			try {
+				await token?.cleanup();
+			} finally {
+				workspaceLease?.release();
+			}
 		}
 	}
 	async runRemoteShellScript(params) {
 		await this.ensureSandboxExists();
-		if (!await this.maybeSeedRemoteWorkspace()) await this.syncSkillsWorkspaceToRemote();
+		if (this.params.execContext.config.mode === "mirror") await this.maybeSeedRemoteWorkspace();
 		return await this.runRemoteShellScriptInternal(params);
 	}
 	async mkdirpRemotePath(remotePath, signal) {
@@ -1170,7 +1223,7 @@ var OpenShellSandboxBackendImpl = class {
 				"--no-git-ignore",
 				this.params.execContext.sandboxName,
 				localPath,
-				path.posix.dirname(remotePath)
+				remotePath
 			],
 			cwd: this.params.createParams.workspaceDir
 		});
@@ -1185,8 +1238,16 @@ var OpenShellSandboxBackendImpl = class {
 	}
 	resolveRemoteTarget(remotePath) {
 		const normalized = normalizeRemotePath(remotePath);
-		const roots = [normalizeRemotePath(this.params.remoteWorkspaceDir), normalizeRemotePath(this.params.remoteAgentWorkspaceDir)].toSorted((a, b) => b.length - a.length);
-		for (const root of roots) if (isRemotePathInside(root, normalized)) {
+		const root = resolveOpenShellWorkspaceRoot([{
+			remote: normalizeRemotePath(this.params.remoteWorkspaceDir),
+			owner: "workspace",
+			value: void 0
+		}, {
+			remote: normalizeRemotePath(this.params.remoteAgentWorkspaceDir),
+			owner: "agent",
+			value: void 0
+		}], normalized)?.remote;
+		if (root) {
 			const relativePath = path.posix.relative(root, normalized);
 			return {
 				root,
@@ -1197,7 +1258,11 @@ var OpenShellSandboxBackendImpl = class {
 	}
 	async ensureSandboxExists() {
 		if (this.ensurePromise) return await this.ensurePromise;
-		this.ensurePromise = this.ensureSandboxExistsInner();
+		const initialize = async () => {
+			await this.ensureSandboxExistsInner();
+			if (this.params.execContext.config.mode === "remote" && !await this.maybeSeedRemoteWorkspace()) await this.syncSkillsWorkspaceToRemote();
+		};
+		this.ensurePromise = this.params.execContext.config.mode === "remote" ? this.runWorkspaceOperation(initialize) : initialize();
 		try {
 			await this.ensurePromise;
 		} catch (error) {
@@ -1221,9 +1286,12 @@ var OpenShellSandboxBackendImpl = class {
 				if (!phase) throw this.buildLegacyRuntimeUnavailableError("OpenShell did not report a lifecycle phase for this sandbox.");
 				if (phase !== "Ready") throw this.buildLegacyRuntimeUnavailableError(`OpenShell reports phase "${phase}".`);
 			}
+			if (this.params.execContext.config.mode === "remote" && await this.remoteManagedRootsEmpty()) this.remoteSeedPending = true;
 			return;
 		}
 		if (this.params.legacyRuntimeAdopted) throw this.buildLegacyRuntimeUnavailableError(getResult.stderr.trim());
+		if (!/\bsandbox not found\b/iu.test(getResult.stderr)) throw new Error(getResult.stderr.trim() || "openshell sandbox get failed");
+		const detachedCreateSupported = await this.supportsDetachedSandboxCreation();
 		const createArgs = [
 			"sandbox",
 			"create",
@@ -1235,8 +1303,12 @@ var OpenShellSandboxBackendImpl = class {
 			...this.params.execContext.config.gpu ? ["--gpu"] : [],
 			...this.params.execContext.config.autoProviders ? ["--auto-providers"] : ["--no-auto-providers"],
 			...this.params.execContext.config.providers.flatMap((provider) => ["--provider", provider]),
-			"--",
-			"true"
+			...detachedCreateSupported ? [
+				"--detach",
+				"--",
+				"sleep",
+				"infinity"
+			] : ["--", "true"]
 		];
 		const createResult = await runOpenShellCli({
 			context: this.params.execContext,
@@ -1247,6 +1319,41 @@ var OpenShellSandboxBackendImpl = class {
 		if (createResult.code !== 0) throw new Error(createResult.stderr.trim() || "openshell sandbox create failed");
 		this.remoteSeedPending = true;
 	}
+	async supportsDetachedSandboxCreation() {
+		const { config } = this.params.execContext;
+		const cliIdentity = JSON.stringify([
+			config.command,
+			config.gatewayEndpoint ?? "",
+			config.gateway ?? "",
+			config.workspace ?? process.env.OPENSHELL_WORKSPACE ?? ""
+		]);
+		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");
+				return /^\s*--detach(?:\s|$)/mu.test(result.stdout);
+			})();
+			openShellDetachedCreateSupport = {
+				key: cliIdentity,
+				promise: support
+			};
+		}
+		try {
+			return await support;
+		} catch (error) {
+			if (openShellDetachedCreateSupport?.promise === support) openShellDetachedCreateSupport = void 0;
+			throw error;
+		}
+	}
 	async resolveLegacyRuntimePhase() {
 		const pageSize = 100;
 		for (let offset = 0;; offset += pageSize) {
@@ -1279,18 +1386,37 @@ var OpenShellSandboxBackendImpl = class {
 			`OpenClaw will not recreate this retired runtime name. Run \`${recreateCommand}\` to migrate this scope to the current naming format.`
 		].filter(Boolean).join(" "));
 	}
-	async syncWorkspaceToRemote() {
-		await this.runRemoteShellScriptInternal({
-			script: "mkdir -p -- \"$1\" && find \"$1\" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +",
-			args: [this.params.remoteWorkspaceDir]
+	workspaceUploadRoots() {
+		const { createParams, remoteWorkspaceDir, remoteAgentWorkspaceDir } = this.params;
+		const roots = [{
+			remote: remoteWorkspaceDir,
+			owner: "workspace",
+			value: createParams.workspaceDir
+		}];
+		if (createParams.cfg.workspaceAccess !== "none" && path.resolve(createParams.agentWorkspaceDir) !== path.resolve(createParams.workspaceDir)) roots.push({
+			remote: remoteAgentWorkspaceDir,
+			owner: "agent",
+			value: createParams.agentWorkspaceDir
 		});
-		await this.uploadPathToRemote(this.params.createParams.workspaceDir, this.params.remoteWorkspaceDir);
-		if (this.params.createParams.cfg.workspaceAccess !== "none" && path.resolve(this.params.createParams.agentWorkspaceDir) !== path.resolve(this.params.createParams.workspaceDir)) {
+		return orderOpenShellWorkspaceRoots(roots).map(({ remote, owner, value: local }) => ({
+			remote,
+			local,
+			owner
+		}));
+	}
+	async syncWorkspaceToRemote() {
+		const roots = this.workspaceUploadRoots();
+		for (const [index, root] of roots.entries()) {
+			const containingRoot = roots.slice(0, index).toReversed().find((candidate) => isOpenShellRemotePathInside(candidate.remote, root.remote));
 			await this.runRemoteShellScriptInternal({
-				script: "mkdir -p -- \"$1\" && find \"$1\" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +",
-				args: [this.params.remoteAgentWorkspaceDir]
+				script: `${ENSURE_OPEN_SHELL_REMOTE_REAL_DIRECTORY_SCRIPT}\nfind "$1" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +`,
+				args: [
+					root.remote,
+					containingRoot?.remote ?? root.remote,
+					containingRoot ? "1" : "0"
+				]
 			});
-			await this.uploadPathToRemote(this.params.createParams.agentWorkspaceDir, this.params.remoteAgentWorkspaceDir);
+			await this.uploadPathToRemote(root.local, root.remote);
 		}
 		await this.syncSkillsWorkspaceToRemote();
 	}
@@ -1306,40 +1432,62 @@ var OpenShellSandboxBackendImpl = class {
 		await this.uploadPathToRemote(this.params.createParams.skillsWorkspaceDir, remoteSkillsWorkspaceDir);
 	}
 	async syncWorkspaceFromRemote() {
-		await withTempWorkspace({
-			rootDir: resolveOpenShellTmpRoot(),
-			prefix: "openclaw-openshell-sync-"
-		}, async ({ dir: tmpDir }) => {
-			const result = await runOpenShellCli({
-				context: this.params.execContext,
-				args: [
-					"sandbox",
-					"download",
-					this.params.execContext.sandboxName,
-					this.params.remoteWorkspaceDir,
-					tmpDir
-				],
-				cwd: this.params.createParams.workspaceDir
-			});
-			if (result.code !== 0) throw new Error(result.stderr.trim() || "openshell sandbox download failed");
-			await removeMaterializedSkillsFromDownloadedWorkspace(tmpDir);
-			const preservedSandboxSkills = await moveMaterializedSkillsShadowAside({
-				workspaceDir: this.params.createParams.workspaceDir,
-				tmpDir
-			});
-			try {
-				await replaceDirectoryContents({
-					sourceDir: tmpDir,
-					targetDir: this.params.createParams.workspaceDir,
-					excludeDirs: DEFAULT_OPEN_SHELL_MIRROR_EXCLUDE_DIRS
-				});
-			} finally {
-				await restoreMaterializedSkillsShadow({
-					workspaceDir: this.params.createParams.workspaceDir,
-					preserved: preservedSandboxSkills
+		const remoteSkillsWorkspaceDir = resolveRemoteMaterializedSkillsWorkspaceDir(this.params.remoteWorkspaceDir);
+		const roots = this.workspaceUploadRoots();
+		for (const [index, root] of roots.entries()) {
+			if (root.owner === "agent") continue;
+			await withTempWorkspace({
+				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");
+				const preservedShadows = [];
+				try {
+					for (const shadowedRoot of roots.slice(index + 1)) {
+						if (root.remote === shadowedRoot.remote || !isOpenShellRemotePathInside(root.remote, shadowedRoot.remote)) continue;
+						const relativeParts = path.posix.relative(root.remote, shadowedRoot.remote).split("/").filter(Boolean);
+						await removeDownloadedWorkspacePath(tmpDir, relativeParts);
+						const preserved = await moveLocalShadowAside({
+							workspaceDir: root.local,
+							tmpDir,
+							relativeParts
+						});
+						if (preserved) preservedShadows.push(preserved);
+					}
+					const relativeSkillsPath = path.posix.relative(root.remote, remoteSkillsWorkspaceDir);
+					if (relativeSkillsPath === "" || !relativeSkillsPath.startsWith("../") && !path.posix.isAbsolute(relativeSkillsPath)) await removeDownloadedWorkspacePath(tmpDir, relativeSkillsPath.split("/").filter(Boolean));
+					if (root.owner === "workspace") {
+						const preserved = await moveLocalShadowAside({
+							workspaceDir: root.local,
+							tmpDir,
+							relativeParts: MATERIALIZED_SKILLS_REMOTE_PARTS
+						});
+						if (preserved) preservedShadows.push(preserved);
+					}
+					await replaceDirectoryContents({
+						sourceDir: tmpDir,
+						targetDir: root.local,
+						excludeDirs: DEFAULT_OPEN_SHELL_MIRROR_EXCLUDE_DIRS
+					});
+				} finally {
+					for (const preserved of preservedShadows.toReversed()) await restoreLocalShadow({
+						workspaceDir: root.local,
+						preserved
+					});
+				}
+			});
+		}
 	}
 	async uploadPathToRemote(localPath, remotePath) {
 		await withTempWorkspace({
@@ -1350,10 +1498,10 @@ var OpenShellSandboxBackendImpl = class {
 			const stagedRoot = path.join(tmpDir, remoteRootName);
 			await stageDirectoryContents({
 				sourceDir: localPath,
-				targetDir: stagedRoot
+				targetDir: stagedRoot,
+				excludeDirs: DEFAULT_OPEN_SHELL_MIRROR_EXCLUDE_DIRS
 			});
-			const stagedEntries = (await fsPromises.readdir(stagedRoot)).toSorted();
-			for (const entry of stagedEntries) {
+			for (const entry of (await fsPromises.readdir(stagedRoot)).toSorted()) {
 				const result = await runOpenShellCli({
 					context: this.params.execContext,
 					args: buildOpenShellDirectoryUploadArgs({
@@ -1367,6 +1515,12 @@ var OpenShellSandboxBackendImpl = class {
 			}
 		});
 	}
+	async remoteManagedRootsEmpty() {
+		return (await this.runRemoteShellScriptInternal({
+			script: REMOTE_MANAGED_ROOTS_EMPTY_SCRIPT,
+			args: [this.params.remoteWorkspaceDir, this.params.remoteAgentWorkspaceDir]
+		})).stdout.toString("utf8").trim() === "0";
+	}
 	async maybeSeedRemoteWorkspace() {
 		if (!this.remoteSeedPending) return false;
 		this.remoteSeedPending = false;
@@ -1431,17 +1585,33 @@ function parseOpenShellSandboxPhasePage(stdout, sandboxName) {
 		return;
 	}
 }
+function parseOpenShellSandboxPhase(stdout) {
+	try {
+		const parsed = JSON.parse(stdout);
+		if (typeof parsed !== "object" || parsed === null || !("phase" in parsed)) return;
+		return typeof parsed.phase === "string" ? parsed.phase : void 0;
+	} catch {
+		return;
+	}
+}
 function resolveRemoteMaterializedSkillsWorkspaceDir(remoteWorkspaceDir) {
 	const root = remoteWorkspaceDir.replace(/\\/g, "/").replace(/\/+$/, "") || "/";
 	return path.posix.join(root, ...MATERIALIZED_SKILLS_REMOTE_PARTS);
 }
-async function removeMaterializedSkillsFromDownloadedWorkspace(tmpDir) {
+async function removeDownloadedWorkspacePath(tmpDir, parts) {
+	if (parts.length === 0) {
+		for (const entry of await fsPromises.readdir(tmpDir)) await fsPromises.rm(path.join(tmpDir, entry), {
+			recursive: true,
+			force: true
+		});
+		return;
+	}
 	let cursor = tmpDir;
-	for (const [index, part] of MATERIALIZED_SKILLS_REMOTE_PARTS.entries()) {
+	for (const [index, part] of parts.entries()) {
 		const next = path.join(cursor, part);
 		const stats = await fsPromises.lstat(next).catch(() => null);
 		if (!stats) return;
-		if (index === MATERIALIZED_SKILLS_REMOTE_PARTS.length - 1) {
+		if (index === parts.length - 1) {
 			await fsPromises.rm(next, {
 				recursive: true,
 				force: true
@@ -1458,31 +1628,31 @@ async function removeMaterializedSkillsFromDownloadedWorkspace(tmpDir) {
 		cursor = next;
 	}
 }
-async function moveMaterializedSkillsShadowAside(params) {
-	const shadowPath = path.join(params.workspaceDir, ...MATERIALIZED_SKILLS_REMOTE_PARTS);
+async function moveLocalShadowAside(params) {
+	const shadowPath = path.join(params.workspaceDir, ...params.relativeParts);
 	const parentStats = await fsPromises.lstat(path.dirname(shadowPath)).catch(() => null);
 	if (!parentStats?.isDirectory() || parentStats.isSymbolicLink()) return;
 	const shadowStats = await fsPromises.lstat(shadowPath).catch(() => null);
 	if (!shadowStats || shadowStats.isSymbolicLink()) return;
 	const preserveRoot = await fsPromises.mkdtemp(path.join(path.dirname(params.tmpDir), "openclaw-openshell-preserve-"));
-	const preservedPath = path.join(preserveRoot, "sandbox-skills");
+	const preservedPath = path.join(preserveRoot, "shadow");
 	await movePathWithCopyFallback({
 		from: shadowPath,
 		to: preservedPath
 	});
 	return {
 		preservedPath,
-		preserveRoot
+		preserveRoot,
+		relativeParts: params.relativeParts
 	};
 }
-async function restoreMaterializedSkillsShadow(params) {
-	if (!params.preserved) return;
+async function restoreLocalShadow(params) {
 	let restored = false;
 	try {
-		const shadowPath = path.join(params.workspaceDir, ...MATERIALIZED_SKILLS_REMOTE_PARTS);
+		const shadowPath = path.join(params.workspaceDir, ...params.preserved.relativeParts);
 		const parentPath = path.dirname(shadowPath);
 		const parentStats = await fsPromises.lstat(parentPath).catch(() => null);
-		if (parentStats?.isSymbolicLink()) throw new Error(`Refusing to restore sandbox skills through symlink parent: ${parentPath}`);
+		if (parentStats?.isSymbolicLink()) throw new Error(`Refusing to restore workspace shadow through symlink parent: ${parentPath}`);
 		if (parentStats && !parentStats.isDirectory()) await fsPromises.rm(parentPath, {
 			recursive: true,
 			force: true
@@ -1512,10 +1682,6 @@ function normalizeRemotePath(remotePath) {
 	if (!path.posix.isAbsolute(normalized)) throw new Error(`OpenShell remote path must be absolute: ${remotePath}`);
 	return normalized;
 }
-function isRemotePathInside(root, candidate) {
-	const relative = path.posix.relative(root, candidate);
-	return relative === "" || relative !== ".." && !relative.startsWith("../") && !path.posix.isAbsolute(relative);
-}
 //#endregion
 //#region extensions/openshell/index.ts
 var openshell_default = definePluginEntry({
@@ -1526,11 +1692,18 @@ var openshell_default = definePluginEntry({
 	register(api) {
 		if (api.registrationMode !== "full") return;
 		const pluginConfig = resolveOpenShellPluginConfig(api.pluginConfig);
-		registerSandboxBackend("openshell", {
+		const unregister = registerSandboxBackend("openshell", {
 			factory: createOpenShellSandboxBackendFactory({ pluginConfig }),
 			manager: createOpenShellSandboxBackendManager({ pluginConfig }),
 			resolveWorkdir: () => pluginConfig.remoteWorkspaceDir
 		});
+		api.lifecycle.registerRuntimeLifecycle({
+			id: "openshell-sandbox-cleanup",
+			cleanup: ({ reason, sessionKey, runId }) => {
+				if (sessionKey !== void 0 || runId !== void 0) return;
+				if (reason === "disable" || reason === "restart") unregister();
+			}
+		});
 	}
 });
 //#endregion

package/openclaw.plugin.json

@@ -54,11 +54,13 @@
       },
       "remoteWorkspaceDir": {
         "type": "string",
-        "minLength": 1
+        "minLength": 1,
+        "pattern": "^\\/(?:sandbox|agent)(?:\\/|$)"
       },
       "remoteAgentWorkspaceDir": {
         "type": "string",
-        "minLength": 1
+        "minLength": 1,
+        "pattern": "^\\/(?:sandbox|agent)(?:\\/|$)"
       },
       "timeoutSeconds": {
         "type": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/openshell-sandbox",
-  "version": "2026.8.1-beta.2",
+  "version": "2026.8.1",
   "description": "OpenClaw sandbox backend for the NVIDIA OpenShell CLI with mirrored local workspaces and SSH command execution.",
   "repository": {
     "type": "git",
@@ -21,10 +21,10 @@
       "minHostVersion": ">=2026.5.12-beta.1"
     },
     "compat": {
-      "pluginApi": ">=2026.8.1-beta.2"
+      "pluginApi": ">=2026.8.1"
     },
     "build": {
-      "openclawVersion": "2026.8.1-beta.2",
+      "openclawVersion": "2026.8.1",
       "bundledDist": false
     },
     "release": {
@@ -41,7 +41,7 @@
     "README.md"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.8.1-beta.2"
+    "openclaw": ">=2026.8.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {