@openclaw/openshell-sandbox 2026.9.6 → 2026.9.8

package/dist/index.js

@@ -5,6 +5,7 @@ import fsSync from "node:fs";
 import fsPromises from "node:fs/promises";
 import path from "node:path";
 import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
+import { GUEST_FILESYSTEM_PYTHON } from "@openclaw/fs-safe/guest";
 import { createDeferred, formatPluginConfigIssue, mapPluginConfigIssues } from "openclaw/plugin-sdk/extension-shared";
 import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
 import { FsSafeError, canonicalPathFromExistingAncestor, extractErrorCode } from "openclaw/plugin-sdk/security-runtime";
@@ -12,7 +13,7 @@ import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coer
 import { buildPluginConfigSchema } from "openclaw/plugin-sdk/core";
 import { MAX_TIMER_TIMEOUT_SECONDS } from "openclaw/plugin-sdk/number-runtime";
 import { z } from "zod";
-import { assertNoSymlinkParents, canonicalPathFromExistingAncestor as canonicalPathFromExistingAncestor$1, isPathInside, root } from "openclaw/plugin-sdk/file-access-runtime";
+import { assertNoSymlinkParents, isPathInside, root } from "openclaw/plugin-sdk/file-access-runtime";
 import pLimit from "p-limit";
 //#region extensions/openshell/src/cli.ts
 function buildOpenShellBaseArgv(config) {
@@ -63,17 +64,6 @@ const DEFAULT_REMOTE_WORKSPACE_DIR = "/sandbox";
 const DEFAULT_REMOTE_AGENT_WORKSPACE_DIR = "/agent";
 const DEFAULT_TIMEOUT_MS = 12e4;
 const OPEN_SHELL_MANAGED_REMOTE_ROOTS = [DEFAULT_REMOTE_WORKSPACE_DIR, DEFAULT_REMOTE_AGENT_WORKSPACE_DIR];
-function normalizeProviders(value) {
-	const seen = /* @__PURE__ */ new Set();
-	const providers = [];
-	for (const entry of value ?? []) {
-		const normalized = entry.trim();
-		if (seen.has(normalized)) continue;
-		seen.add(normalized);
-		providers.push(normalized);
-	}
-	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" });
@@ -120,22 +110,7 @@ function createOpenShellPluginConfigSchema() {
 	} });
 }
 function resolveOpenShellPluginConfig(value) {
-	if (value === void 0) return {
-		mode: DEFAULT_MODE,
-		command: DEFAULT_COMMAND,
-		gateway: void 0,
-		gatewayEndpoint: void 0,
-		workspace: void 0,
-		from: DEFAULT_SOURCE,
-		policy: void 0,
-		providers: [],
-		gpu: false,
-		autoProviders: true,
-		remoteWorkspaceDir: DEFAULT_REMOTE_WORKSPACE_DIR,
-		remoteAgentWorkspaceDir: DEFAULT_REMOTE_AGENT_WORKSPACE_DIR,
-		timeoutMs: DEFAULT_TIMEOUT_MS
-	};
-	const parsed = OpenShellPluginConfigSchema.safeParse(value);
+	const parsed = OpenShellPluginConfigSchema.safeParse(value === void 0 ? {} : value);
 	if (!parsed.success) {
 		const message = formatPluginConfigIssue(parsed.error.issues[0]);
 		throw new Error(`Invalid openshell plugin config: ${message}`);
@@ -149,7 +124,7 @@ function resolveOpenShellPluginConfig(value) {
 		workspace: cfg.workspace,
 		from: cfg.from ?? DEFAULT_SOURCE,
 		policy: cfg.policy,
-		providers: normalizeProviders(cfg.providers),
+		providers: [...new Set(cfg.providers ?? [])],
 		gpu: cfg.gpu ?? false,
 		autoProviders: cfg.autoProviders ?? true,
 		remoteWorkspaceDir: normalizeOpenShellRemotePath(cfg.remoteWorkspaceDir, DEFAULT_REMOTE_WORKSPACE_DIR, "remoteWorkspaceDir"),
@@ -196,64 +171,49 @@ var OpenShellFsBridge = class {
 	}
 	async readFile(params) {
 		const target = this.resolveTarget(params);
-		const hostPath = this.requireHostPath(target);
-		let opened;
+		const hostPath = target.hostPath;
 		try {
-			await assertLocalPathSafety({
-				target,
-				allowFinalSymlinkForUnlink: false
-			});
-			const root$1 = await root(target.mountHostRoot);
-			if (params.maxBytes !== void 0) return (await root$1.read(path.relative(target.mountHostRoot, hostPath), {
+			return (await (await root(target.mountHostRoot)).read(relativeToRoot(target, hostPath), {
 				hardlinks: "reject",
-				maxBytes: params.maxBytes
+				maxBytes: params.maxBytes ?? Infinity
 			})).buffer;
-			opened = await root$1.open(path.relative(target.mountHostRoot, hostPath), { hardlinks: "reject" });
-			try {
-				return await opened.handle.readFile();
-			} finally {
-				await opened.handle.close();
-			}
 		} catch (err) {
 			throw new Error(`Sandbox boundary checks failed; cannot read files: ${target.containerPath}`, { cause: err });
 		}
 	}
 	async readDirectory(params) {
 		const target = this.resolveTarget(params);
-		const hostPath = this.requireHostPath(target);
-		await assertLocalPathSafety({
-			target,
-			allowFinalSymlinkForUnlink: false
-		});
-		return (await (await root(target.mountHostRoot)).list(relativeToRoot(target, hostPath), { withFileTypes: true })).map(({ name, isDirectory }) => ({
+		const hostPath = target.hostPath;
+		const root$1 = await root(target.mountHostRoot);
+		const entries = [];
+		for await (const { name, isDirectory } of root$1.entries(relativeToRoot(target, hostPath), { order: "sorted" })) entries.push({
 			name,
 			isDirectory
-		}));
+		});
+		return entries;
 	}
 	async writeFile(params) {
 		const target = this.resolveTarget(params);
-		const hostPath = this.requireHostPath(target);
+		const hostPath = target.hostPath;
 		this.ensureWritable(target, "write files");
-		await assertLocalPathSafety({
-			target,
-			allowFinalSymlinkForUnlink: false
-		});
 		const buffer = Buffer.isBuffer(params.data) ? params.data : Buffer.from(params.data, params.encoding ?? "utf8");
-		await (await root(target.mountHostRoot)).write(path.relative(target.mountHostRoot, hostPath), buffer, { mkdir: params.mkdir });
+		await (await root(target.mountHostRoot)).write(relativeToRoot(target, hostPath), buffer, {
+			mkdir: params.mkdir,
+			mutationSymlinks: "reject"
+		});
 		await this.backend.syncLocalPathToRemote(hostPath, target.containerPath);
 	}
 	async createFileExclusive(params) {
 		const target = this.resolveTarget(params);
-		const hostPath = this.requireHostPath(target);
+		const hostPath = target.hostPath;
 		this.ensureWritable(target, "create files");
-		await assertLocalPathSafety({
-			target,
-			allowFinalSymlinkForUnlink: false
-		});
 		const buffer = Buffer.isBuffer(params.data) ? params.data : Buffer.from(params.data, params.encoding ?? "utf8");
 		const root$2 = await root(target.mountHostRoot);
 		try {
-			await root$2.create(path.relative(target.mountHostRoot, hostPath), buffer, { mkdir: params.mkdir !== false });
+			await root$2.create(relativeToRoot(target, hostPath), buffer, {
+				mkdir: params.mkdir !== false,
+				mutationSymlinks: "reject"
+			});
 		} catch (error) {
 			if (error instanceof FsSafeError && error.code === "already-exists") return "exists";
 			throw error;
@@ -263,7 +223,7 @@ var OpenShellFsBridge = class {
 	}
 	async mkdirp(params) {
 		const target = this.resolveTarget(params);
-		const hostPath = this.requireHostPath(target);
+		const hostPath = target.hostPath;
 		this.ensureWritable(target, "create directories");
 		await assertLocalPathSafety({
 			target,
@@ -277,7 +237,7 @@ var OpenShellFsBridge = class {
 	}
 	async remove(params) {
 		const target = this.resolveTarget(params);
-		const hostPath = this.requireHostPath(target);
+		const hostPath = target.hostPath;
 		this.ensureWritable(target, "remove files", params.recursive);
 		await assertLocalPathSafety({
 			target,
@@ -297,8 +257,8 @@ var OpenShellFsBridge = class {
 	}
 	async rename(params) {
 		const { from, to } = this.resolveRenameTargets(params);
-		const fromHostPath = this.requireHostPath(from);
-		const toHostPath = this.requireHostPath(to);
+		const fromHostPath = from.hostPath;
+		const toHostPath = to.hostPath;
 		await assertLocalPathSafety({
 			target: from,
 			allowFinalSymlinkForUnlink: true
@@ -324,7 +284,7 @@ var OpenShellFsBridge = class {
 	}
 	async stat(params) {
 		const target = this.resolveTarget(params);
-		const hostPath = this.requireHostPath(target);
+		const hostPath = target.hostPath;
 		const stats = await fsPromises.lstat(hostPath).catch(() => null);
 		if (!stats) return null;
 		await assertLocalPathSafety({
@@ -348,10 +308,6 @@ var OpenShellFsBridge = class {
 			workdir
 		})), ...this.sandbox.readOnlyResourceMounts ?? []];
 	}
-	requireHostPath(target) {
-		if (!target.hostPath) throw new Error(`OpenShell mirror bridge requires a local host path: ${target.containerPath}`);
-		return target.hostPath;
-	}
 	containerMounts(readOnlyMounts = this.readOnlyMounts()) {
 		const workspaceRoot = path.resolve(this.sandbox.workspaceDir);
 		const agentRoot = path.resolve(this.sandbox.agentWorkspaceDir);
@@ -450,7 +406,7 @@ async function removeLocalRootPath(params) {
 	const relativePath = relativeToRoot(params.target, params.hostPath);
 	try {
 		if (params.force === false) await fsPromises.lstat(params.hostPath);
-		const targets = params.recursive && !relativePath ? await root$3.list("") : [relativePath];
+		const targets = params.recursive && !relativePath ? (await root$3.list("")).map((name) => relativeToRoot(params.target, path.join(params.hostPath, name))) : [relativePath];
 		for (const target of targets) await root$3.remove(target, {
 			force: params.force !== false,
 			...params.recursive ? {
@@ -479,7 +435,7 @@ async function mkdirParentPath(root, relativePath) {
 }
 function relativeToRoot(target, hostPath) {
 	const relativePath = path.relative(target.mountHostRoot, hostPath);
-	return relativePath === "." ? "" : relativePath;
+	return relativePath ? `.${path.sep}${relativePath}` : "";
 }
 async function assertRenameSourceSupported(fromHostPath) {
 	const stats = await fsPromises.lstat(fromHostPath);
@@ -513,21 +469,14 @@ async function nearestExistingDirectoryStats(params) {
 	return await fsPromises.lstat(rootPath);
 }
 function isNotFoundError(err) {
-	return err instanceof FsSafeError && err.code === "not-found" || typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+	return err instanceof FsSafeError && err.code === "not-found" || extractErrorCode(err) === "ENOENT";
 }
 async function assertLocalPathSafety(params) {
 	const { hostPath, mountHostRoot } = params.target;
-	if (!hostPath) throw new Error(`Missing local host path for ${params.target.containerPath}`);
-	const canonicalRoot = await fsPromises.realpath(mountHostRoot).catch((error) => {
-		if (isNotFoundError(error)) return path.resolve(mountHostRoot);
-		throw error;
-	});
 	const unlinkSymlink = params.allowFinalSymlinkForUnlink && hostPath !== mountHostRoot && (await fsPromises.lstat(hostPath).catch((error) => {
 		if (isNotFoundError(error)) return null;
 		throw error;
 	}))?.isSymbolicLink();
-	const candidate = unlinkSymlink ? path.resolve(canonicalRoot, path.relative(mountHostRoot, hostPath)) : await canonicalPathFromExistingAncestor$1(hostPath);
-	if (!isPathInside(canonicalRoot, candidate)) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${params.target.containerPath}`);
 	await assertNoSymlinkParents({
 		rootDir: mountHostRoot,
 		targetPath: unlinkSymlink ? path.dirname(hostPath) : hostPath,
@@ -619,107 +568,28 @@ function buildOpenShellDirectoryUploadArgs(params) {
 	];
 }
 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; }",
-	"validate_basename() {",
-	"  case \"$1\" in \"\"|\".\"|\"..\"|*/*) die \"unsafe remote basename: $1\" ;; esac",
-	"}",
-	"pin_dir() {",
-	"  root=\"$1\"",
-	"  relative=\"$2\"",
-	"  create=\"$3\"",
-	"  case \"$root\" in /*) ;; *) die \"remote root must be absolute: $root\" ;; esac",
-	"  root=\"${root%/}\"",
-	"  [ -n \"$root\" ] || root=\"/\"",
-	"  if [ -L \"$root\" ]; then die \"unsafe remote root symlink: $root\"; fi",
-	"  mkdir -p -- \"$root\"",
-	"  canonical_root=\"$(cd \"$root\" && pwd -P)\"",
-	"  current=\"$canonical_root\"",
-	"  relative=\"${relative#/}\"",
-	"  while [ -n \"$relative\" ]; do",
-	"    part=\"${relative%%/*}\"",
-	"    if [ \"$part\" = \"$relative\" ]; then relative=\"\"; else relative=\"${relative#*/}\"; fi",
-	"    [ -n \"$part\" ] || continue",
-	"    case \"$part\" in \".\"|\"..\") die \"unsafe remote directory component: $part\" ;; esac",
-	"    if [ \"$current\" = \"/\" ]; then next=\"/$part\"; else next=\"$current/$part\"; fi",
-	"    if [ -L \"$next\" ]; then die \"unsafe remote directory symlink: $next\"; fi",
-	"    if [ -e \"$next\" ]; then",
-	"      if [ ! -d \"$next\" ]; then die \"unsafe remote directory component: $next\"; fi",
-	"    else",
-	"      if [ \"$create\" != \"1\" ]; then die \"remote directory not found: $next\"; fi",
-	"      mkdir -- \"$next\"",
-	"    fi",
-	"    current=\"$next\"",
-	"  done",
-	"  printf \"%s\\n\" \"$current\"",
-	"}",
-	"pin_dir_or_missing() {",
-	"  root=\"$1\"",
-	"  relative=\"$2\"",
-	"  missing_ok=\"$3\"",
-	"  case \"$root\" in /*) ;; *) die \"remote root must be absolute: $root\" ;; esac",
-	"  root=\"${root%/}\"",
-	"  [ -n \"$root\" ] || root=\"/\"",
-	"  if [ -L \"$root\" ]; then die \"unsafe remote root symlink: $root\"; fi",
-	"  if [ ! -d \"$root\" ]; then",
-	"    if [ -e \"$root\" ]; then die \"unsafe remote root component: $root\"; fi",
-	"    if [ \"$missing_ok\" = \"1\" ]; then printf \"\\n\"; return 0; fi",
-	"    die \"remote directory not found: $root\"",
-	"  fi",
-	"  canonical_root=\"$(cd \"$root\" && pwd -P)\"",
-	"  current=\"$canonical_root\"",
-	"  relative=\"${relative#/}\"",
-	"  while [ -n \"$relative\" ]; do",
-	"    part=\"${relative%%/*}\"",
-	"    if [ \"$part\" = \"$relative\" ]; then relative=\"\"; else relative=\"${relative#*/}\"; fi",
-	"    [ -n \"$part\" ] || continue",
-	"    case \"$part\" in \".\"|\"..\") die \"unsafe remote directory component: $part\" ;; esac",
-	"    if [ \"$current\" = \"/\" ]; then next=\"/$part\"; else next=\"$current/$part\"; fi",
-	"    if [ -L \"$next\" ]; then die \"unsafe remote directory symlink: $next\"; fi",
-	"    if [ -e \"$next\" ]; then",
-	"      if [ ! -d \"$next\" ]; then die \"unsafe remote directory component: $next\"; fi",
-	"    else",
-	"      if [ \"$missing_ok\" = \"1\" ]; then printf \"\\n\"; return 0; fi",
-	"      die \"remote directory not found: $next\"",
-	"    fi",
-	"    current=\"$next\"",
-	"  done",
-	"  printf \"%s\\n\" \"$current\"",
-	"}",
-	"operation=\"$1\"",
-	"case \"$operation\" in",
-	"  mkdirp)",
-	"    pin_dir \"$2\" \"$3\" 1 >/dev/null",
-	"    ;;",
-	"  remove)",
-	"    validate_basename \"$4\"",
-	"    parent=\"$(pin_dir_or_missing \"$2\" \"$3\" \"${5:-0}\")\"",
-	"    [ -n \"$parent\" ] || exit 0",
-	"    target=\"$parent/$4\"",
-	"    if [ -d \"$target\" ] && [ ! -L \"$target\" ]; then rm -rf -- \"$target\"; elif [ -e \"$target\" ] || [ -L \"$target\" ]; then rm -f -- \"$target\"; fi",
-	"    ;;",
-	"  removefile)",
-	"    validate_basename \"$4\"",
-	"    parent=\"$(pin_dir_or_missing \"$2\" \"$3\" \"${5:-0}\")\"",
-	"    [ -n \"$parent\" ] || exit 0",
-	"    target=\"$parent/$4\"",
-	"    if [ -d \"$target\" ] && [ ! -L \"$target\" ]; then rmdir -- \"$target\"; elif [ -e \"$target\" ] || [ -L \"$target\" ]; then rm -f -- \"$target\"; fi",
-	"    ;;",
-	"  rename)",
-	"    src_parent=\"$(pin_dir \"$2\" \"$3\" 0)\"",
-	"    validate_basename \"$4\"",
-	"    dst_parent=\"$(pin_dir \"$5\" \"$6\" 1)\"",
-	"    validate_basename \"$7\"",
-	"    if [ -L \"$dst_parent/$7\" ]; then die \"unsafe remote rename target symlink: $dst_parent/$7\"; fi",
-	"    if [ -d \"$dst_parent/$7\" ]; then die \"unsafe remote rename target directory: $dst_parent/$7\"; fi",
-	"    mv -- \"$src_parent/$4\" \"$dst_parent/$7\"",
-	"    ;;",
-	"  *)",
-	"    die \"unknown remote path mutation: $operation\"",
-	"    ;;",
-	"esac"
-].join("\n");
+const OPEN_SHELL_GUEST_MUTATION_PYTHON = `
+import os, sys
+guest = sys.argv.pop(1)
+ignore_missing_parent = sys.argv.pop(1) == '1'
+operation = sys.argv[1]
+for index in ((2, 5) if operation == 'rename' else (2,)):
+    root = sys.argv[index].rstrip('/') or '/'
+    sys.argv[index] = root
+    if not os.path.isabs(root) or os.path.islink(root):
+        raise OSError('unsafe remote root: ' + root)
+    if operation != 'remove':
+        os.makedirs(root, exist_ok=True)
+if operation == 'rename':
+    target = os.path.join(sys.argv[5], sys.argv[6], sys.argv[7])
+    if os.path.islink(target) or os.path.isdir(target):
+        raise OSError('unsafe remote rename target: ' + target)
+try:
+    exec(guest)
+except FileNotFoundError:
+    if operation != 'remove' or not ignore_missing_parent:
+        raise
+`;
 const ENSURE_OPEN_SHELL_REMOTE_REAL_DIRECTORY_SCRIPT = [
 	"set -e",
 	"target=\"$1\"",
@@ -767,9 +637,6 @@ const ENSURE_OPEN_SHELL_REMOTE_REAL_DIRECTORY_SCRIPT = [
 	"  current=\"$next\"",
 	"done"
 ].join("\n");
-function buildOpenShellSshExecEnv() {
-	return sanitizeEnvVars(process.env).allowed;
-}
 function createOpenShellSandboxBackendFactory(params) {
 	return async (createParams) => await createOpenShellSandboxBackend({
 		...params,
@@ -868,7 +735,7 @@ var OpenShellSandboxBackendImpl = class {
 				});
 				return {
 					argv: pending.argv,
-					env: buildOpenShellSshExecEnv(),
+					env: sanitizeEnvVars(process.env).allowed,
 					stdinMode: "pipe-open",
 					finalizeToken: pending.token
 				};
@@ -1004,16 +871,7 @@ var OpenShellSandboxBackendImpl = class {
 	}
 	resolveWorkdirValidationRoot(workdir) {
 		try {
-			const normalized = normalizeRemotePath(workdir);
-			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;
+			return this.resolveRemoteTarget(workdir).root;
 		} catch {
 			return this.params.remoteWorkspaceDir;
 		}
@@ -1080,12 +938,14 @@ var OpenShellSandboxBackendImpl = class {
 		const target = this.resolveRemoteTarget(remotePath);
 		await this.runPinnedRemotePathMutation({
 			args: [
-				params?.recursive ? "remove" : "removefile",
+				"remove",
 				target.root,
 				path.posix.dirname(target.relativePath) === "." ? "" : path.posix.dirname(target.relativePath),
 				path.posix.basename(target.relativePath),
-				params?.ignoreMissing ? "1" : "0"
+				params?.recursive ? "1" : "0",
+				"1"
 			],
+			ignoreMissingParent: params?.ignoreMissing,
 			signal: params?.signal
 		});
 	}
@@ -1100,7 +960,8 @@ var OpenShellSandboxBackendImpl = class {
 				path.posix.basename(from.relativePath),
 				to.root,
 				path.posix.dirname(to.relativePath) === "." ? "" : path.posix.dirname(to.relativePath),
-				path.posix.basename(to.relativePath)
+				path.posix.basename(to.relativePath),
+				"1"
 			],
 			signal
 		});
@@ -1130,24 +991,11 @@ var OpenShellSandboxBackendImpl = class {
 		await this.maybeSeedRemoteWorkspace();
 		const target = this.resolveRemoteTarget(remotePath);
 		const stats = await fsPromises.lstat(localPath).catch(() => null);
-		if (!stats) {
-			await this.runPinnedRemotePathMutation({ args: [
-				"remove",
-				target.root,
-				path.posix.dirname(target.relativePath) === "." ? "" : path.posix.dirname(target.relativePath),
-				path.posix.basename(target.relativePath),
-				"1"
-			] });
-			return;
-		}
-		if (stats.isSymbolicLink()) {
-			await this.runPinnedRemotePathMutation({ args: [
-				"remove",
-				target.root,
-				path.posix.dirname(target.relativePath) === "." ? "" : path.posix.dirname(target.relativePath),
-				path.posix.basename(target.relativePath),
-				"1"
-			] });
+		if (!stats || stats.isSymbolicLink()) {
+			await this.removeRemotePath(remotePath, {
+				recursive: true,
+				ignoreMissing: true
+			});
 			return;
 		}
 		if (stats.isDirectory()) {
@@ -1175,8 +1023,13 @@ var OpenShellSandboxBackendImpl = class {
 	}
 	async runPinnedRemotePathMutation(params) {
 		return await this.runRemoteShellScript({
-			script: PINNED_REMOTE_PATH_MUTATION_SCRIPT,
-			args: params.args,
+			script: "python_script=\"$1\"; shift; python3 -c \"$python_script\" \"$@\"",
+			args: [
+				OPEN_SHELL_GUEST_MUTATION_PYTHON,
+				GUEST_FILESYSTEM_PYTHON,
+				params.ignoreMissingParent ? "1" : "0",
+				...params.args
+			],
 			signal: params.signal
 		});
 	}
@@ -1412,7 +1265,7 @@ var OpenShellSandboxBackendImpl = class {
 					}
 					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") await moveLocalShadowAside({
+					await moveLocalShadowAside({
 						workspaceDir: root.local,
 						tmpDir,
 						relativeParts: MATERIALIZED_SKILLS_REMOTE_PARTS,
@@ -1567,14 +1420,7 @@ async function removeDownloadedWorkspacePath(tmpDir, parts) {
 		const next = path.join(cursor, part);
 		const stats = await fsPromises.lstat(next).catch(() => null);
 		if (!stats) return;
-		if (index === parts.length - 1) {
-			await fsPromises.rm(next, {
-				recursive: true,
-				force: true
-			});
-			return;
-		}
-		if (stats.isSymbolicLink() || !stats.isDirectory()) {
+		if (index === parts.length - 1 || stats.isSymbolicLink() || !stats.isDirectory()) {
 			await fsPromises.rm(next, {
 				recursive: true,
 				force: true

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

@@ -2,6 +2,108 @@
 
 ## Unreleased
 
+## 0.21.1 - 2026-09-27
+
+### Fixes
+
+- **Linux without `openat2`:** native opens now follow in-root relative symlinks exactly as `RESOLVE_BENEATH` does, rejecting absolute links, `..` escapes, procfs and `nosymfollow` links, and chains longer than 40. Denial and symlink policies report the same errors as the `openat2` path. Links inside sticky world-writable directories are refused. ([#717](https://github.com/openclaw/fs-safe/pull/717))
+- **Deny policies on case-insensitive filesystems:** `denyMutations` now denies creating a not-yet-existing case or Unicode-normalization alias of a denied path (for example `case.txt` when `Case.txt` is denied on APFS, NTFS or casefold ext4). Where a filesystem's sensitivity cannot be proven, Unicode-equivalent names are denied conservatively. ([#720](https://github.com/openclaw/fs-safe/pull/720))
+- **Directory listings:** `list()`, `entries()` and `walk()` reject names that are not valid UTF-8 with `invalid-path` instead of decoding them lossily, which could collide with a real `U+FFFD` name and report another entry's metadata. ([#715](https://github.com/openclaw/fs-safe/pull/715))
+- **ZIP admission:** entries that differ only by case or Unicode normalization are rejected during preflight and member reads, matching extraction's collision policy. ([#716](https://github.com/openclaw/fs-safe/pull/716))
+- **Atomic restore:** when a metadata call fails with `EIO` after the destination was truncated, restore-original writes the original bytes back through the retained, identity-verified descriptor instead of leaving the file empty. ([#718](https://github.com/openclaw/fs-safe/pull/718))
+- **Lock and prune cleanup:** cleanup decisions compare exact bigint file identities. Legacy numeric receipts with IDs above 2^53 are refused instead of risking removal of the wrong file. ([#719](https://github.com/openclaw/fs-safe/pull/719))
+- **Watch overflow:** subscriptions no longer publish spurious whole-scope overflow invalidations for excluded or unselected paths or for slow reconcile passes. macOS streams use OS-level exclusion paths and anchor-scoped streams, and Windows uses a 1 MiB change buffer on local volumes. Genuine OS event drops still invalidate. ([#724](https://github.com/openclaw/fs-safe/pull/724))
+- **Mutation authority:** reject synchronous and asynchronous generator callback results before mutation, so lazy authority checks cannot be skipped. ([#711](https://github.com/openclaw/fs-safe/pull/711))
+- **Synchronous atomic writes:** reject deferred `beforeRename` hooks before publication and clean up the owned stage. ([#728](https://github.com/openclaw/fs-safe/pull/728))
+- **Copy publication callbacks:** reject deferred generator observers in `Root.copyIn()` while preserving the completed destination and source bytes. ([#726](https://github.com/openclaw/fs-safe/pull/726))
+- **Native move diagnostics:** no-clobber `Root.move()` keeps the original native loader error as its cause, including missing libraries or incompatible glibc versions. ([#709](https://github.com/openclaw/fs-safe/pull/709))
+
+### Features
+
+- **Watch polling interval:** `pollIntervalMs` sets the scan interval whenever polling is the selected transport, including `mode: "auto"` falling back to polling, without changing the events reconcile interval. ([#723](https://github.com/openclaw/fs-safe/pull/723))
+
+### Performance
+
+- **Linux directory cloning:** reuse the admitted filesystem type when creating clone sources and cloning trees, avoiding a duplicate filesystem probe and allocation per operation. ([#732](https://github.com/openclaw/fs-safe/pull/732))
+
+## 0.21.0 - 2026-09-26
+
+### Highlights
+
+- **Guarded filesystem observation:** `@openclaw/fs-safe/watch` observes literal entry and tree scopes beneath an admitted Root and delivers bounded advisory invalidations; guarded scans stay authoritative. One shared Rust event thread per process uses inotify, FSEvents and ReadDirectoryChangesW on Linux, macOS and Windows, sleeps while idle, and falls back to portable polling under `mode: "auto"`. Subscriptions become ready after one baseline scan, stay available under sustained writes, fence stale generations on `setScopes()`, join native work on `close()`, and support `persistent: false` so one-shot Node commands can exit. Thanks @vincentkoc. ([#690](https://github.com/openclaw/fs-safe/pull/690), [#695](https://github.com/openclaw/fs-safe/pull/695), [#697](https://github.com/openclaw/fs-safe/pull/697), [#703](https://github.com/openclaw/fs-safe/pull/703), [#707](https://github.com/openclaw/fs-safe/pull/707))
+- **Linux user namespaces:** private temp workspaces now work beneath unmapped ancestors, including systemd user services with `PrivateUsers=true`, while UID/GID mappings and ancestor permissions are still rechecked. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+
+### Features
+
+- **Revocable atomic writes:** atomic replacement can recheck caller authority before new effects and report retained destination identities for partial writes and publication, without treating receipts as permission to roll back. ([#694](https://github.com/openclaw/fs-safe/pull/694))
+- **Root walking:** `symlinkPolicy: "include"` reports links without following their targets, preserving sorted traversal, entry budgets, and the existing skip/follow result types. Directory-to-symlink substitutions fail before descent. ([#692](https://github.com/openclaw/fs-safe/pull/692))
+- **Windows file retirement:** the advanced surface can retire existing NTFS files through a retained handle, with exact producer identity, current authority, and separate disposition and settlement facts. There is no persistence guarantee. ([#706](https://github.com/openclaw/fs-safe/pull/706))
+
+### Performance
+
+- **Temporary filename sanitization:** skip duplicate normalization after reserved-device suffixing while preserving filename admission and fallback rules. ([#689](https://github.com/openclaw/fs-safe/pull/689))
+
+### Compatibility
+
+- Supplied temp workspace roots must be owned by the effective user and must not be group- or world-writable; use a private per-user root instead of shared `/tmp`. A one-time warning reports host ownership that cannot be verified. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+- On Windows, an events-mode watch holds one handle on each watched Root, so the Root's own ancestor directories cannot be renamed while it is open; renaming inside the Root is unaffected. Use `mode: "poll"` where that matters. ([#697](https://github.com/openclaw/fs-safe/pull/697))
+- `watch()` requires an explicit `mode` (`"auto"`, `"events"` or `"poll"`); `"events"` fails readiness with `helper-unavailable` when no native backend is available, and Bun currently selects polling under `"auto"`. ([#690](https://github.com/openclaw/fs-safe/pull/690))
+
+## 0.20.0 - 2026-09-25
+
+### Highlights
+
+- **Older Linux systems:** when `openat2` is absent (Linux before 5.6) or blocked by seccomp, native operations fall back to a guarded no-follow walk instead of failing with `ENOSYS`. Nested no-clobber moves keep working, and GNU x64/arm64 bindings now target glibc 2.28, so native operations load on RHEL 8-family systems. ([#686](https://github.com/openclaw/fs-safe/pull/686), [#685](https://github.com/openclaw/fs-safe/pull/685); fixes [#572](https://github.com/openclaw/fs-safe/issues/572), [#511](https://github.com/openclaw/fs-safe/issues/511), [#548](https://github.com/openclaw/fs-safe/issues/548))
+- **Path hardening:** trash moves stay inside allowed roots, symlink-parent checks inspect raw segments before dotdot normalization, relative-escape checks recognize either Windows separator and nested escapes, and safe path segments reject Windows reserved device names. Thanks @SebTardif. ([#611](https://github.com/openclaw/fs-safe/pull/611), [#615](https://github.com/openclaw/fs-safe/pull/615), [#614](https://github.com/openclaw/fs-safe/pull/614), [#612](https://github.com/openclaw/fs-safe/pull/612))
+- **ZIP admission per operation:** portable ZIP reads and extraction bind entry selection to the admitted archive, name, and decoder object, and verify payloads against the admitted CRC and size. Substituted, renamed, or replaced decoder entries are rejected. ([#660](https://github.com/openclaw/fs-safe/pull/660))
+
+### Features
+
+- **Retained symlink publication:** `retainSymlinkInDirectory()` on the advanced surface holds an explicitly identified POSIX symlink through exact-slot no-replace publication and explicit recovery, preserving observed foreign replacements and uncertain outcomes. ([#682](https://github.com/openclaw/fs-safe/pull/682))
+- **Batched Windows ACL facts:** `readOwnerAndDaclBatch()` inspects ordered paths in one isolated native worker or one PowerShell process, with a configurable whole-batch timeout and bounded output. Results are bounded during collection; oversized batches reject with `too-large` before later paths are queried. ([#669](https://github.com/openclaw/fs-safe/pull/669), [#680](https://github.com/openclaw/fs-safe/pull/680))
+- **Atomic text options:** `writeTextAtomic()` forwards the existing `beforeRename` hook and `tempPrefix` option to atomic replacement, keeping its validation and identity checks. ([#580](https://github.com/openclaw/fs-safe/pull/580))
+
+### Fixes
+
+- **Lock exit cleanup:** leave raw sidecars in place when Windows reports an unknown device or inode, while keeping token-owned cleanup working when the descriptor and path identities legitimately differ (for example on VirtioFS). Thanks @SebTardif. ([#617](https://github.com/openclaw/fs-safe/pull/617))
+- **Retained symlink errors:** preserve uncertain publication outcomes and cached cleanup/recovery failures when inspecting thrown error metadata fails, retaining the original cause without retrying mutations, callbacks, or descriptor closes. ([#684](https://github.com/openclaw/fs-safe/pull/684))
+- **Create collision cleanup:** atomic and streamed creates remove their private stage when the JavaScript fallback observes a competing destination before publication; failures after a link attempt retain their existing recovery evidence. ([#683](https://github.com/openclaw/fs-safe/pull/683))
+
+### Compatibility
+
+- Safe path segments now reject Windows reserved device names (`CON`, `NUL`, `COM1`, `CON.json`, …) on every platform, because segments are portable identifiers. Temporary filename sanitization still suffixes them (`CON.txt` becomes `CON_.txt`). ([#612](https://github.com/openclaw/fs-safe/pull/612))
+- `assertNoSymlinkParents()` and guarded appends with `rejectSymlinkParents` reject raw spellings whose dotdot segments would cancel a symlink or re-enter the root after leaving it. ([#615](https://github.com/openclaw/fs-safe/pull/615))
+- Without `openat2`, beneath opens report `best-effort` containment instead of `kernel-atomic`, anonymous `O_TMPFILE` opens report `ENOTSUP`, and bounded tree cleanup fails closed with `helper-unavailable` because it requires `RESOLVE_NO_XDEV`. ([#686](https://github.com/openclaw/fs-safe/pull/686))
+- The Linux GNU binding floor is glibc 2.28 for both x64 and arm64 (arm64 was previously built against 2.17), matching Node 22's own Linux baseline. ([#685](https://github.com/openclaw/fs-safe/pull/685))
+
+## 0.19.0 - 2026-09-24
+
+### Highlights
+
+- **Strict secret-file durability:** `createSecretFileAtomic()` accepts `durable: "file"` to require every file flush to succeed, including on `EPERM`; parent-directory synchronization remains best effort. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- **Literal `~` names:** keep FileStore keys, absolute Root reads, discovered walk entries, and ZIP/TAR entries literal instead of treating them as home-directory shorthand. Reads, writes, removal, pruning, extraction, and durable publication select the intended entry. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- **Native Unix descriptor safety:** reject negative descriptors in low-level root, query, hash, copy, clone, staging, and cleanup calls without Rust panics or working-directory operations. Modern macOS beneath opens report `EBADF` for negative roots instead of `EIO`. ([#640](https://github.com/openclaw/fs-safe/pull/640), [#643](https://github.com/openclaw/fs-safe/pull/643), [#646](https://github.com/openclaw/fs-safe/pull/646))
+
+### Fixes
+
+- **Guest directory permissions:** cross-device moves preserve mode `000`, including nested directories, without changing other modes' umask behavior. Restore top-level permissions through the retained directory descriptor and preserve published entries on failure. Thanks @SebTardif. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- **ReFS clone cleanup:** remove ordinary partial output when Windows rejects the ignore-readonly deletion flag. Keep readonly attributes intact and include cleanup failures in the original clone error; readonly files or other processes' open handles can still leave output behind. ([#648](https://github.com/openclaw/fs-safe/pull/648))
+
+### Compatibility and documentation
+
+- Secret creation's default and boolean durability options retain their behavior, and `writeSecretFileAtomic()` remains boolean-only. Strict file synchronization preserves existing publication and cleanup semantics: a failure after publication can leave a complete file present. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- `Root.walk("~")` and `Root.walk("~/dir")` expand home shorthand when iteration starts and return admitted canonical paths relative to the Root. Use `./~/dir` for a literal tilde directory, and prefix returned entry paths with `./` when passing them to another Root method. Relative Root `~/name` inputs still expand home; FileStore keys do not. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- Guest moves still require OS permission to read mode-000 source directories; they do not widen source permissions. If permission restoration fails after publication, the source and published copy remain for caller reconciliation. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- Clarify that `Root.append()` and `openWritable()` creation modes remain subject to the process umask and do not chmod existing files. This documents existing behavior. ([#636](https://github.com/openclaw/fs-safe/pull/636))
+
+## 0.18.2 - 2026-09-22
+
+### Fixes
+
+- **Lock errors:** preserve Root stale-removal rejections and `null` or `undefined` retry failures instead of masking them with timeouts or `TypeError`s. ([#624](https://github.com/openclaw/fs-safe/pull/624))
+- **Secret-file reads:** report caught `null` or `undefined` inspection and read failures as structured errors instead of internal `TypeError`s. ([#623](https://github.com/openclaw/fs-safe/pull/623))
+- **Secret-file creation:** preserve `null` or `undefined` thrown by parameter getters instead of masking them with an internal `TypeError`. ([#625](https://github.com/openclaw/fs-safe/pull/625))
+
 ## 0.18.1 - 2026-09-22
 
 ### Fixes