@openclaw/openshell-sandbox 2026.9.2 → 2026.9.3

package/dist/index.js

@@ -1,11 +1,13 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 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 fsSync from "node:fs";
 import fsPromises from "node:fs/promises";
 import path from "node:path";
+import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
 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 { FsSafeError, canonicalPathFromExistingAncestor, extractErrorCode } 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";
@@ -218,6 +220,20 @@ var OpenShellFsBridge = class {
 			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,
+			root: target.mountHostRoot,
+			allowMissingLeaf: false,
+			allowFinalSymlinkForUnlink: false
+		});
+		return (await (await root(target.mountHostRoot)).list(relativeToRoot(target, hostPath), { withFileTypes: true })).map(({ name, isDirectory }) => ({
+			name,
+			isDirectory
+		}));
+	}
 	async writeFile(params) {
 		const target = this.resolveTarget(params);
 		const hostPath = this.requireHostPath(target);
@@ -913,6 +929,7 @@ var OpenShellSandboxBackendImpl = class {
 		return {
 			resolvePath: (params) => bridge.resolvePath(params),
 			readFile: (params) => this.runWorkspaceOperation(() => bridge.readFile(params), params.signal),
+			readDirectory: (params) => this.runWorkspaceOperation(() => bridge.readDirectory(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),
@@ -1406,39 +1423,51 @@ var OpenShellSandboxBackendImpl = class {
 				});
 				if (result.code !== 0) throw new Error(result.stderr.trim() || "openshell sandbox download failed");
 				const preservedShadows = [];
+				const failures = [];
 				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({
+						await moveLocalShadowAside({
 							workspaceDir: root.local,
 							tmpDir,
-							relativeParts
+							relativeParts,
+							preservedShadows
 						});
-						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);
-					}
+					if (root.owner === "workspace") await moveLocalShadowAside({
+						workspaceDir: root.local,
+						tmpDir,
+						relativeParts: MATERIALIZED_SKILLS_REMOTE_PARTS,
+						preservedShadows
+					});
 					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
-					});
+				} catch (error) {
+					failures.push(error);
+				}
+				const retained = [];
+				for (const preserved of preservedShadows.toReversed()) {
+					if (preserved.sourceRetired) try {
+						const cleanupFailure = await restoreLocalShadow(preserved);
+						if (cleanupFailure) failures.push(cleanupFailure);
+						continue;
+					} catch (error) {
+						failures.push(error);
+					}
+					retained.push(`${preserved.receipt.path} (workspace path: ${preserved.shadowPath})`);
 				}
+				if (retained.length > 0 || failures.length > 1) {
+					const recovery = retained.length > 0 ? ` Inspect the recovery paths ${retained.join("; ")}. Remaining workspace entries were preserved; compare both paths before recovering or deleting either copy.` : "";
+					throw new AggregateError(failures, `OpenShell mirror synchronization failed: ${failures.map(String).join("; ")}.${recovery}`, { cause: failures[0] });
+				}
+				if (failures.length > 0) throw failures[0];
 			});
 		}
 	}
@@ -1588,44 +1617,55 @@ async function moveLocalShadowAside(params) {
 	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, "shadow");
+	let preserved;
 	await movePathWithCopyFallback({
 		from: shadowPath,
-		to: preservedPath
+		to: path.join(preserveRoot, "shadow"),
+		onDestinationPublished: (receipt) => {
+			preserved = {
+				receipt,
+				shadowPath,
+				sourceRetired: false
+			};
+			params.preservedShadows.push(preserved);
+		}
 	});
-	return {
-		preservedPath,
-		preserveRoot,
-		relativeParts: params.relativeParts
-	};
+	if (preserved) preserved.sourceRetired = true;
 }
-async function restoreLocalShadow(params) {
-	let restored = false;
-	try {
-		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 workspace shadow through symlink parent: ${parentPath}`);
-		if (parentStats && !parentStats.isDirectory()) await fsPromises.rm(parentPath, {
-			recursive: true,
-			force: true
-		});
-		await fsPromises.mkdir(parentPath, { recursive: true });
-		await fsPromises.rm(shadowPath, {
-			recursive: true,
-			force: true
-		});
-		await movePathWithCopyFallback({
-			from: params.preserved.preservedPath,
-			to: shadowPath
-		});
-		restored = true;
-	} finally {
-		if (restored) await fsPromises.rm(params.preserved.preserveRoot, {
+function assertPreservedShadowIdentity(receipt) {
+	const stat = fsSync.lstatSync(receipt.path, { bigint: true });
+	if (stat.isSymbolicLink() || stat.dev !== receipt.dev || stat.ino !== receipt.ino || process.platform === "win32" && (stat.dev === 0n || stat.ino === 0n)) throw new Error(`Refusing to restore an unverified workspace shadow: ${receipt.path}`);
+}
+async function restoreLocalShadow(preserved) {
+	const { shadowPath, receipt } = preserved;
+	const assertBackup = () => assertPreservedShadowIdentity(receipt);
+	const parentPath = path.dirname(shadowPath);
+	const parentStats = await fsPromises.lstat(parentPath).catch(() => null);
+	if (parentStats?.isSymbolicLink()) throw new Error(`Refusing to restore workspace shadow through symlink parent: ${parentPath}`);
+	if (parentStats && !parentStats.isDirectory()) {
+		assertBackup();
+		await fsPromises.rm(parentPath, {
 			recursive: true,
 			force: true
 		});
 	}
+	assertBackup();
+	await fsPromises.mkdir(parentPath, { recursive: true });
+	assertBackup();
+	await fsPromises.rm(shadowPath, {
+		recursive: true,
+		force: true
+	});
+	await movePathWithCopyFallback({
+		from: receipt.path,
+		to: shadowPath,
+		assertBeforeMutation: assertBackup
+	});
+	try {
+		await fsPromises.rmdir(path.dirname(receipt.path));
+	} catch (error) {
+		return new Error(`Workspace shadow was restored at ${shadowPath}, but preservation directory cleanup failed at ${path.dirname(receipt.path)}`, { cause: error });
+	}
 }
 function resolveOpenShellTmpRoot() {
 	return path.resolve(resolvePreferredOpenClawTmpDir());