@openclaw/openshell-sandbox 2026.9.1-beta.1 → 2026.9.1

package/dist/index.js

@@ -1,16 +1,16 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
-import { buildRemoteCommand, buildRemoteWorkdirValidationCommand, buildValidatedExecRemoteCommand, createRemoteShellSandboxFsBridge, createSshSandboxSessionFromConfigText, createWritableRenameTargetResolver, disposeSshSandboxSession, prepareSshSandboxExec, registerSandboxBackend, resolvePreferredOpenClawTmpDir, runPluginCommandWithTimeout, runSshSandboxCommand, sanitizeEnvVars, shellEscape, withTempWorkspace } from "openclaw/plugin-sdk/sandbox";
+import { buildRemoteCommand, buildRemoteWorkdirValidationCommand, buildValidatedExecRemoteCommand, createRemoteShellSandboxFsBridge, createSshSandboxSessionFromConfigText, createWritableRenameTargetResolver, disposeSshSandboxSession, prepareSshSandboxExec, registerSandboxBackend, resolvePreferredOpenClawTmpDir, resolveReadOnlyWorkspaceSkillMounts, 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 { MAX_TIMER_TIMEOUT_SECONDS } from "openclaw/plugin-sdk/number-runtime";
 import { z } from "zod";
 import { isPathInside, root } from "openclaw/plugin-sdk/file-access-runtime";
-import { FsSafeError, movePathWithCopyFallback } from "openclaw/plugin-sdk/security-runtime";
 import pLimit from "p-limit";
 //#region extensions/openshell/src/cli.ts
 function buildOpenShellBaseArgv(config) {
@@ -156,12 +156,25 @@ 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",
-	"sandbox-skills",
-	"skills"
-];
 function createOpenShellFsBridge(params) {
 	return new OpenShellFsBridge(params.sandbox, params.backend);
 }
@@ -169,7 +182,7 @@ var OpenShellFsBridge = class {
 	constructor(sandbox, backend) {
 		this.sandbox = sandbox;
 		this.backend = backend;
-		this.resolveRenameTargets = createWritableRenameTargetResolver((target) => this.resolveTarget(target), (target, action) => this.ensureWritable(target, action));
+		this.resolveRenameTargets = createWritableRenameTargetResolver((target) => this.resolveTarget(target), (target, action) => this.ensureWritable(target, action, true));
 	}
 	resolvePath(params) {
 		const target = this.resolveTarget(params);
@@ -259,7 +272,7 @@ var OpenShellFsBridge = class {
 	async remove(params) {
 		const target = this.resolveTarget(params);
 		const hostPath = this.requireHostPath(target);
-		this.ensureWritable(target, "remove files");
+		this.ensureWritable(target, "remove files", params.recursive);
 		await assertLocalPathSafety({
 			target,
 			root: target.mountHostRoot,
@@ -326,8 +339,16 @@ var OpenShellFsBridge = class {
 			mtimeMs: stats.mtimeMs
 		};
 	}
-	ensureWritable(target, action) {
-		if (this.sandbox.workspaceAccess !== "rw" || !target.writable) throw new Error(`Sandbox path is read-only; cannot ${action}: ${target.containerPath}`);
+	ensureWritable(target, action, includeDescendants = false) {
+		if (this.sandbox.workspaceAccess === "ro" || !target.writable || includeDescendants && this.readOnlyMounts().some((mount) => isOpenShellRemotePathInside(target.containerPath, mount.containerPath))) throw new Error(`Sandbox path is read-only; cannot ${action}: ${target.containerPath}`);
+	}
+	readOnlyMounts() {
+		const workdirs = [this.sandbox.containerWorkdir];
+		if (this.sandbox.workspaceAccess !== "none" && path.resolve(this.sandbox.workspaceDir) !== path.resolve(this.sandbox.agentWorkspaceDir)) workdirs.push(this.backend.remoteAgentWorkspaceDir || "/agent");
+		return [...workdirs.flatMap((workdir) => resolveReadOnlyWorkspaceSkillMounts({
+			...this.sandbox,
+			workdir
+		})), ...this.sandbox.readOnlyResourceMounts ?? []];
 	}
 	requireHostPath(target) {
 		if (!target.hostPath) throw new Error(`OpenShell mirror bridge requires a local host path: ${target.containerPath}`);
@@ -339,91 +360,74 @@ var OpenShellFsBridge = class {
 		const hasAgentMount = this.sandbox.workspaceAccess !== "none" && workspaceRoot !== agentRoot;
 		const agentContainerRoot = (this.backend.remoteAgentWorkspaceDir || "/agent").replace(/\\/g, "/");
 		const workspaceContainerRoot = this.sandbox.containerWorkdir.replace(/\\/g, "/");
-		const skillsRoot = this.sandbox.skillsWorkspaceDir ? path.resolve(this.sandbox.skillsWorkspaceDir, "skills") : void 0;
-		const skillsContainerRoot = path.posix.join(workspaceContainerRoot, ...MATERIALIZED_SKILLS_CONTAINER_PARTS);
-		const workspaceSkillsShadowRoot = path.resolve(workspaceRoot, ...MATERIALIZED_SKILLS_CONTAINER_PARTS);
 		const input = params.filePath.trim();
-		if (skillsRoot && this.sandbox.workspaceAccess === "rw") {
-			const protectedSkillTarget = resolveProtectedSkillTarget({
-				input,
-				skillsRoot,
-				skillsContainerRoot
-			});
-			if (protectedSkillTarget) return protectedSkillTarget;
-		}
-		if (input.startsWith(`${workspaceContainerRoot}/`) || input === workspaceContainerRoot) {
-			const relative = path.posix.relative(workspaceContainerRoot, input) || "";
-			const hostPath = relative ? path.resolve(workspaceRoot, ...relative.split("/")) : workspaceRoot;
-			if (!isPathInside(workspaceRoot, hostPath)) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${input}`);
-			return {
-				hostPath,
-				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 hostPath = relative ? path.resolve(agentRoot, ...relative.split("/")) : agentRoot;
-			if (!isPathInside(agentRoot, hostPath)) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${input}`);
+		const readOnlyMounts = this.readOnlyMounts();
+		const containerMounts = [{
+			remote: workspaceContainerRoot,
+			owner: "workspace",
+			value: {
+				hostRoot: workspaceRoot,
+				writable: this.sandbox.workspaceAccess !== "ro"
+			}
+		}, ...hasAgentMount ? [{
+			remote: agentContainerRoot,
+			owner: "agent",
+			value: {
+				hostRoot: agentRoot,
+				writable: this.sandbox.workspaceAccess === "rw"
+			}
+		}] : []];
+		containerMounts.unshift(...readOnlyMounts.map((mount) => ({
+			remote: mount.containerPath,
+			owner: resolveOpenShellWorkspaceRoot(containerMounts, mount.containerPath)?.owner ?? "workspace",
+			value: {
+				hostRoot: path.resolve(mount.hostPath),
+				writable: false
+			}
+		})));
+		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,
-				relativePath: relative ? agentContainerRoot + "/" + relative : agentContainerRoot,
-				containerPath: relative ? path.posix.join(agentContainerRoot, relative) : agentContainerRoot,
-				mountHostRoot: agentRoot,
-				writable: this.sandbox.workspaceAccess === "rw",
-				source: "agent"
+				relativePath: containerMount.owner === "agent" ? relative ? containerMount.remote + "/" + relative : containerMount.remote : path.posix.relative(workspaceContainerRoot, containerPath),
+				containerPath: relative ? path.posix.join(containerMount.remote, relative) : containerMount.remote,
+				mountHostRoot: containerMount.value.hostRoot,
+				writable: containerMount.value.writable
 			};
+		};
+		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);
-		if (skillsRoot && this.sandbox.workspaceAccess === "rw") {
-			const protectedSkillShadowTarget = resolveProtectedSkillShadowTarget({
-				hostPath,
-				workspaceSkillsShadowRoot,
-				skillsRoot,
-				skillsContainerRoot
-			});
-			if (protectedSkillShadowTarget) return protectedSkillShadowTarget;
+		for (const mount of readOnlyMounts) 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 {
-				hostPath,
-				relativePath: relative,
-				containerPath: relative ? path.posix.join(workspaceContainerRoot, relative) : workspaceContainerRoot,
-				mountHostRoot: workspaceRoot,
-				writable: this.sandbox.workspaceAccess === "rw",
-				source: "workspace"
-			};
-		}
-		if (skillsRoot && this.sandbox.workspaceAccess === "rw" && isPathInside(skillsRoot, hostPath)) {
-			const relative = path.relative(skillsRoot, hostPath).split(path.sep).join(path.posix.sep);
-			return {
-				hostPath,
-				relativePath: relative ? path.posix.join(...MATERIALIZED_SKILLS_CONTAINER_PARTS, relative) : path.posix.join(...MATERIALIZED_SKILLS_CONTAINER_PARTS),
-				containerPath: relative ? path.posix.join(skillsContainerRoot, relative) : skillsContainerRoot,
-				mountHostRoot: skillsRoot,
-				writable: false,
-				source: "protectedSkill"
-			};
+			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 {
-				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;
@@ -510,43 +514,12 @@ async function nearestExistingDirectoryStats(params) {
 function isNotFoundError(err) {
 	return err instanceof FsSafeError && err.code === "not-found" || typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
 }
-function resolveProtectedSkillTarget(params) {
-	const relativeRoot = path.posix.join(...MATERIALIZED_SKILLS_CONTAINER_PARTS);
-	const normalizedInput = path.posix.normalize(params.input.replace(/\\/g, "/"));
-	const isAbsoluteContainer = normalizedInput === params.skillsContainerRoot || normalizedInput.startsWith(`${params.skillsContainerRoot}/`);
-	const isRelativeContainer = normalizedInput === relativeRoot || normalizedInput.startsWith(`${relativeRoot}/`);
-	if (!isAbsoluteContainer && !isRelativeContainer) return null;
-	const relative = isAbsoluteContainer ? path.posix.relative(params.skillsContainerRoot, normalizedInput) : path.posix.relative(relativeRoot, normalizedInput);
-	const safeRelative = relative === "." ? "" : relative;
-	return {
-		hostPath: safeRelative ? path.resolve(params.skillsRoot, ...safeRelative.split("/")) : params.skillsRoot,
-		relativePath: safeRelative ? path.posix.join(relativeRoot, safeRelative) : relativeRoot,
-		containerPath: safeRelative ? path.posix.join(params.skillsContainerRoot, safeRelative) : params.skillsContainerRoot,
-		mountHostRoot: params.skillsRoot,
-		writable: false,
-		source: "protectedSkill"
-	};
-}
-function resolveProtectedSkillShadowTarget(params) {
-	if (!isPathInside(params.workspaceSkillsShadowRoot, params.hostPath)) return null;
-	const relative = path.relative(params.workspaceSkillsShadowRoot, params.hostPath).split(path.sep).join(path.posix.sep);
-	const safeRelative = relative === "." ? "" : relative;
-	const hostPath = safeRelative ? path.resolve(params.skillsRoot, ...safeRelative.split("/")) : params.skillsRoot;
-	const relativeRoot = path.posix.join(...MATERIALIZED_SKILLS_CONTAINER_PARTS);
-	return {
-		hostPath,
-		relativePath: safeRelative ? path.posix.join(relativeRoot, safeRelative) : relativeRoot,
-		containerPath: safeRelative ? path.posix.join(params.skillsContainerRoot, safeRelative) : params.skillsContainerRoot,
-		mountHostRoot: params.skillsRoot,
-		writable: false,
-		source: "protectedSkill"
-	};
-}
 async function assertLocalPathSafety(params) {
 	if (!params.target.hostPath) throw new Error(`Missing local host path for ${params.target.containerPath}`);
 	const canonicalRoot = await fsPromises.realpath(params.root).catch(() => path.resolve(params.root));
 	const targetStats = await fsPromises.lstat(params.target.hostPath).catch(() => null);
-	if (!isPathInside(canonicalRoot, params.allowFinalSymlinkForUnlink && targetStats?.isSymbolicLink() ? path.resolve(canonicalRoot, path.relative(params.root, params.target.hostPath)) : await resolveCanonicalCandidate(params.target.hostPath))) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${params.target.containerPath}`);
+	const candidate = params.allowFinalSymlinkForUnlink && targetStats?.isSymbolicLink() ? path.resolve(canonicalRoot, path.relative(params.root, params.target.hostPath)) : await resolveCanonicalCandidate(params.target.hostPath);
+	if (!isPathInside(canonicalRoot, candidate)) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${params.target.containerPath}`);
 	const segments = path.relative(params.root, params.target.hostPath).split(path.sep).filter(Boolean);
 	let cursor = params.root;
 	for (const [index, segment] of segments.entries()) {
@@ -588,63 +561,60 @@ 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
@@ -767,6 +737,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%/}\"",
@@ -794,9 +765,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",
@@ -876,11 +853,11 @@ var OpenShellSandboxBackendImpl = class {
 		this.params = params;
 		this.handle = null;
 		this.ensurePromise = null;
-		this.preparedRemoteWorkspaceForNextExec = null;
 		this.remoteSeedPending = false;
 	}
 	asHandle() {
 		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,
@@ -892,7 +869,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,
@@ -913,12 +889,12 @@ var OpenShellSandboxBackendImpl = class {
 			finalizeExec: async ({ token }) => {
 				await this.finalizeExec(token);
 			},
-			runShellCommand: async (command) => await this.runWorkspaceOperation(async () => await this.runRemoteShellScript(command)),
+			runShellCommand: runRemoteShellScript,
 			createFsBridge: ({ sandbox }) => this.params.execContext.config.mode === "remote" ? createRemoteShellSandboxFsBridge({
 				sandbox,
 				runtime: handle
 			}) : this.createMirrorFsBridge(sandbox),
-			runRemoteShellScript: async (command) => await this.runWorkspaceOperation(async () => await this.runRemoteShellScript(command))
+			runRemoteShellScript
 		};
 		this.handle = handle;
 		return handle;
@@ -936,18 +912,20 @@ var OpenShellSandboxBackendImpl = class {
 		});
 		return {
 			resolvePath: (params) => bridge.resolvePath(params),
-			readFile: (params) => this.runWorkspaceOperation(() => bridge.readFile(params)),
-			writeFile: (params) => this.runWorkspaceOperation(() => bridge.writeFile(params)),
-			createFileExclusive: (params) => this.runWorkspaceOperation(() => bridge.createFileExclusive(params)),
-			mkdirp: (params) => this.runWorkspaceOperation(() => bridge.mkdirp(params)),
-			remove: (params) => this.runWorkspaceOperation(() => bridge.remove(params)),
-			rename: (params) => this.runWorkspaceOperation(() => bridge.rename(params)),
-			stat: (params) => this.runWorkspaceOperation(() => bridge.stat(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) {
+	async runWorkspaceOperation(operation, signal) {
+		signal?.throwIfAborted();
 		const lease = await this.acquireWorkspaceLease();
 		try {
+			signal?.throwIfAborted();
 			return await operation();
 		} finally {
 			lease.release();
@@ -955,32 +933,19 @@ var OpenShellSandboxBackendImpl = class {
 	}
 	async acquireWorkspaceLease() {
 		const { config, sandboxName } = this.params.execContext;
-		const keys = [`host:${path.resolve(this.params.createParams.workspaceDir)}`, `runtime:${JSON.stringify([
+		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 = [];
-		try {
-			for (const key of keys) {
-				const acquired = createDeferred();
-				const released = createDeferred();
-				openShellWorkspaceOperations.enqueue(key, async () => {
-					acquired.resolve();
-					await released.promise;
-				});
-				await acquired.promise;
-				releases.push(released.resolve);
-			}
-		} catch (error) {
-			for (const release of releases.toReversed()) release();
-			throw error;
+		for (const key of keys) {
+			const acquired = createDeferred();
+			openShellWorkspaceOperations.enqueue(key, () => new Promise(acquired.resolve));
+			releases.push(await acquired.promise);
 		}
-		let active = true;
 		return { release: () => {
-			if (!active) return;
-			active = false;
 			for (const release of releases.toReversed()) release();
 		} };
 	}
@@ -991,10 +956,13 @@ var OpenShellSandboxBackendImpl = class {
 			workdir: remoteWorkdir,
 			env: {}
 		});
-		const preparedWorkspace = this.consumePreparedRemoteWorkspaceForNextExec(remoteWorkdir);
-		const workspaceLease = preparedWorkspace?.lease ?? await this.acquireWorkspaceLease();
+		const workspaceLease = this.params.execContext.config.mode === "mirror" ? await this.acquireWorkspaceLease() : void 0;
 		try {
-			await (preparedWorkspace?.promise ?? this.prepareRemoteWorkspaceForExec());
+			await this.ensureSandboxExists();
+			if (workspaceLease) {
+				await this.syncWorkspaceToRemote();
+				this.remoteSeedPending = false;
+			}
 			const sshSession = await createOpenShellSshSession({ context: this.params.execContext });
 			try {
 				const prepared = await prepareSshSandboxExec({
@@ -1006,9 +974,14 @@ var OpenShellSandboxBackendImpl = class {
 				return {
 					argv: prepared.argv,
 					token: {
-						sshSession,
-						cleanup: prepared.cleanup,
-						workspaceLease
+						workspaceLease,
+						cleanup: async () => {
+							try {
+								await prepared.cleanup();
+							} finally {
+								await disposeSshSandboxSession(sshSession);
+							}
+						}
 					}
 				};
 			} catch (error) {
@@ -1016,104 +989,89 @@ var OpenShellSandboxBackendImpl = class {
 				throw error;
 			}
 		} catch (error) {
-			workspaceLease.release();
+			workspaceLease?.release();
 			throw error;
 		}
 	}
 	async validateWorkdir(workdir) {
-		this.discardPreparedRemoteWorkspace();
-		const lease = await this.acquireWorkspaceLease();
-		const preparedWorkspace = this.prepareRemoteWorkspaceForExec();
-		const reusablePreparation = {
-			workdir,
-			promise: preparedWorkspace,
-			lease
-		};
-		this.preparedRemoteWorkspaceForNextExec = reusablePreparation;
+		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 {
-			await preparedWorkspace;
-			const sshSession = await createOpenShellSshSession({ context: this.params.execContext });
-			try {
-				const result = await runSshSandboxCommand({
-					session: sshSession,
-					remoteCommand: buildRemoteWorkdirValidationCommand({
-						workdir,
-						root: this.resolveWorkdirValidationRoot(workdir)
-					}),
-					allowFailure: true
-				});
-				const resolvedWorkdir = result.code === 0 ? result.stdout.toString("utf8").trim() : "";
-				if (this.preparedRemoteWorkspaceForNextExec === reusablePreparation) {
-					this.preparedRemoteWorkspaceForNextExec = resolvedWorkdir ? {
-						workdir: resolvedWorkdir,
-						promise: preparedWorkspace,
-						lease
-					} : null;
-					if (!resolvedWorkdir) lease.release();
-				} else lease.release();
-				return resolvedWorkdir || null;
-			} finally {
-				await disposeSshSandboxSession(sshSession);
-			}
-		} catch (error) {
-			if (this.preparedRemoteWorkspaceForNextExec?.lease === lease) this.preparedRemoteWorkspaceForNextExec = null;
-			lease.release();
-			throw error;
+			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.discardPreparedRemoteWorkspace();
-			return null;
-		}
-		this.preparedRemoteWorkspaceForNextExec = null;
-		return preparedWorkspace;
-	}
-	discardPreparedWorkdir(workdir) {
-		if (this.preparedRemoteWorkspaceForNextExec?.workdir === workdir) this.discardPreparedRemoteWorkspace();
-	}
-	discardPreparedRemoteWorkspace() {
-		const preparedWorkspace = this.preparedRemoteWorkspaceForNextExec;
-		if (!preparedWorkspace) return;
-		this.preparedRemoteWorkspaceForNextExec = null;
-		preparedWorkspace.promise.then(() => preparedWorkspace.lease.release(), () => preparedWorkspace.lease.release());
-	}
-	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 ?? await this.acquireWorkspaceLease();
+		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 {
 			try {
-				if (token?.sshSession) try {
-					await token.cleanup();
-				} finally {
-					await disposeSshSandboxSession(token.sshSession);
-				}
+				await token?.cleanup();
 			} finally {
-				workspaceLease.release();
+				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) {
@@ -1233,8 +1191,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,
@@ -1245,7 +1211,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) {
@@ -1369,18 +1339,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();
 	}
@@ -1396,40 +1385,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({
@@ -1443,8 +1454,7 @@ var OpenShellSandboxBackendImpl = class {
 				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({
@@ -1541,13 +1551,20 @@ 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
@@ -1564,31 +1581,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
@@ -1618,10 +1635,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({
@@ -1632,11 +1645,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/openshell-sandbox",
-  "version": "2026.9.1-beta.1",
+  "version": "2026.9.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.9.1-beta.1"
+      "pluginApi": ">=2026.9.1"
     },
     "build": {
-      "openclawVersion": "2026.9.1-beta.1",
+      "openclawVersion": "2026.9.1",
       "bundledDist": false
     },
     "release": {
@@ -41,7 +41,7 @@
     "README.md"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.9.1-beta.1"
+    "openclaw": ">=2026.9.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {