@agent-vm/openclaw-agent-vm-plugin 0.0.81 → 0.0.84

package/dist/index.js

@@ -1,4 +1,5 @@
-import { createToolVmActiveUseHandle, isToolVmLeasePeek, isToolVmSshLease } from "@agent-vm/gateway-interface";
+import path from "node:path/posix";
+import { ControllerRequestPolicyTransportError, OPENCLAW_STATE_SANDBOXES_VM_ROOT, TOOL_VM_SCRATCH_GUEST_ROOT, TOOL_VM_WORKSPACE_GUEST_ROOT, createToolVmActiveUseHandle, drainControllerResponseBody, fetchControllerWithPolicy, gatewayControlLinkHealthPins, isToolVmLeasePeek, isToolVmSshLease, translateRuntimePath } from "@agent-vm/gateway-interface";
 import { z } from "zod";
 //#region src/controller-lease-client.ts
 var ControllerLeaseRequestError = class extends Error {
@@ -46,7 +47,7 @@ function isHeartbeatActiveUseResponse(value) {
 	const record = objectValue(value);
 	return record !== void 0 && typeof Reflect.get(record, "expiresAt") === "number" && typeof Reflect.get(record, "heartbeatAfterMs") === "number";
 }
-function formatUnknownError$1(error) {
+function formatUnknownError$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 function writeLeaseClientLog(message) {
@@ -58,7 +59,7 @@ function parseJsonBody(bodyText, context) {
 		const parsedBody = jsonValueSchema.safeParse(parsedJson);
 		return parsedBody.success ? parsedBody.data : void 0;
 	} catch (error) {
-		writeLeaseClientLog(`${context} returned a non-JSON error body: ${formatUnknownError$1(error)}`);
+		writeLeaseClientLog(`${context} returned a non-JSON error body: ${formatUnknownError$2(error)}`);
 		return;
 	}
 }
@@ -86,15 +87,30 @@ async function readJsonResponse(response, context, isExpectedResponse) {
 function createLeaseClient(options) {
 	const fetchImpl = options.fetchImpl ?? fetch;
 	const baseUrl = options.controllerUrl.replace(/\/$/u, "");
+	const fetchController = async (optionsForRequest) => await fetchControllerWithPolicy({
+		fetchImpl,
+		input: optionsForRequest.input,
+		operation: optionsForRequest.operation,
+		...optionsForRequest.init === void 0 ? {} : { init: optionsForRequest.init },
+		...options.requestPolicy === void 0 ? {} : { policy: options.requestPolicy }
+	});
 	const renewLease = async (leaseId) => {
-		return await readJsonResponse(await fetchImpl(`${baseUrl}/lease/${encodeURIComponent(leaseId)}/renew`, { method: "POST" }), "Controller lease renew API", isToolVmSshLease);
+		return await readJsonResponse(await fetchController({
+			input: `${baseUrl}/lease/${encodeURIComponent(leaseId)}/renew`,
+			init: { method: "POST" },
+			operation: "lease-renew"
+		}), "Controller lease renew API", isToolVmSshLease);
 	};
 	return {
 		endActiveUse: async (leaseId, useId, request) => {
-			const response = await fetchImpl(`${baseUrl}/lease/${encodeURIComponent(leaseId)}/uses/${encodeURIComponent(useId)}`, {
-				body: JSON.stringify(request),
-				headers: { "content-type": "application/json" },
-				method: "DELETE"
+			const response = await fetchController({
+				input: `${baseUrl}/lease/${encodeURIComponent(leaseId)}/uses/${encodeURIComponent(useId)}`,
+				init: {
+					body: JSON.stringify(request),
+					headers: { "content-type": "application/json" },
+					method: "DELETE"
+				},
+				operation: "lease-use-end"
 			});
 			if (!response.ok) {
 				const errorBody = await readErrorBody(response, "Controller active-use end API");
@@ -105,19 +121,35 @@ function createLeaseClient(options) {
 					status: response.status
 				});
 			}
+			await drainControllerResponseBody(response);
 		},
-		heartbeatActiveUse: async (leaseId, useId) => {
-			return await readJsonResponse(await fetchImpl(`${baseUrl}/lease/${encodeURIComponent(leaseId)}/uses/${encodeURIComponent(useId)}/heartbeat`, { method: "POST" }), "Controller active-use heartbeat API", isHeartbeatActiveUseResponse);
+		heartbeatActiveUse: async (leaseId, useId, request) => {
+			return await readJsonResponse(await fetchController({
+				input: `${baseUrl}/lease/${encodeURIComponent(leaseId)}/uses/${encodeURIComponent(useId)}/heartbeat`,
+				init: {
+					body: JSON.stringify(request),
+					headers: { "content-type": "application/json" },
+					method: "POST"
+				},
+				operation: "lease-heartbeat"
+			}), "Controller active-use heartbeat API", isHeartbeatActiveUseResponse);
 		},
 		renewLease,
 		peekLease: async (leaseId) => {
-			return await readJsonResponse(await fetchImpl(`${baseUrl}/lease/${encodeURIComponent(leaseId)}/peek`), "Controller lease peek API", isToolVmLeasePeek);
+			return await readJsonResponse(await fetchController({
+				input: `${baseUrl}/lease/${encodeURIComponent(leaseId)}/peek`,
+				operation: "lease-peek"
+			}), "Controller lease peek API", isToolVmLeasePeek);
 		},
 		publishOpenClawRuntimeStatus: async (report) => {
-			const response = await fetchImpl(`${baseUrl}/zones/${encodeURIComponent(report.zoneId)}/openclaw-runtime-status`, {
-				body: JSON.stringify(report),
-				headers: { "content-type": "application/json" },
-				method: "POST"
+			const response = await fetchController({
+				input: `${baseUrl}/zones/${encodeURIComponent(report.zoneId)}/openclaw-runtime-status`,
+				init: {
+					body: JSON.stringify(report),
+					headers: { "content-type": "application/json" },
+					method: "POST"
+				},
+				operation: "openclaw-runtime-status"
 			});
 			if (!response.ok) {
 				const errorBody = await readErrorBody(response, "Controller OpenClaw runtime status API");
@@ -128,11 +160,16 @@ function createLeaseClient(options) {
 					status: response.status
 				});
 			}
+			await drainControllerResponseBody(response);
 		},
 		releaseLease: async (leaseId, releaseOptions = {}) => {
 			const releaseUrl = new URL(`${baseUrl}/lease/${encodeURIComponent(leaseId)}`);
 			if (releaseOptions.force === true) releaseUrl.searchParams.set("force", "true");
-			const response = await fetchImpl(releaseUrl.toString(), { method: "DELETE" });
+			const response = await fetchController({
+				input: releaseUrl.toString(),
+				init: { method: "DELETE" },
+				operation: "lease-release"
+			});
 			if (!response.ok) {
 				const errorBody = await readErrorBody(response, "Controller lease release API");
 				throw new ControllerLeaseRequestError({
@@ -142,28 +179,36 @@ function createLeaseClient(options) {
 					status: response.status
 				});
 			}
+			await drainControllerResponseBody(response);
 		},
 		requestLease: async (request) => {
-			return await readJsonResponse(await fetchImpl(`${baseUrl}/lease`, {
-				body: JSON.stringify({
-					agentId: request.agentId,
-					agentWorkspaceDir: request.agentWorkspaceDir,
-					profileId: request.profileId,
-					sandbox: request.sandbox,
-					scopeKey: request.scopeKey,
-					sessionKey: request.sessionKey,
-					workMountDir: request.workMountDir,
-					zoneId: request.zoneId
-				}),
-				headers: { "content-type": "application/json" },
-				method: "POST"
+			return await readJsonResponse(await fetchController({
+				input: `${baseUrl}/lease`,
+				init: {
+					body: JSON.stringify({
+						agentId: request.agentId,
+						agentWorkspaceDir: request.agentWorkspaceDir,
+						...request.idleTtlMs !== void 0 ? { idleTtlMs: request.idleTtlMs } : {},
+						profileId: request.profileId,
+						sessionKey: request.sessionKey,
+						workMountDir: request.workMountDir,
+						zoneId: request.zoneId
+					}),
+					headers: { "content-type": "application/json" },
+					method: "POST"
+				},
+				operation: "lease-create"
 			}), "Controller lease API", isToolVmSshLease);
 		},
 		startActiveUse: async (leaseId, request) => {
-			return await readJsonResponse(await fetchImpl(`${baseUrl}/lease/${encodeURIComponent(leaseId)}/uses`, {
-				body: JSON.stringify(request),
-				headers: { "content-type": "application/json" },
-				method: "POST"
+			return await readJsonResponse(await fetchController({
+				input: `${baseUrl}/lease/${encodeURIComponent(leaseId)}/uses`,
+				init: {
+					body: JSON.stringify(request),
+					headers: { "content-type": "application/json" },
+					method: "POST"
+				},
+				operation: "lease-use-start"
 			}), "Controller active-use start API", isStartActiveUseResponse);
 		}
 	};
@@ -190,7 +235,13 @@ const OPENCLAW_GONDOLIN_SANDBOX_REQUIREMENTS = [
 		key: "workspaceAccess"
 	}
 ];
-const OPENCLAW_GONDOLIN_LEASE_SCOPE_GUIDANCE = "Managed OpenClaw/Gondolin requires an explicit agentId. scopeKey is OpenClaw scope provenance and may include channel, session, thread, or subagent segments under that agent.";
+const OPENCLAW_GONDOLIN_LEASE_SCOPE_GUIDANCE = "Managed OpenClaw/Gondolin leases are agent-scoped. The plugin derives agentId from sessionKey and does not send OpenClaw scope keys to the controller.";
+var OpenClawAgentIdError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OpenClawAgentIdError";
+	}
+};
 function isOpenClawAgentId(value) {
 	return agentIdPattern.test(value.trim());
 }
@@ -208,11 +259,13 @@ function formatOpenClawGondolinRequirementHint(options) {
 }
 function normalizeOpenClawAgentId(value) {
 	const trimmed = (value ?? "").trim().toLowerCase();
-	return isOpenClawAgentId(trimmed) ? trimmed : OPENCLAW_DEFAULT_AGENT_ID;
+	if (trimmed === "") return OPENCLAW_DEFAULT_AGENT_ID;
+	if (!isOpenClawAgentId(trimmed)) throw new OpenClawAgentIdError(`Invalid OpenClaw agentId '${value}'.`);
+	return trimmed;
 }
 function resolveOpenClawAgentIdFromSessionKey(sessionKey) {
 	const parts = sessionKey.trim().split(":");
-	if (parts[0] !== "agent" || !parts[1]) return OPENCLAW_DEFAULT_AGENT_ID;
+	if (parts[0] !== "agent" || !parts[1] || !isOpenClawAgentId(parts[1])) throw new OpenClawAgentIdError(`OpenClaw sessionKey '${sessionKey}' must be agent-shaped and include a valid agentId.`);
 	return normalizeOpenClawAgentId(parts[1]);
 }
 function isOpenClawAgentSessionKey(sessionKey) {
@@ -231,21 +284,385 @@ function findOpenClawGondolinSandboxMismatch(sandbox) {
 	return OPENCLAW_GONDOLIN_SANDBOX_REQUIREMENTS.find((requirement) => sandbox[requirement.key] !== requirement.expectedValue);
 }
 //#endregion
+//#region src/sandbox-backend/openclaw-agent-workspace-source.ts
+var OpenClawAgentWorkspaceSourceError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OpenClawAgentWorkspaceSourceError";
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeAbsolutePosixPath(inputPath) {
+	return `/${inputPath.split("/").filter((segment) => segment !== "" && segment !== ".").join("/")}`;
+}
+function containsParentTraversal(inputPath) {
+	return inputPath.split(/\/+/u).includes("..");
+}
+function pathIsInsideOrEqual(inputPath, rootPath) {
+	return inputPath === rootPath || inputPath.startsWith(`${rootPath}/`);
+}
+function isRuntimePathLeak(inputPath, defaultWorkspaceDir) {
+	const normalized = normalizeAbsolutePosixPath(inputPath);
+	const normalizedDefaultWorkspace = defaultWorkspaceDir === void 0 ? void 0 : normalizeAbsolutePosixPath(resolveUserPathLikeOpenClaw(defaultWorkspaceDir));
+	const implicitWorkspaceFamilyRoot = normalizedDefaultWorkspace === void 0 ? void 0 : normalizedDefaultWorkspace.replace(/(?:-[^/]+)?$/u, "");
+	return normalized === TOOL_VM_WORKSPACE_GUEST_ROOT || normalized.startsWith(`${TOOL_VM_WORKSPACE_GUEST_ROOT}/`) || normalized === TOOL_VM_SCRATCH_GUEST_ROOT || normalized.startsWith(`${TOOL_VM_SCRATCH_GUEST_ROOT}/`) || normalized === OPENCLAW_STATE_SANDBOXES_VM_ROOT || normalized.startsWith(`${OPENCLAW_STATE_SANDBOXES_VM_ROOT}/`) || normalizedDefaultWorkspace !== void 0 && (pathIsInsideOrEqual(normalized, normalizedDefaultWorkspace) || normalized.startsWith(`${normalizedDefaultWorkspace}-`)) || implicitWorkspaceFamilyRoot !== void 0 && (pathIsInsideOrEqual(normalized, implicitWorkspaceFamilyRoot) || normalized.startsWith(`${implicitWorkspaceFamilyRoot}-`));
+}
+function resolveUserPathLikeOpenClaw(inputPath) {
+	const trimmedPath = inputPath.trim();
+	const homeDirectory = process.env.HOME?.trim();
+	if (trimmedPath === "~" && homeDirectory) return homeDirectory;
+	if (trimmedPath.startsWith("~/") && homeDirectory) return path.resolve(path.join(homeDirectory, trimmedPath.slice(2)));
+	return path.resolve(trimmedPath);
+}
+function assertCanonicalSourcePath(inputPath, context) {
+	const trimmedPath = inputPath.trim();
+	if (trimmedPath === "" || containsParentTraversal(trimmedPath)) throw new OpenClawAgentWorkspaceSourceError(`${context} must be a non-empty path without parent traversal.`);
+	if (!trimmedPath.startsWith("/") && !trimmedPath.startsWith("~")) throw new OpenClawAgentWorkspaceSourceError(`${context} must be an absolute or home-relative path.`);
+	const normalized = normalizeAbsolutePosixPath(resolveUserPathLikeOpenClaw(trimmedPath));
+	if (normalized === "/" || normalized === TOOL_VM_WORKSPACE_GUEST_ROOT || normalized.startsWith(`${TOOL_VM_WORKSPACE_GUEST_ROOT}/`) || normalized === TOOL_VM_SCRATCH_GUEST_ROOT || normalized.startsWith(`${TOOL_VM_SCRATCH_GUEST_ROOT}/`)) throw new OpenClawAgentWorkspaceSourceError(`${context} must resolve to an OpenClaw/Gondolin source path, not Tool VM guest path '${normalized}'.`);
+	if (normalized === OPENCLAW_STATE_SANDBOXES_VM_ROOT || normalized.startsWith(`${OPENCLAW_STATE_SANDBOXES_VM_ROOT}/`)) throw new OpenClawAgentWorkspaceSourceError(`${context} must resolve to a stable agent workspace path, not transient OpenClaw sandbox path '${normalized}'.`);
+	return normalized;
+}
+function assertLeaseBackedSourcePath(inputPath, context, defaultWorkspaceDir) {
+	const normalized = assertCanonicalSourcePath(inputPath, context);
+	if (isRuntimePathLeak(normalized, defaultWorkspaceDir)) throw new OpenClawAgentWorkspaceSourceError(`${context} must resolve to a controller lease-backed OpenClaw/Gondolin source path, not OpenClaw runtime fallback path '${normalized}'.`);
+	return normalized;
+}
+function readWorkspace(value) {
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+}
+function readAgentId(value) {
+	return normalizeOpenClawAgentId(typeof value === "string" ? value : void 0);
+}
+function agentEntries(config) {
+	return config?.agents?.list?.filter(isRecord) ?? [];
+}
+function findAgentEntry(config, agentId) {
+	return agentEntries(config).find((entry) => readAgentId(entry.id) === agentId);
+}
+function resolveDefaultAgentId(config) {
+	const entries = agentEntries(config);
+	return readAgentId((entries.find((entry) => entry.default === true) ?? entries[0])?.id);
+}
+function resolveOpenClawAgentWorkspaceSource(options) {
+	const agentId = normalizeOpenClawAgentId(options.agentId);
+	const agentWorkspace = readWorkspace(findAgentEntry(options.openClawConfig, agentId)?.workspace);
+	if (agentWorkspace !== void 0) return {
+		kind: "configured-agent-workspace",
+		sourceDir: assertLeaseBackedSourcePath(agentWorkspace, `agents.list workspace for '${agentId}'`, options.defaultWorkspaceDir)
+	};
+	const defaultsWorkspace = readWorkspace(options.openClawConfig?.agents?.defaults?.workspace);
+	if (defaultsWorkspace !== void 0) {
+		const defaultsRoot = assertLeaseBackedSourcePath(defaultsWorkspace, "agents.defaults.workspace", options.defaultWorkspaceDir);
+		const defaultAgentId = resolveDefaultAgentId(options.openClawConfig);
+		return {
+			kind: agentId === defaultAgentId ? "default-agent-workspace" : "default-workspace-child",
+			sourceDir: agentId === defaultAgentId ? defaultsRoot : path.join(defaultsRoot, agentId)
+		};
+	}
+	if (!isRuntimePathLeak(options.paramsAgentWorkspaceDir, options.defaultWorkspaceDir)) return {
+		kind: "sdk-agent-workspace",
+		sourceDir: assertCanonicalSourcePath(options.paramsAgentWorkspaceDir, "OpenClaw backend agentWorkspaceDir")
+	};
+	const stateRoot = options.stateDir === void 0 ? void 0 : assertCanonicalSourcePath(options.stateDir, "OpenClaw stateDir");
+	if (stateRoot === void 0) throw new OpenClawAgentWorkspaceSourceError(`OpenClaw provided agentWorkspaceDir '${options.paramsAgentWorkspaceDir}' for agent '${agentId}', which is a runtime path. Provide an OpenClaw stateDir provider or configure agents.list[].workspace.`);
+	if (agentId === resolveDefaultAgentId(options.openClawConfig)) throw new OpenClawAgentWorkspaceSourceError(`OpenClaw provided agentWorkspaceDir '${options.paramsAgentWorkspaceDir}' for default agent '${agentId}', but OpenClaw's implicit default workspace is not controller lease backed; configure agents.list[].workspace or agents.defaults.workspace for managed Gondolin agents.`);
+	return {
+		kind: "state-workspace-child",
+		sourceDir: path.join(stateRoot, `workspace-${agentId}`)
+	};
+}
+//#endregion
+//#region src/sandbox-backend/openclaw-tool-vm-path-mapping.ts
+var OpenClawToolVmPathIntentError = class extends Error {
+	details;
+	constructor(details) {
+		super(`${details.message} ${details.retryGuidance}`);
+		this.name = "OpenClawToolVmPathIntentError";
+		this.details = details;
+	}
+};
+function pathContainsParentTraversal(inputPath) {
+	return inputPath.split(/\/+/u).includes("..");
+}
+function normalizedAbsolutePath(inputPath) {
+	return `/${inputPath.split("/").filter((segment) => segment !== "" && segment !== ".").join("/")}`;
+}
+function invalidAgentWorkspaceRootError(agentWorkspaceDir) {
+	return {
+		allowedPathForms: [],
+		code: "invalid-runtime-root",
+		inputPath: agentWorkspaceDir,
+		mappingId: "openclaw-tool-vm",
+		message: `OpenClaw agentWorkspaceDir '${agentWorkspaceDir}' must be an absolute non-root path without parent traversal.`,
+		purpose: "executionCwd",
+		retryGuidance: "Retry with OpenClaw agentWorkspaceDir set to the resolved host RealFS workspace for the requested agent."
+	};
+}
+function validateAgentWorkspaceDir(agentWorkspaceDir) {
+	if (agentWorkspaceDir.trim() === "" || !agentWorkspaceDir.startsWith("/") || normalizedAbsolutePath(agentWorkspaceDir) === "/" || pathContainsParentTraversal(agentWorkspaceDir)) return invalidAgentWorkspaceRootError(agentWorkspaceDir);
+}
+function createOpenClawToolVmPathMapping(options) {
+	return {
+		id: "openclaw-tool-vm",
+		roots: [
+			{
+				id: "agent-workspace",
+				backing: {
+					kind: "host-realfs",
+					durability: "durable",
+					backup: "included"
+				},
+				capabilities: {
+					executionCwd: true,
+					leaseMount: true
+				},
+				locations: {
+					"openclaw-gateway": options.agentWorkspaceDir,
+					"tool-vm-guest": TOOL_VM_WORKSPACE_GUEST_ROOT
+				},
+				rootPathAllowed: true,
+				guidanceLabel: "agent workspace"
+			},
+			{
+				id: "tool-vm-scratch",
+				backing: {
+					kind: "guest-rootfs-cow",
+					durability: "vm-lifetime"
+				},
+				capabilities: {
+					executionCwd: true,
+					leaseMount: false
+				},
+				locations: { "tool-vm-guest": TOOL_VM_SCRATCH_GUEST_ROOT },
+				rootPathAllowed: true,
+				guidanceLabel: "Tool VM scratch"
+			},
+			{
+				id: "openclaw-sandboxes",
+				backing: {
+					kind: "host-realfs",
+					durability: "durable",
+					backup: "included"
+				},
+				capabilities: {
+					executionCwd: true,
+					leaseMount: true
+				},
+				locations: { "openclaw-gateway": OPENCLAW_STATE_SANDBOXES_VM_ROOT },
+				rootPathAllowed: false,
+				guidanceLabel: "OpenClaw sandbox work directory"
+			}
+		]
+	};
+}
+function resolveOpenClawSandboxPathIntent(translation) {
+	const [sandboxChild, ...guestCwdSegments] = translation.relativePath.split("/");
+	const leaseWorkMountDir = sandboxChild === void 0 || sandboxChild === "" ? translation.outputPath : `${OPENCLAW_STATE_SANDBOXES_VM_ROOT}/${sandboxChild}`;
+	return {
+		effectiveGuestCwd: guestCwdSegments.length === 0 ? TOOL_VM_WORKSPACE_GUEST_ROOT : `${TOOL_VM_WORKSPACE_GUEST_ROOT}/${guestCwdSegments.join("/")}`,
+		leaseWorkMountDir
+	};
+}
+function kindForTranslation(translation) {
+	const isRoot = translation.relativePath === "";
+	if (translation.rootId === "tool-vm-scratch") return isRoot ? "scratch-root" : "scratch-subpath";
+	if (translation.rootId === "openclaw-sandboxes") return "openclaw-sandbox-path";
+	if (translation.inputNamespace === "openclaw-gateway") return isRoot ? "host-workspace-root" : "host-workspace-subpath";
+	return isRoot ? "workspace-root" : "workspace-subpath";
+}
+function leaseRootForTranslation(translation) {
+	return translation.relativePath === "" ? translation.outputPath : translation.outputPath.slice(0, -(translation.relativePath.length + 1));
+}
+function resolveOpenClawToolVmPathIntent(options) {
+	const agentWorkspaceDirError = validateAgentWorkspaceDir(options.agentWorkspaceDir);
+	if (agentWorkspaceDirError !== void 0) return {
+		error: agentWorkspaceDirError,
+		ok: false
+	};
+	const mappings = [createOpenClawToolVmPathMapping({ agentWorkspaceDir: options.agentWorkspaceDir }), ...(options.equivalentAgentWorkspaceDirs ?? []).map((equivalentAgentWorkspaceDir) => createOpenClawToolVmPathMapping({ agentWorkspaceDir: equivalentAgentWorkspaceDir }))];
+	const invalidEquivalentRoot = (options.equivalentAgentWorkspaceDirs ?? []).map((equivalentAgentWorkspaceDir) => validateAgentWorkspaceDir(equivalentAgentWorkspaceDir)).find((error) => error !== void 0);
+	if (invalidEquivalentRoot !== void 0) return {
+		error: invalidEquivalentRoot,
+		ok: false
+	};
+	const mapping = createOpenClawToolVmPathMapping({ agentWorkspaceDir: options.agentWorkspaceDir });
+	const sandboxTranslation = translateRuntimePath({
+		inputPath: options.inputPath,
+		mapping,
+		purpose: "executionCwd",
+		sourceNamespace: "openclaw-gateway",
+		targetNamespace: "openclaw-gateway"
+	});
+	if (sandboxTranslation.ok && sandboxTranslation.value.rootId === "openclaw-sandboxes") {
+		const sandboxPathIntent = resolveOpenClawSandboxPathIntent(sandboxTranslation.value);
+		return {
+			ok: true,
+			value: {
+				effectiveGuestCwd: sandboxPathIntent.effectiveGuestCwd,
+				hostEquivalentPath: sandboxTranslation.value.outputPath,
+				kind: kindForTranslation(sandboxTranslation.value),
+				leaseWorkMountDir: sandboxPathIntent.leaseWorkMountDir
+			}
+		};
+	}
+	const translationResults = mappings.map((candidateMapping) => translateRuntimePath({
+		inputPath: options.inputPath,
+		mapping: candidateMapping,
+		purpose: "executionCwd",
+		targetNamespace: "tool-vm-guest"
+	}));
+	const translation = translationResults.find((candidateTranslation) => candidateTranslation.ok);
+	if (translation === void 0) {
+		const primaryTranslation = translationResults[0];
+		if (primaryTranslation === void 0 || primaryTranslation.ok) return {
+			error: invalidAgentWorkspaceRootError(options.agentWorkspaceDir),
+			ok: false
+		};
+		return primaryTranslation;
+	}
+	const hostEquivalentTranslation = translateRuntimePath({
+		inputPath: options.inputPath,
+		mapping,
+		purpose: "executionCwd",
+		targetNamespace: "openclaw-gateway"
+	});
+	return {
+		ok: true,
+		value: {
+			effectiveGuestCwd: translation.value.outputPath,
+			...hostEquivalentTranslation.ok ? { hostEquivalentPath: hostEquivalentTranslation.value.outputPath } : {},
+			kind: kindForTranslation(translation.value),
+			leaseWorkMountDir: hostEquivalentTranslation.ok && hostEquivalentTranslation.value.rootId !== "tool-vm-scratch" ? leaseRootForTranslation(hostEquivalentTranslation.value) : options.agentWorkspaceDir
+		}
+	};
+}
+function assertOpenClawToolVmPathIntent(options) {
+	const result = resolveOpenClawToolVmPathIntent(options);
+	if (!result.ok) throw new OpenClawToolVmPathIntentError(result.error);
+	return result.value;
+}
+//#endregion
 //#region src/sandbox-backend/sandbox-shell-script.ts
 function buildShellScriptWithArgs(script, args) {
 	if (!args || args.length === 0) return script;
 	return `set -- ${args.map((arg) => `'${arg.replace(/'/g, "'\\''")}'`).join(" ")}; ${script}`;
 }
 //#endregion
+//#region src/sandbox-backend/tool-vm-ssh-operation-guard.ts
+var ToolVmSshOperationStaleError = class extends Error {
+	cause;
+	reason;
+	constructor(options) {
+		super(options.message);
+		this.cause = options.cause;
+		this.reason = options.reason;
+	}
+};
+function formatUnknownError$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function defaultWriteLog$1(message) {
+	process.stderr.write(`[tool-vm-ssh-operation-guard] ${message}\n`);
+}
+async function publishHealthEvent(options) {
+	if (!options.guardOptions.healthEvent) return;
+	const event = {
+		agentId: options.guardOptions.healthEvent.agentId,
+		elapsedMs: options.elapsedMs,
+		...options.errorCode === void 0 ? {} : { errorCode: options.errorCode },
+		kind: "tool-vm-ssh",
+		leaseId: options.guardOptions.healthEvent.leaseId,
+		observedAtMs: options.observedAtMs,
+		operation: options.guardOptions.healthEvent.operation,
+		result: options.result,
+		zoneId: options.guardOptions.healthEvent.zoneId
+	};
+	try {
+		await options.guardOptions.healthEvent.publish(event);
+	} catch (error) {
+		(options.guardOptions.writeLog ?? defaultWriteLog$1)(`tool-vm-ssh health publish failed operation=${options.guardOptions.healthEvent.operation} elapsedMs=${String(options.elapsedMs)} error=${formatUnknownError$1(error)}`);
+	}
+}
+async function runToolVmSshOperationWithGuard(options) {
+	const now = options.now ?? Date.now;
+	const setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
+	const clearTimeoutImpl = options.clearTimeoutImpl ?? clearTimeout;
+	const abortController = new AbortController();
+	const startedAtMs = now();
+	let timeoutHandle;
+	options.report({
+		observedAtMs: now(),
+		phase: "running"
+	});
+	const timeoutPromise = new Promise((_resolve, reject) => {
+		timeoutHandle = setTimeoutImpl(() => {
+			abortController.abort();
+			reject(new ToolVmSshOperationStaleError({
+				cause: void 0,
+				message: `${options.operationName} exceeded ${String(options.timeoutMs)}ms.`,
+				reason: "ssh-command-timed-out"
+			}));
+		}, options.timeoutMs);
+	});
+	try {
+		const result = await Promise.race([options.operation(abortController.signal), timeoutPromise]);
+		options.report({
+			observedAtMs: now(),
+			phase: "completed",
+			ssh: { probeSucceeded: true }
+		});
+		const observedAtMs = now();
+		publishHealthEvent({
+			elapsedMs: observedAtMs - startedAtMs,
+			guardOptions: options,
+			observedAtMs,
+			result: "ok"
+		});
+		return result;
+	} catch (error) {
+		const staleError = error instanceof ToolVmSshOperationStaleError ? error : new ToolVmSshOperationStaleError({
+			cause: error,
+			message: formatUnknownError$1(error),
+			reason: "ssh-command-failed"
+		});
+		options.report({
+			observedAtMs: now(),
+			phase: "failed",
+			ssh: { failure: {
+				kind: staleError.reason,
+				message: staleError.message
+			} }
+		});
+		const observedAtMs = now();
+		publishHealthEvent({
+			elapsedMs: observedAtMs - startedAtMs,
+			errorCode: staleError.reason,
+			guardOptions: options,
+			observedAtMs,
+			result: "failed"
+		});
+		throw staleError;
+	} finally {
+		if (timeoutHandle !== void 0) clearTimeoutImpl(timeoutHandle);
+	}
+}
+//#endregion
 //#region src/sandbox-backend/sandbox-backend-handle-factory.ts
 function agentLeaseCacheKey(params) {
-	return [
-		params.zoneId,
-		params.agentId,
-		params.profileId,
-		params.agentWorkspaceDir,
-		params.workspaceDir
-	].join("\0");
+	return [params.zoneId, params.agentId].join("\0");
+}
+function findCachedLeaseCompatibilityMismatch(params) {
+	if (params.cachedEntry.agentWorkspaceDir !== params.requestedEntry.agentWorkspaceDir) return "agentWorkspaceDir";
+	if (params.cachedEntry.leaseWorkMountDir !== params.requestedEntry.leaseWorkMountDir) return "leaseWorkMountDir";
+	if (params.cachedEntry.profileId !== params.requestedEntry.profileId) return "profileId";
+}
+function assertCachedLeaseCompatible(params) {
+	const mismatch = findCachedLeaseCompatibilityMismatch(params);
+	if (mismatch === void 0) return;
+	throw new Error(`Cannot reuse cached Tool VM lease for zone '${params.zoneId}' agent '${params.agentId}': ${mismatch} changed.`);
 }
 function formatControllerLeaseRequestError(error) {
 	const responseBody = error.responseBody === void 0 ? error.bodyText : JSON.stringify(error.responseBody);
@@ -259,7 +676,10 @@ function writeSandboxBackendLog(message) {
 	process.stderr.write(`[openclaw-agent-vm-plugin] ${message}\n`);
 }
 function shouldRefreshCachedLease(error) {
-	return error instanceof ControllerLeaseRequestError && error.status === 404;
+	return isRefreshableLeaseError(error);
+}
+function isRefreshableLeaseError(error) {
+	return error instanceof ControllerLeaseRequestError && (error.status === 404 || error.status === 410);
 }
 function isCleanupNotFound(error) {
 	return error instanceof ControllerLeaseRequestError && error.status === 404;
@@ -273,111 +693,276 @@ function isActiveUseFinalizeToken(value) {
 function activeUseOutcomeForFinalizeParams(finalizeParams) {
 	return finalizeParams.timedOut ? "timed-out" : finalizeParams.status === "completed" ? "completed" : "failed";
 }
+async function publishFinalizeToolVmSshHealthEvent(options) {
+	const event = {
+		agentId: options.agentId,
+		elapsedMs: 0,
+		...options.timedOut ? { errorCode: "ssh-command-timed-out" } : {},
+		kind: "tool-vm-ssh",
+		leaseId: options.leaseId,
+		observedAtMs: Date.now(),
+		operation: "finalize",
+		result: options.timedOut ? "failed" : "ok",
+		zoneId: options.zoneId
+	};
+	try {
+		await options.publishHealthEvent(event);
+	} catch (error) {
+		writeSandboxBackendLog(`tool-vm-ssh finalize health publish failed for zone '${options.zoneId}' lease '${options.leaseId}': ${formatUnknownError(error)}`);
+	}
+}
+function mergedAbortSignal(firstSignal, secondSignal) {
+	if (firstSignal === void 0) return secondSignal;
+	return AbortSignal.any([firstSignal, secondSignal]);
+}
+function mergedAbortSignals(signals) {
+	const presentSignals = signals.filter((signal) => signal !== void 0);
+	if (presentSignals.length === 0) return;
+	if (presentSignals.length === 1) return presentSignals[0];
+	return AbortSignal.any(presentSignals);
+}
 function resolveLeaseRequestAgentId(sessionKey) {
 	return resolveOpenClawAgentIdFromSessionKey(sessionKey);
 }
+function defaultOpenClawStateDir() {
+	const explicitStateDir = process.env.OPENCLAW_STATE_DIR?.trim();
+	if (explicitStateDir) return path.resolve(explicitStateDir);
+	const homeDirectory = process.env.HOME?.trim();
+	return homeDirectory ? path.join(homeDirectory, ".openclaw", "state") : void 0;
+}
+function defaultOpenClawWorkspaceDir() {
+	const homeDirectory = process.env.HOME?.trim();
+	if (!homeDirectory) return;
+	const profile = process.env.OPENCLAW_PROFILE?.trim().toLowerCase();
+	return profile && profile !== "default" ? path.join(homeDirectory, ".openclaw", `workspace-${profile}`) : path.join(homeDirectory, ".openclaw", "workspace");
+}
 function assertPluginLeaseContract(params) {
 	const mismatch = findOpenClawGondolinSandboxMismatch(params.cfg);
 	if (mismatch) throw new Error(`OpenClaw Gondolin sandbox requires ${mismatch.key}=${mismatch.expectedValue}; received ${String(params.cfg[mismatch.key])}.`);
 }
 function createGondolinSandboxBackendFactory(options, dependencies) {
-	const scopeCache = /* @__PURE__ */ new Map();
+	const agentLeaseCache = /* @__PURE__ */ new Map();
+	const inFlightLeaseRequests = /* @__PURE__ */ new Map();
 	return async (params) => {
 		const profileId = options.profileId ?? "standard";
 		const agentId = resolveLeaseRequestAgentId(params.sessionKey);
-		assertPluginLeaseContract({
+		assertPluginLeaseContract({ cfg: params.cfg });
+		const defaultWorkspaceDir = options.openClawDefaultWorkspaceDirProvider?.() ?? defaultOpenClawWorkspaceDir();
+		const equivalentAgentWorkspaceDirs = defaultWorkspaceDir === void 0 ? [] : [defaultWorkspaceDir];
+		const workspaceSource = resolveOpenClawAgentWorkspaceSource({
 			agentId,
-			cfg: params.cfg,
-			scopeKey: params.scopeKey
+			defaultWorkspaceDir,
+			openClawConfig: options.openClawRuntimeConfigProvider?.(),
+			paramsAgentWorkspaceDir: params.agentWorkspaceDir,
+			stateDir: options.openClawStateDirProvider?.() ?? defaultOpenClawStateDir()
+		});
+		const pathIntent = assertOpenClawToolVmPathIntent({
+			agentWorkspaceDir: workspaceSource.sourceDir,
+			equivalentAgentWorkspaceDirs,
+			inputPath: params.workspaceDir
 		});
 		const cacheKey = agentLeaseCacheKey({
 			agentId,
-			agentWorkspaceDir: params.agentWorkspaceDir,
-			profileId,
-			workspaceDir: params.workspaceDir,
 			zoneId: options.zoneId
 		});
+		const requestedCacheEntry = {
+			agentWorkspaceDir: workspaceSource.sourceDir,
+			leaseWorkMountDir: pathIntent.leaseWorkMountDir,
+			profileId
+		};
 		const leaseClient = dependencies.createLeaseClient?.({ controllerUrl: options.controllerUrl }) ?? createLeaseClient({ controllerUrl: options.controllerUrl });
-		const cachedEntry = scopeCache.get(cacheKey);
-		if (cachedEntry) try {
-			await leaseClient.renewLease(cachedEntry.lease.leaseId);
-			return cachedEntry.handle;
-		} catch (error) {
-			writeSandboxBackendLog(`lease renew failed for zone '${options.zoneId}' scope '${params.scopeKey}' lease '${cachedEntry.lease.leaseId}': ${formatUnknownError(error)}`);
-			if (!shouldRefreshCachedLease(error)) throw error;
-			scopeCache.delete(cacheKey);
+		const publishHealthEvent = async (event) => {
+			const response = await fetchControllerWithPolicy({
+				input: `${options.controllerUrl.replace(/\/+$/u, "")}/zones/${encodeURIComponent(options.zoneId)}/health-events`,
+				init: {
+					body: JSON.stringify(event),
+					headers: { "content-type": "application/json" },
+					method: "POST"
+				},
+				operation: "health-event-publish"
+			});
+			if (!response.ok) {
+				await response.text().catch(() => void 0);
+				throw new Error(`health event publish returned HTTP ${String(response.status)}`);
+			}
+			await response.text().catch(() => void 0);
+		};
+		const markLeaseStale = async (lease, reason, error) => {
+			agentLeaseCache.delete(cacheKey);
+			writeSandboxBackendLog(`lease marked stale for zone '${options.zoneId}' agent '${agentId}' lease '${lease.leaseId}' reason '${reason}': ${formatUnknownError(error)}`);
+			await leaseClient.releaseLease(lease.leaseId, { force: true }).catch((releaseError) => {
+				writeSandboxBackendLog(`best-effort stale lease release failed for zone '${options.zoneId}' agent '${agentId}' lease '${lease.leaseId}': ${formatUnknownError(releaseError)}`);
+			});
+		};
+		const cachedEntry = agentLeaseCache.get(cacheKey);
+		let lease;
+		if (cachedEntry) {
+			assertCachedLeaseCompatible({
+				agentId,
+				cachedEntry,
+				requestedEntry: requestedCacheEntry,
+				zoneId: options.zoneId
+			});
+			try {
+				const renewedLease = await leaseClient.renewLease(cachedEntry.lease.leaseId);
+				await runToolVmSshOperationWithGuard({
+					healthEvent: {
+						agentId,
+						leaseId: renewedLease.leaseId,
+						operation: "probe",
+						publish: publishHealthEvent,
+						zoneId: options.zoneId
+					},
+					operation: async (signal) => await dependencies.runRemoteShellScript({
+						allowFailure: false,
+						script: "true",
+						signal,
+						ssh: renewedLease.ssh
+					}),
+					operationName: "cached-ssh-probe",
+					report: () => {},
+					timeoutMs: 3e4
+				});
+				lease = renewedLease;
+				agentLeaseCache.set(cacheKey, {
+					...requestedCacheEntry,
+					lease
+				});
+			} catch (error) {
+				writeSandboxBackendLog(`lease renew failed for zone '${options.zoneId}' agent '${agentId}' lease '${cachedEntry.lease.leaseId}': ${formatUnknownError(error)}`);
+				if (error instanceof ToolVmSshOperationStaleError) await markLeaseStale(cachedEntry.lease, error.reason, error);
+				else if (shouldRefreshCachedLease(error)) agentLeaseCache.delete(cacheKey);
+				else throw error;
+			}
 		}
-		const runtimeStatus = options.openClawRuntimeStatusProvider?.();
-		if (runtimeStatus && leaseClient.publishOpenClawRuntimeStatus) await leaseClient.publishOpenClawRuntimeStatus(runtimeStatus);
-		const leaseResponse = await leaseClient.requestLease({
-			agentId,
-			agentWorkspaceDir: params.agentWorkspaceDir,
-			profileId,
-			sandbox: snapshotOpenClawGondolinSandboxConfig(params.cfg),
-			scopeKey: params.scopeKey,
-			sessionKey: params.sessionKey,
-			workMountDir: params.workspaceDir,
-			zoneId: options.zoneId
-		});
-		if (!isToolVmSshLease(leaseResponse)) throw new TypeError("Controller lease API returned an unexpected response.");
-		const lease = leaseResponse;
-		const handle = createSandboxBackendHandle({
+		if (lease === void 0) {
+			const inFlightLeaseRequest = inFlightLeaseRequests.get(cacheKey);
+			if (inFlightLeaseRequest !== void 0) {
+				const inFlightEntry = await inFlightLeaseRequest;
+				assertCachedLeaseCompatible({
+					agentId,
+					cachedEntry: inFlightEntry,
+					requestedEntry: requestedCacheEntry,
+					zoneId: options.zoneId
+				});
+				lease = inFlightEntry.lease;
+			} else {
+				const leaseRequestPromise = (async () => {
+					const runtimeStatus = options.openClawRuntimeStatusProvider?.();
+					if (runtimeStatus && leaseClient.publishOpenClawRuntimeStatus) await leaseClient.publishOpenClawRuntimeStatus(runtimeStatus);
+					const leaseResponse = await leaseClient.requestLease({
+						agentId,
+						agentWorkspaceDir: workspaceSource.sourceDir,
+						profileId,
+						sessionKey: params.sessionKey,
+						workMountDir: pathIntent.leaseWorkMountDir,
+						zoneId: options.zoneId
+					});
+					if (!isToolVmSshLease(leaseResponse)) throw new TypeError("Controller lease API returned an unexpected response.");
+					return {
+						...requestedCacheEntry,
+						lease: leaseResponse
+					};
+				})();
+				inFlightLeaseRequests.set(cacheKey, leaseRequestPromise);
+				try {
+					const leaseEntry = await leaseRequestPromise;
+					agentLeaseCache.set(cacheKey, leaseEntry);
+					lease = leaseEntry.lease;
+				} finally {
+					if (inFlightLeaseRequests.get(cacheKey) === leaseRequestPromise) inFlightLeaseRequests.delete(cacheKey);
+				}
+			}
+		}
+		return createSandboxBackendHandle({
 			cfg: params.cfg,
 			controllerUrl: options.controllerUrl,
 			createFsBridgeBuilder: dependencies.createFsBridgeBuilder,
+			effectiveGuestCwd: pathIntent.effectiveGuestCwd,
 			lease,
 			leaseClient,
+			markCachedLeaseStale: async (reason, error) => {
+				await markLeaseStale(lease, reason, error);
+			},
+			publishHealthEvent,
 			runRemoteShellScript: dependencies.runRemoteShellScript,
 			buildExecSpec: dependencies.buildExecSpec,
-			scopeKey: params.scopeKey,
 			sessionKey: params.sessionKey,
 			zoneId: options.zoneId
 		});
-		scopeCache.set(cacheKey, {
-			handle,
-			lease
-		});
-		return handle;
 	};
 }
 function createSandboxBackendHandle(options) {
-	const createActiveUseHandle = async (correlation) => await createToolVmActiveUseHandle({
-		correlation,
-		endActiveUse: async (useId, request) => {
-			await options.leaseClient.endActiveUse(options.lease.leaseId, useId, request);
-		},
-		heartbeatActiveUse: async (useId) => await options.leaseClient.heartbeatActiveUse(options.lease.leaseId, useId),
-		isEndErrorTolerable: isCleanupNotFound,
-		logEndFailure: (error) => {
-			writeSandboxBackendLog(`active-use cleanup ignored for zone '${options.zoneId}' lease '${options.lease.leaseId}': ${formatUnknownError(error)}`);
-		},
-		logHeartbeatFailure: (error) => {
-			writeSandboxBackendLog(`active-use heartbeat failed for zone '${options.zoneId}' lease '${options.lease.leaseId}': ${formatUnknownError(error)}`);
-		},
-		startActiveUse: async (request) => await options.leaseClient.startActiveUse(options.lease.leaseId, request)
-	});
+	const createActiveUseHandle = async (correlation) => {
+		try {
+			return await createToolVmActiveUseHandle({
+				correlation,
+				endActiveUse: async (useId, request) => {
+					await options.leaseClient.endActiveUse(options.lease.leaseId, useId, request);
+				},
+				heartbeatActiveUse: async (useId, request) => await options.leaseClient.heartbeatActiveUse(options.lease.leaseId, useId, request),
+				isEndErrorTolerable: isCleanupNotFound,
+				isHeartbeatErrorRefreshable: isRefreshableLeaseError,
+				logEndFailure: (error) => {
+					writeSandboxBackendLog(`active-use cleanup ignored for zone '${options.zoneId}' lease '${options.lease.leaseId}': ${formatUnknownError(error)}`);
+				},
+				logHeartbeatFailure: (error) => {
+					writeSandboxBackendLog(`active-use heartbeat failed for zone '${options.zoneId}' lease '${options.lease.leaseId}': ${formatUnknownError(error)}`);
+				},
+				onRefreshableHeartbeatFailure: async (error) => {
+					await options.markCachedLeaseStale("active-use-refreshable-failure", error);
+				},
+				startActiveUse: async (request) => await options.leaseClient.startActiveUse(options.lease.leaseId, request)
+			});
+		} catch (error) {
+			if (isRefreshableLeaseError(error)) await options.markCachedLeaseStale("active-use-refreshable-failure", error);
+			throw error;
+		}
+	};
 	const runWithActiveUse = async (correlation, fn) => {
 		const activeUseHandle = await createActiveUseHandle(correlation);
 		try {
-			const result = await fn();
+			const result = await fn(activeUseHandle);
 			await activeUseHandle.dispose("completed");
 			return result;
 		} catch (error) {
-			await activeUseHandle.dispose("failed").catch((cleanupError) => {
+			await activeUseHandle.dispose(error instanceof ToolVmSshOperationStaleError && error.reason === "ssh-command-timed-out" ? "timed-out" : "failed").catch((cleanupError) => {
 				writeSandboxBackendLog(`failed to end active use after operation failure for zone '${options.zoneId}' lease '${options.lease.leaseId}': ${formatUnknownError(cleanupError)}`);
 			});
+			if (error instanceof ToolVmSshOperationStaleError) await options.markCachedLeaseStale(error.reason, error);
 			throw error;
 		}
 	};
 	const boundRunRemoteShellScript = async (shellParams) => await runWithActiveUse({
 		sessionKey: options.sessionKey,
 		toolName: "fs-bridge"
-	}, async () => await options.runRemoteShellScript({
-		...shellParams.allowFailure !== void 0 ? { allowFailure: shellParams.allowFailure } : {},
-		script: buildShellScriptWithArgs(shellParams.script, shellParams.args),
-		...shellParams.signal !== void 0 ? { signal: shellParams.signal } : {},
-		ssh: options.lease.ssh,
-		...shellParams.stdin !== void 0 ? { stdin: shellParams.stdin } : {}
+	}, async (activeUseHandle) => await runToolVmSshOperationWithGuard({
+		healthEvent: {
+			agentId: options.lease.agentId,
+			leaseId: options.lease.leaseId,
+			operation: "file-bridge",
+			publish: options.publishHealthEvent,
+			zoneId: options.zoneId
+		},
+		operation: async (signal) => {
+			const operationSignal = mergedAbortSignals([
+				shellParams.signal,
+				activeUseHandle.signal,
+				signal
+			]);
+			return await options.runRemoteShellScript({
+				...shellParams.allowFailure !== void 0 ? { allowFailure: shellParams.allowFailure } : {},
+				script: buildShellScriptWithArgs(shellParams.script, shellParams.args),
+				...operationSignal === void 0 ? {} : { signal: operationSignal },
+				ssh: options.lease.ssh,
+				...shellParams.stdin !== void 0 ? { stdin: shellParams.stdin } : {}
+			});
+		},
+		operationName: "fs-bridge",
+		report: (report) => {
+			activeUseHandle.report(report);
+		},
+		timeoutMs: 3e4
 	}));
 	const disposeInnerFinalizeToken = async (token) => {
 		if (isDisposableFinalizeToken(token)) await token.dispose();
@@ -400,7 +985,7 @@ function createSandboxBackendHandle(options) {
 	};
 	const createFsBridge = options.createFsBridgeBuilder?.({
 		remoteAgentWorkspaceDir: options.lease.workdir,
-		remoteWorkspaceDir: options.lease.workdir,
+		remoteWorkspaceDir: options.effectiveGuestCwd,
 		runRemoteShellScript: boundRunRemoteShellScript
 	});
 	return {
@@ -411,7 +996,7 @@ function createSandboxBackendHandle(options) {
 		id: "gondolin",
 		runtimeId: options.lease.leaseId,
 		runtimeLabel: options.lease.leaseId,
-		workdir: options.lease.workdir,
+		workdir: options.effectiveGuestCwd,
 		buildExecSpec: async (execParams) => {
 			const activeUseHandle = await createActiveUseHandle({
 				sessionKey: options.sessionKey,
@@ -423,7 +1008,7 @@ function createSandboxBackendHandle(options) {
 					env: execParams.env,
 					ssh: options.lease.ssh,
 					usePty: execParams.usePty,
-					workdir: execParams.workdir ?? options.lease.workdir
+					workdir: execParams.workdir ?? options.effectiveGuestCwd
 				});
 				return {
 					...execSpec,
@@ -441,7 +1026,23 @@ function createSandboxBackendHandle(options) {
 		},
 		finalizeExec: async (finalizeParams) => {
 			if (isActiveUseFinalizeToken(finalizeParams.token)) {
+				if (finalizeParams.timedOut) finalizeParams.token.activeUseHandle.report({
+					observedAtMs: Date.now(),
+					phase: "failed",
+					ssh: { failure: {
+						kind: "ssh-command-timed-out",
+						message: "exec command timed out."
+					} }
+				});
 				await endActiveUseFinalizeToken(finalizeParams.token, activeUseOutcomeForFinalizeParams(finalizeParams));
+				publishFinalizeToolVmSshHealthEvent({
+					agentId: options.lease.agentId,
+					leaseId: options.lease.leaseId,
+					publishHealthEvent: options.publishHealthEvent,
+					timedOut: finalizeParams.timedOut,
+					zoneId: options.zoneId
+				});
+				if (finalizeParams.timedOut) await options.markCachedLeaseStale("ssh-command-timed-out", void 0);
 				return;
 			}
 			await disposeInnerFinalizeToken(finalizeParams.token);
@@ -449,9 +1050,24 @@ function createSandboxBackendHandle(options) {
 		runShellCommand: async (commandParams) => await runWithActiveUse({
 			sessionKey: options.sessionKey,
 			toolName: "runShellCommand"
-		}, async () => await options.runRemoteShellScript({
-			script: commandParams.script,
-			ssh: options.lease.ssh
+		}, async (activeUseHandle) => await runToolVmSshOperationWithGuard({
+			healthEvent: {
+				agentId: options.lease.agentId,
+				leaseId: options.lease.leaseId,
+				operation: "command",
+				publish: options.publishHealthEvent,
+				zoneId: options.zoneId
+			},
+			operation: async (signal) => await options.runRemoteShellScript({
+				script: commandParams.script,
+				signal: mergedAbortSignal(activeUseHandle.signal, signal),
+				ssh: options.lease.ssh
+			}),
+			operationName: "runShellCommand",
+			report: (report) => {
+				activeUseHandle.report(report);
+			},
+			timeoutMs: 3e4
 		}))
 	};
 }
@@ -481,10 +1097,20 @@ function createGondolinSandboxBackendManager(options, dependencies) {
 }
 //#endregion
 //#region src/gondolin-plugin-config.ts
+function isObjectRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function resolveGondolinPluginConfig(config) {
 	if (typeof config.controllerUrl !== "string" || typeof config.zoneId !== "string") throw new Error("Gondolin plugin config requires controllerUrl and zoneId.");
+	const rawGatewayControlLinkMonitor = config.gatewayControlLinkMonitor;
+	const gatewayControlLinkMonitor = isObjectRecord$1(rawGatewayControlLinkMonitor) ? {
+		baseIntervalMs: typeof rawGatewayControlLinkMonitor.baseIntervalMs === "number" ? rawGatewayControlLinkMonitor.baseIntervalMs : 1e4,
+		enabled: typeof rawGatewayControlLinkMonitor.enabled === "boolean" ? rawGatewayControlLinkMonitor.enabled : true,
+		maxIntervalMs: typeof rawGatewayControlLinkMonitor.maxIntervalMs === "number" ? rawGatewayControlLinkMonitor.maxIntervalMs : 12e4
+	} : void 0;
 	return {
 		controllerUrl: config.controllerUrl,
+		...gatewayControlLinkMonitor ? { gatewayControlLinkMonitor } : {},
 		...typeof config.profileId === "string" ? { profileId: config.profileId } : {},
 		...typeof config.zoneGitToken === "string" ? { zoneGitToken: config.zoneGitToken } : {},
 		...typeof config.zoneGitTokenEnv === "string" ? { zoneGitTokenEnv: config.zoneGitTokenEnv } : {},
@@ -492,6 +1118,119 @@ function resolveGondolinPluginConfig(config) {
 	};
 }
 //#endregion
+//#region src/gateway-control-link-monitor.ts
+function defaultWriteLog(message) {
+	process.stderr.write(`[gateway-control-link-monitor] ${message}\n`);
+}
+function joinUrl(baseUrl, path) {
+	return `${baseUrl.replace(/\/+$/, "")}${path}`;
+}
+function nextIntervalMs(options) {
+	const multiplier = 2 ** Math.min(options.consecutiveFailureCount, 8);
+	return Math.min(options.maxIntervalMs, options.baseIntervalMs * multiplier);
+}
+function createGatewayControlLinkMonitor(options) {
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
+	const clearTimeoutImpl = options.clearTimeoutImpl ?? clearTimeout;
+	const writeLog = options.writeLog ?? defaultWriteLog;
+	let consecutiveFailureCount = 0;
+	let stopped = true;
+	let timer;
+	const publish = async (event) => {
+		const response = await fetchControllerWithPolicy({
+			fetchImpl,
+			input: joinUrl(options.controllerUrl, `/zones/${encodeURIComponent(options.zoneId)}/health-events`),
+			init: {
+				body: JSON.stringify(event),
+				headers: { "content-type": "application/json" },
+				method: "POST"
+			},
+			operation: "health-event-publish"
+		});
+		if (!response.ok) {
+			await response.text().catch(() => void 0);
+			throw new Error(`health event publish returned HTTP ${String(response.status)}`);
+		}
+		await response.text().catch(() => void 0);
+	};
+	const scheduleNext = () => {
+		if (stopped) return;
+		if (timer) return;
+		timer = setTimeoutImpl(() => {
+			timer = void 0;
+			tick().finally(scheduleNext);
+		}, nextIntervalMs({
+			baseIntervalMs: options.baseIntervalMs,
+			consecutiveFailureCount,
+			maxIntervalMs: options.maxIntervalMs
+		}));
+		timer.unref?.();
+	};
+	const tick = async () => {
+		const startedAtMs = options.now();
+		let event;
+		try {
+			const response = await fetchControllerWithPolicy({
+				fetchImpl,
+				input: joinUrl(options.controllerUrl, gatewayControlLinkHealthPins.path),
+				init: { method: "GET" },
+				operation: "controller-health"
+			});
+			const ok = response.ok;
+			await response.text().catch(() => void 0);
+			consecutiveFailureCount = ok ? 0 : consecutiveFailureCount + 1;
+			event = {
+				controllerHost: gatewayControlLinkHealthPins.controllerHost,
+				controllerPort: gatewayControlLinkHealthPins.controllerPort,
+				elapsedMs: options.now() - startedAtMs,
+				kind: "gateway-control-link",
+				observedAtMs: options.now(),
+				operation: gatewayControlLinkHealthPins.operation,
+				path: gatewayControlLinkHealthPins.path,
+				result: ok ? "ok" : "failed",
+				zoneId: options.zoneId
+			};
+		} catch (error) {
+			consecutiveFailureCount += 1;
+			event = {
+				controllerHost: gatewayControlLinkHealthPins.controllerHost,
+				controllerPort: gatewayControlLinkHealthPins.controllerPort,
+				elapsedMs: options.now() - startedAtMs,
+				kind: "gateway-control-link",
+				observedAtMs: options.now(),
+				operation: gatewayControlLinkHealthPins.operation,
+				path: gatewayControlLinkHealthPins.path,
+				result: error instanceof ControllerRequestPolicyTransportError && error.code === "controller-request-timeout" ? "timeout" : "failed",
+				zoneId: options.zoneId
+			};
+			writeLog(`gateway-control-link fetch failed operation=controller-health elapsedMs=${String(event.elapsedMs)} errorCode=${error instanceof ControllerRequestPolicyTransportError ? error.code : "controller-request-failed"}`);
+		}
+		try {
+			await publish(event);
+		} catch (error) {
+			writeLog(`gateway-control-link publish failed operation=health-event-publish elapsedMs=${String(event.elapsedMs)} errorCode=${error instanceof ControllerRequestPolicyTransportError ? error.code : "health-event-publish-failed"} message=${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+	return {
+		consecutiveFailureCount: () => consecutiveFailureCount,
+		noteFailureForTest: () => {
+			consecutiveFailureCount += 1;
+		},
+		start: () => {
+			stopped = false;
+			scheduleNext();
+		},
+		stop: () => {
+			stopped = true;
+			if (!timer) return;
+			clearTimeoutImpl(timer);
+			timer = void 0;
+		},
+		tick
+	};
+}
+//#endregion
 //#region src/openclaw-backend-dependencies.ts
 const OPENCLAW_SSH_SESSION_SCRATCH_ROOT = "/work";
 function createBackendDeps(ssh) {
@@ -670,13 +1409,18 @@ function registerZoneGitTool(options) {
 		},
 		execute: async (_toolCallId, input) => {
 			const expectedHead = readExpectedHead(input);
-			const response = await (options.fetchImpl ?? fetch)(buildControllerUrl(options.controllerUrl, options.zoneId), {
-				body: JSON.stringify({ expectedHead }),
-				headers: {
-					"content-type": "application/json",
-					...options.zoneGitToken ? { [zoneGitCapabilityHeader]: options.zoneGitToken } : {}
+			const response = await fetchControllerWithPolicy({
+				fetchImpl: options.fetchImpl ?? fetch,
+				input: buildControllerUrl(options.controllerUrl, options.zoneId),
+				init: {
+					body: JSON.stringify({ expectedHead }),
+					headers: {
+						"content-type": "application/json",
+						...options.zoneGitToken ? { [zoneGitCapabilityHeader]: options.zoneGitToken } : {}
+					},
+					method: "POST"
 				},
-				method: "POST"
+				operation: "zone-git-push"
 			});
 			const responseText = await readResponseText(response);
 			if (!response.ok) throw new Error(`zone_git_push failed: ${response.status} ${responseText.slice(0, 500)}`);
@@ -693,22 +1437,8 @@ function registerZoneGitTool(options) {
 }
 //#endregion
 //#region src/openclaw-plugin-registration.ts
-const runtimeStatusPublishMaxAttempts = 30;
-const runtimeStatusPublishRetryDelayMs = 1e3;
-function sleep(ms) {
-	return new Promise((resolve) => {
-		setTimeout(resolve, ms);
-	});
-}
-async function publishRuntimeStatusWithRetry(options) {
-	const leaseClient = createLeaseClient({ controllerUrl: options.controllerUrl });
-	for (let attemptIndex = 0; attemptIndex < runtimeStatusPublishMaxAttempts; attemptIndex += 1) try {
-		await leaseClient.publishOpenClawRuntimeStatus?.(options.report);
-		return;
-	} catch (error) {
-		if (attemptIndex === runtimeStatusPublishMaxAttempts - 1) throw error;
-		await sleep(runtimeStatusPublishRetryDelayMs);
-	}
+async function publishRuntimeStatus(options) {
+	await createLeaseClient({ controllerUrl: options.controllerUrl }).publishOpenClawRuntimeStatus?.(options.report);
 }
 const plugin = {
 	id: "gondolin",
@@ -729,6 +1459,13 @@ const plugin = {
 			zoneId: pluginConfig.zoneId
 		});
 		if (api.registrationMode !== "full") return;
+		if (pluginConfig.gatewayControlLinkMonitor?.enabled) createGatewayControlLinkMonitor({
+			baseIntervalMs: pluginConfig.gatewayControlLinkMonitor.baseIntervalMs,
+			controllerUrl: pluginConfig.controllerUrl,
+			maxIntervalMs: pluginConfig.gatewayControlLinkMonitor.maxIntervalMs,
+			now: () => Date.now(),
+			zoneId: pluginConfig.zoneId
+		}).start();
 		const buildRuntimeStatus = () => {
 			const runtimeConfig = api.runtime?.config?.current?.() ?? api.config;
 			return runtimeConfig ? buildOpenClawRuntimeStatusReport({
@@ -737,7 +1474,7 @@ const plugin = {
 			}) : void 0;
 		};
 		const initialRuntimeStatus = buildRuntimeStatus();
-		if (initialRuntimeStatus) publishRuntimeStatusWithRetry({
+		if (initialRuntimeStatus) publishRuntimeStatus({
 			controllerUrl: pluginConfig.controllerUrl,
 			report: initialRuntimeStatus
 		}).catch((error) => {
@@ -759,6 +1496,7 @@ const plugin = {
 			sdkRaw.registerSandboxBackend("gondolin", {
 				factory: createGondolinSandboxBackendFactory({
 					...pluginConfig,
+					openClawRuntimeConfigProvider: () => api.runtime?.config?.current?.() ?? api.config,
 					openClawRuntimeStatusProvider: buildRuntimeStatus
 				}, backendDependencies),
 				manager: createGondolinSandboxBackendManager(pluginConfig, backendDependencies)
@@ -773,6 +1511,6 @@ const plugin = {
 //#region src/index.ts
 const OPENCLAW_GONDOLIN_PLUGIN_PACKAGE_NAME = "@agent-vm/openclaw-agent-vm-plugin";
 //#endregion
-export { ControllerLeaseRequestError, OPENCLAW_DEFAULT_AGENT_ID, OPENCLAW_GONDOLIN_LEASE_SCOPE_GUIDANCE, OPENCLAW_GONDOLIN_PLUGIN_PACKAGE_NAME, OPENCLAW_GONDOLIN_SANDBOX_REQUIREMENTS, OPENCLAW_SSH_SESSION_SCRATCH_ROOT, buildOpenClawRuntimeStatusReport, createBackendDeps, createGondolinSandboxBackendFactory, createGondolinSandboxBackendManager, createLeaseClient, plugin as default, effectiveOpenClawGondolinSandboxValue, findOpenClawGondolinSandboxMismatch, formatOpenClawGondolinRequirementFieldPath, formatOpenClawGondolinRequirementFindingId, formatOpenClawGondolinRequirementHint, isOpenClawAgentId, isOpenClawAgentSessionKey, normalizeOpenClawAgentId, resolveGondolinPluginConfig, resolveOpenClawAgentIdFromSessionKey, snapshotOpenClawGondolinSandboxConfig };
+export { ControllerLeaseRequestError, ControllerRequestPolicyTransportError, OPENCLAW_DEFAULT_AGENT_ID, OPENCLAW_GONDOLIN_LEASE_SCOPE_GUIDANCE, OPENCLAW_GONDOLIN_PLUGIN_PACKAGE_NAME, OPENCLAW_GONDOLIN_SANDBOX_REQUIREMENTS, OPENCLAW_SSH_SESSION_SCRATCH_ROOT, OpenClawAgentIdError, buildOpenClawRuntimeStatusReport, createBackendDeps, createGatewayControlLinkMonitor, createGondolinSandboxBackendFactory, createGondolinSandboxBackendManager, createLeaseClient, plugin as default, drainControllerResponseBody, effectiveOpenClawGondolinSandboxValue, fetchControllerWithPolicy, findOpenClawGondolinSandboxMismatch, formatOpenClawGondolinRequirementFieldPath, formatOpenClawGondolinRequirementFindingId, formatOpenClawGondolinRequirementHint, isOpenClawAgentId, isOpenClawAgentSessionKey, normalizeOpenClawAgentId, resolveGondolinPluginConfig, resolveOpenClawAgentIdFromSessionKey, snapshotOpenClawGondolinSandboxConfig };
 
 //# sourceMappingURL=index.js.map