@agent-vm/gateway-interface 0.0.82 → 0.0.85

package/dist/index.js

@@ -25,6 +25,428 @@ function gatewayVmAllowedHosts(egressHosts) {
 	return Array.from(new Set([controllerVmHost, ...egressHostsForAudience(egressHosts, "gateway")]));
 }
 //#endregion
+//#region src/health/controller-request-policy.ts
+const gatewayInternalControllerRequestOperations = [
+	"controller-health",
+	"health-event-publish",
+	"openclaw-runtime-status",
+	"zone-git-push",
+	"lease-create",
+	"lease-get",
+	"lease-peek",
+	"lease-list",
+	"lease-renew",
+	"lease-release",
+	"lease-use-start",
+	"lease-heartbeat",
+	"lease-use-end"
+];
+const workerInternalControllerRequestOperations = ["worker-push-branches", "worker-pull-default"];
+const dedicatedControllerRequestHealthEventOperationSet = new Set(["lease-heartbeat", "lease-renew"]);
+function isGenericControllerRequestEventOperation(operation) {
+	return !dedicatedControllerRequestHealthEventOperationSet.has(operation);
+}
+const genericControllerRequestEventOperations = [...gatewayInternalControllerRequestOperations, ...workerInternalControllerRequestOperations].filter(isGenericControllerRequestEventOperation);
+const externalControllerRoutes = [
+	"GET /controller-status",
+	"GET /zones/:zoneId/status",
+	"GET /zones/:zoneId/health",
+	"GET /zones/:zoneId/zone-git/status",
+	"GET /zones/:zoneId/logs",
+	"POST /zones/:zoneId/credentials/refresh",
+	"POST /zones/:zoneId/destroy",
+	"POST /zones/:zoneId/upgrade",
+	"GET /zones/:zoneId/tasks/:taskId",
+	"POST /zones/:zoneId/worker-tasks",
+	"POST /zones/:zoneId/tasks/:taskId/close",
+	"POST /zones/:zoneId/enable-ssh",
+	"POST /zones/:zoneId/execute-command",
+	"POST /stop-controller"
+];
+var ControllerRequestPolicyTransportError = class extends Error {
+	code;
+	operation;
+	constructor(options) {
+		const causeMessage = options.cause instanceof Error ? options.cause.message : String(options.cause);
+		super(`${options.operation} ${options.code}: ${causeMessage}`, { cause: options.cause });
+		this.code = options.code;
+		this.operation = options.operation;
+	}
+};
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted === true) {
+			reject(signal.reason);
+			return;
+		}
+		const timeout = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timeout);
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+function shouldRetryResponse(response, policy) {
+	return policy.retryEnabled && policy.retryStatuses.includes(response.status);
+}
+async function drainControllerResponseBody(response) {
+	if (response.bodyUsed) return;
+	await response.text().catch(() => void 0);
+}
+async function fetchWithTimeout(options) {
+	const abortController = new AbortController();
+	let callerAborted = options.init?.signal?.aborted ?? false;
+	let timedOut = false;
+	const abortFromCaller = () => {
+		callerAborted = true;
+		abortController.abort(options.init?.signal?.reason);
+	};
+	const timeout = setTimeout(() => {
+		timedOut = true;
+		abortController.abort(/* @__PURE__ */ new Error(`${options.operation} timed out after ${String(options.timeoutMs)}ms`));
+	}, options.timeoutMs);
+	if (callerAborted) abortController.abort(options.init?.signal?.reason);
+	else options.init?.signal?.addEventListener("abort", abortFromCaller, { once: true });
+	try {
+		return await options.fetchImpl(options.input, {
+			...options.init,
+			signal: abortController.signal
+		});
+	} catch (error) {
+		if (callerAborted) throw error;
+		throw new ControllerRequestPolicyTransportError({
+			cause: error,
+			code: timedOut ? "controller-request-timeout" : "controller-request-failed",
+			operation: options.operation
+		});
+	} finally {
+		clearTimeout(timeout);
+		options.init?.signal?.removeEventListener("abort", abortFromCaller);
+	}
+}
+async function fetchControllerWithPolicy(options) {
+	const policy = options.policy ?? controllerRequestPolicies[options.operation];
+	const fetchImpl = options.fetchImpl ?? fetch;
+	let lastTransportError;
+	for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) try {
+		const response = await fetchWithTimeout({
+			fetchImpl,
+			init: options.init,
+			input: options.input,
+			operation: options.operation,
+			timeoutMs: policy.timeoutMs
+		});
+		if (attempt < policy.maxAttempts && shouldRetryResponse(response, policy)) {
+			await drainControllerResponseBody(response);
+			if (policy.retryBaseDelayMs > 0) await sleep(policy.retryBaseDelayMs, options.init?.signal ?? void 0);
+			continue;
+		}
+		return response;
+	} catch (error) {
+		if (!(error instanceof ControllerRequestPolicyTransportError)) throw error;
+		lastTransportError = error;
+		if (!(policy.retryEnabled && attempt < policy.maxAttempts)) throw error;
+		if (policy.retryBaseDelayMs > 0) await sleep(policy.retryBaseDelayMs, options.init?.signal ?? void 0);
+	}
+	throw lastTransportError ?? /* @__PURE__ */ new Error(`${options.operation} failed without a response`);
+}
+const controllerRequestPolicies = {
+	"controller-health": {
+		idempotency: "read",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 3e3
+	},
+	"health-event-publish": {
+		idempotency: "safe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 3e3
+	},
+	"openclaw-runtime-status": {
+		idempotency: "safe-mutation",
+		maxAttempts: 30,
+		retryBaseDelayMs: 1e3,
+		retryEnabled: true,
+		retryStatuses: [
+			429,
+			503,
+			504
+		],
+		timeoutMs: 3e3
+	},
+	"zone-git-push": {
+		idempotency: "unsafe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 12e4
+	},
+	"lease-create": {
+		idempotency: "unsafe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 18e4
+	},
+	"lease-get": {
+		idempotency: "read",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"lease-peek": {
+		idempotency: "read",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"lease-list": {
+		idempotency: "read",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"lease-renew": {
+		idempotency: "safe-mutation",
+		maxAttempts: 3,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [
+			429,
+			503,
+			504
+		],
+		timeoutMs: 1e4
+	},
+	"lease-release": {
+		idempotency: "safe-mutation",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"lease-use-start": {
+		idempotency: "safe-mutation",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [
+			429,
+			503,
+			504
+		],
+		timeoutMs: 1e4
+	},
+	"lease-heartbeat": {
+		idempotency: "safe-mutation",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [
+			429,
+			503,
+			504
+		],
+		timeoutMs: 5e3
+	},
+	"lease-use-end": {
+		idempotency: "safe-mutation",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"worker-push-branches": {
+		idempotency: "unsafe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 12e4
+	},
+	"worker-pull-default": {
+		idempotency: "unsafe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 12e4
+	}
+};
+//#endregion
+//#region src/health/agent-vm-health.ts
+const agentVmHealthEventKinds = [
+	"gateway-service-health",
+	"gateway-control-link",
+	"controller-request",
+	"lease-renew",
+	"lease-heartbeat",
+	"tool-vm-ssh",
+	"gateway-plugin-health"
+];
+const agentVmHealthResultKinds = [
+	"ok",
+	"failed",
+	"timeout",
+	"stale"
+];
+const gatewayControlLinkHealthPins = {
+	controllerHost: "controller.vm.host",
+	controllerPort: 18800,
+	operation: "controller-health",
+	path: "/health"
+};
+const zoneHealthStateKinds = [
+	"unknown",
+	"ok",
+	"stale",
+	"failed"
+];
+const zoneHealthIssueKinds = [
+	"gateway-service-unhealthy",
+	"gateway-control-link-unhealthy",
+	"controller-request-failing",
+	"lease-heartbeat-failing",
+	"lease-renew-failing",
+	"tool-vm-ssh-failing",
+	"gateway-plugin-unhealthy",
+	"health-event-stale"
+];
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOneOf(values, value) {
+	return typeof value === "string" && values.includes(value);
+}
+function isNonNegativeFiniteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function hasBaseEventFields(record) {
+	return isNonNegativeFiniteNumber(record.observedAtMs) && isOneOf(agentVmHealthResultKinds, record.result) && typeof record.zoneId === "string" && record.zoneId.length > 0;
+}
+function optionalString(value) {
+	return value === void 0 || typeof value === "string";
+}
+function optionalStatusCode(value) {
+	return value === void 0 || Number.isInteger(value);
+}
+function isAgentVmHealthEvent(value) {
+	if (!isRecord(value) || !hasBaseEventFields(value)) return false;
+	switch (value.kind) {
+		case "gateway-service-health": return typeof value.path === "string" && value.path.length > 0 && Number.isInteger(value.port) && optionalStatusCode(value.statusCode);
+		case "gateway-control-link": return value.controllerHost === gatewayControlLinkHealthPins.controllerHost && value.controllerPort === gatewayControlLinkHealthPins.controllerPort && isNonNegativeFiniteNumber(value.elapsedMs) && value.operation === gatewayControlLinkHealthPins.operation && value.path === gatewayControlLinkHealthPins.path;
+		case "controller-request": return Number.isInteger(value.attempt) && isNonNegativeFiniteNumber(value.elapsedMs) && optionalString(value.errorCode) && Number.isInteger(value.maxAttempts) && isOneOf(genericControllerRequestEventOperations, value.operation) && optionalStatusCode(value.statusCode);
+		case "lease-renew": return typeof value.agentId === "string" && isNonNegativeFiniteNumber(value.elapsedMs) && optionalString(value.errorCode) && typeof value.leaseId === "string";
+		case "lease-heartbeat": return typeof value.agentId === "string" && isNonNegativeFiniteNumber(value.elapsedMs) && optionalString(value.errorCode) && typeof value.leaseId === "string" && typeof value.useId === "string";
+		case "tool-vm-ssh": return typeof value.agentId === "string" && isNonNegativeFiniteNumber(value.elapsedMs) && optionalString(value.errorCode) && typeof value.leaseId === "string" && isOneOf([
+			"command",
+			"file-bridge",
+			"finalize",
+			"probe"
+		], value.operation);
+		case "gateway-plugin-health": return isOneOf(gatewayTypeValues, value.gatewayService) && isOneOf([
+			"starting",
+			"ready",
+			"stopping",
+			"failed"
+		], value.state);
+		default: return false;
+	}
+}
+function healthEventBucketKey(event) {
+	switch (event.kind) {
+		case "gateway-control-link": return `${event.zoneId}:${event.kind}`;
+		case "gateway-service-health": return `${event.zoneId}:${event.kind}:${event.port}:${event.path}`;
+		case "controller-request": return `${event.zoneId}:${event.kind}:${event.operation}`;
+		case "lease-heartbeat": return `${event.zoneId}:${event.kind}:${event.leaseId}:${event.useId}`;
+		case "lease-renew": return `${event.zoneId}:${event.kind}:${event.leaseId}`;
+		case "tool-vm-ssh": return `${event.zoneId}:${event.kind}:${event.leaseId}:${event.operation}`;
+		case "gateway-plugin-health": return `${event.zoneId}:${event.kind}:${event.gatewayService}`;
+	}
+	return assertNeverHealthEvent(event);
+}
+function failedIssueKindForEvent(event) {
+	switch (event.kind) {
+		case "gateway-service-health": return "gateway-service-unhealthy";
+		case "gateway-control-link": return "gateway-control-link-unhealthy";
+		case "controller-request": return "controller-request-failing";
+		case "lease-heartbeat": return "lease-heartbeat-failing";
+		case "lease-renew": return "lease-renew-failing";
+		case "tool-vm-ssh": return "tool-vm-ssh-failing";
+		case "gateway-plugin-health": return "gateway-plugin-unhealthy";
+	}
+	return assertNeverHealthEvent(event);
+}
+function assertNeverHealthEvent(event) {
+	throw new Error(`Unhandled health event kind: ${JSON.stringify(event)}`);
+}
+function issueForEvent(event, options) {
+	if (options.nowMs - event.observedAtMs > options.staleAfterMs) return {
+		kind: "health-event-stale",
+		latestEvent: event,
+		message: `${event.kind} health event is stale`,
+		sinceMs: event.observedAtMs
+	};
+	if (event.result === "failed" || event.result === "timeout" || event.result === "stale") return {
+		kind: failedIssueKindForEvent(event),
+		latestEvent: event,
+		message: `${event.kind} health event reported ${event.result}`,
+		sinceMs: event.observedAtMs
+	};
+}
+function deriveZoneHealthSnapshot(events, options) {
+	const latestByKey = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		if (event.zoneId !== options.zoneId) continue;
+		const key = healthEventBucketKey(event);
+		const previous = latestByKey.get(key);
+		if (!previous || previous.observedAtMs <= event.observedAtMs) latestByKey.set(key, event);
+	}
+	const latestEvents = [...latestByKey.values()].toSorted((first, second) => second.observedAtMs - first.observedAtMs);
+	if (latestEvents.length === 0) return {
+		kind: "unknown",
+		reason: "no-events",
+		zoneId: options.zoneId
+	};
+	const issues = latestEvents.map((event) => issueForEvent(event, options)).filter((issue) => issue !== void 0);
+	if (issues.length === 0) return {
+		kind: "ok",
+		latestEvents,
+		zoneId: options.zoneId
+	};
+	if (issues.some((issue) => issue.kind === "health-event-stale")) return {
+		issues,
+		kind: "stale",
+		latestEvents,
+		zoneId: options.zoneId
+	};
+	return {
+		issues,
+		kind: "failed",
+		latestEvents,
+		zoneId: options.zoneId
+	};
+}
+//#endregion
 //#region src/force-ipv4-egress.ts
 /**
 * Canonical NODE_OPTIONS value for forcing IPv4-preference egress
@@ -62,6 +484,7 @@ function gatewayVmAllowedHosts(egressHosts) {
 * revert recommendation by the Node core team).
 */
 const FORCE_IPV4_EGRESS_NODE_OPTIONS = "--dns-result-order=ipv4first --no-network-family-autoselection";
+const FORCE_IPV4_EGRESS_NODE_OPTION_FLAGS = FORCE_IPV4_EGRESS_NODE_OPTIONS.split(/\s+/u);
 /**
 * Compose the forced IPv4-preference flags with a user-provided
 * NODE_OPTIONS value (if any).
@@ -72,8 +495,9 @@ const FORCE_IPV4_EGRESS_NODE_OPTIONS = "--dns-result-order=ipv4first --no-networ
 * a zone secret happens to provide its own NODE_OPTIONS.
 *
 * Forced flags come FIRST so they are unambiguously applied.
-* User-provided flags are appended verbatim. Node treats NODE_OPTIONS
-* as a whitespace-separated list and all flags apply.
+* User-provided flags are appended verbatim except for duplicate
+* forced IPv4-preference flags. Node treats NODE_OPTIONS as a
+* whitespace-separated list and all flags apply.
 *
 * Returns just the forced flags if the user value is undefined,
 * empty, or whitespace-only.
@@ -93,7 +517,9 @@ const FORCE_IPV4_EGRESS_NODE_OPTIONS = "--dns-result-order=ipv4first --no-networ
 function composeNodeOptions(userValue) {
 	const trimmed = userValue?.trim() ?? "";
 	if (trimmed === "") return FORCE_IPV4_EGRESS_NODE_OPTIONS;
-	return `${FORCE_IPV4_EGRESS_NODE_OPTIONS} ${trimmed}`;
+	const userFlags = trimmed.split(/\s+/u).filter((flag) => !FORCE_IPV4_EGRESS_NODE_OPTION_FLAGS.includes(flag));
+	if (userFlags.length === 0) return FORCE_IPV4_EGRESS_NODE_OPTIONS;
+	return `${FORCE_IPV4_EGRESS_NODE_OPTIONS} ${userFlags.join(" ")}`;
 }
 //#endregion
 //#region src/split-resolved-gateway-secrets.ts
@@ -250,9 +676,11 @@ const TOOL_VM_WORKSPACE_GUEST_ROOT = "/workspace";
 const TOOL_VM_SCRATCH_GUEST_ROOT = "/work";
 const OPENCLAW_STATE_VM_ROOT = "/home/openclaw/.openclaw/state";
 const OPENCLAW_STATE_SANDBOXES_VM_ROOT = `${OPENCLAW_STATE_VM_ROOT}/sandboxes`;
-function isHostRealfsRootMapping(root) {
-	return root.backing.kind === "host-realfs";
-}
+const guidanceNamespaceOrder = [
+	"tool-vm-guest",
+	"openclaw-gateway",
+	"controller-host"
+];
 function pathContainsParentTraversal(inputPath) {
 	return inputPath.split(/\/+/u).includes("..");
 }
@@ -272,11 +700,22 @@ function relativePathForRoot(candidatePath, rootPath) {
 function joinRootAndRelative(rootPath, relativePath) {
 	return relativePath === "" ? rootPath : `${rootPath}/${relativePath}`;
 }
+function runtimeRootIsInvalid(rootPath) {
+	return rootPath.trim() === "" || !rootPath.startsWith("/") || pathContainsParentTraversal(rootPath);
+}
+function namespaceShouldShowInGuidance(root, namespace) {
+	if (root.showInGuidance?.[namespace] !== void 0) return root.showInGuidance[namespace];
+	return namespace !== "controller-host";
+}
 function allowedPathFormsForMapping(mapping, purpose) {
 	return mapping.roots.flatMap((root) => {
 		if (!root.capabilities[purpose]) return [];
 		const suffix = root.rootPathAllowed ? "[/subpath]" : "/<child>";
-		return [root.guestRoot, root.backing.kind === "host-realfs" && root.showHostRootInGuidance !== false ? root.hostRoot : void 0].filter((value) => value !== void 0).map((value) => `${normalizeRoot(value)}${suffix}`);
+		return guidanceNamespaceOrder.flatMap((namespace) => {
+			const rootPath = root.locations[namespace];
+			if (rootPath === void 0 || !namespaceShouldShowInGuidance(root, namespace)) return [];
+			return [`${normalizeRoot(rootPath)}${suffix}`];
+		});
 	});
 }
 function retryGuidanceForMapping(mapping, purpose) {
@@ -297,23 +736,26 @@ function errorResult(params) {
 	};
 }
 function findBestRootMatch(params) {
-	return params.mapping.roots.flatMap((root) => {
-		const guestRoot = root.guestRoot === void 0 ? void 0 : normalizeRoot(root.guestRoot);
-		let hostRoot;
-		if (isHostRealfsRootMapping(root)) hostRoot = normalizeRoot(root.hostRoot);
-		const rootMatches = [];
-		if (guestRoot !== void 0 && pathMatchesRoot(params.inputPath, guestRoot)) rootMatches.push({
-			inputNamespace: "guest",
-			matchedRoot: guestRoot,
-			root
-		});
-		if (hostRoot !== void 0 && pathMatchesRoot(params.inputPath, hostRoot)) rootMatches.push({
-			inputNamespace: "host",
-			matchedRoot: hostRoot,
+	return params.mapping.roots.flatMap((root) => guidanceNamespaceOrder.flatMap((inputNamespace) => {
+		const rootPath = root.locations[inputNamespace];
+		if (rootPath === void 0) return [];
+		if (params.sourceNamespace !== void 0 && inputNamespace !== params.sourceNamespace) return [];
+		const normalizedRoot = normalizeRoot(rootPath);
+		return pathMatchesRoot(params.inputPath, normalizedRoot) ? [{
+			inputNamespace,
+			matchedRoot: normalizedRoot,
 			root
-		});
-		return rootMatches;
-	}).toSorted((left, right) => right.matchedRoot.length - left.matchedRoot.length)[0];
+		}] : [];
+	})).toSorted((left, right) => right.matchedRoot.length - left.matchedRoot.length)[0];
+}
+function findInvalidRoot(mapping) {
+	for (const root of mapping.roots) for (const namespace of guidanceNamespaceOrder) {
+		const rootPath = root.locations[namespace];
+		if (rootPath !== void 0 && runtimeRootIsInvalid(rootPath)) return {
+			rootId: root.id,
+			rootPath
+		};
+	}
 }
 function translateRuntimePath(input) {
 	if (!input.inputPath.startsWith("/")) return errorResult({
@@ -330,10 +772,19 @@ function translateRuntimePath(input) {
 		message: `Path '${input.inputPath}' must not contain parent traversal.`,
 		purpose: input.purpose
 	});
+	const invalidRoot = findInvalidRoot(input.mapping);
+	if (invalidRoot !== void 0) return errorResult({
+		code: "invalid-runtime-root",
+		inputPath: input.inputPath,
+		mapping: input.mapping,
+		message: `Runtime path root '${invalidRoot.rootId}' has invalid path '${invalidRoot.rootPath}'.`,
+		purpose: input.purpose
+	});
 	const normalizedInputPath = normalizeAbsolutePath(input.inputPath);
 	const match = findBestRootMatch({
 		inputPath: normalizedInputPath,
-		mapping: input.mapping
+		mapping: input.mapping,
+		...input.sourceNamespace === void 0 ? {} : { sourceNamespace: input.sourceNamespace }
 	});
 	if (match === void 0) return errorResult({
 		code: "unknown-runtime-path",
@@ -357,48 +808,25 @@ function translateRuntimePath(input) {
 		message: `Path '${normalizedInputPath}' matched ${match.root.guidanceLabel} but cannot be used for ${input.purpose}.`,
 		purpose: input.purpose
 	});
-	const guestRoot = match.root.guestRoot === void 0 ? void 0 : normalizeRoot(match.root.guestRoot);
-	let hostRoot;
-	if (isHostRealfsRootMapping(match.root)) hostRoot = normalizeRoot(match.root.hostRoot);
-	if (hostRoot === void 0) {
-		if (guestRoot === void 0) return errorResult({
-			code: "invalid-runtime-root",
-			inputPath: normalizedInputPath,
-			mapping: input.mapping,
-			message: `Runtime path root '${match.root.id}' has no guest path.`,
-			purpose: input.purpose
-		});
-		return {
-			ok: true,
-			value: {
-				backing: match.root.backing,
-				capabilities: match.root.capabilities,
-				guestPath: joinRootAndRelative(guestRoot, relativePath),
-				guestRoot,
-				hasHostBacking: false,
-				inputNamespace: match.inputNamespace,
-				inputPath: normalizedInputPath,
-				kind: "guest-only",
-				mappingId: input.mapping.id,
-				relativePath,
-				rootId: match.root.id
-			}
-		};
-	}
+	const targetRoot = match.root.locations[input.targetNamespace];
+	if (targetRoot === void 0) return errorResult({
+		code: "target-namespace-not-available",
+		inputPath: normalizedInputPath,
+		mapping: input.mapping,
+		message: `Path '${normalizedInputPath}' matched ${match.root.guidanceLabel}, but '${input.targetNamespace}' is not available for that root.`,
+		purpose: input.purpose
+	});
+	const normalizedTargetRoot = normalizeRoot(targetRoot);
 	return {
 		ok: true,
 		value: {
 			backing: match.root.backing,
 			capabilities: match.root.capabilities,
-			...guestRoot !== void 0 ? { guestPath: joinRootAndRelative(guestRoot, relativePath) } : {},
-			...guestRoot !== void 0 ? { guestRoot } : {},
-			hasHostBacking: true,
-			hostPath: joinRootAndRelative(hostRoot, relativePath),
-			hostRoot,
 			inputNamespace: match.inputNamespace,
 			inputPath: normalizedInputPath,
-			kind: "host-backed",
 			mappingId: input.mapping.id,
+			outputNamespace: input.targetNamespace,
+			outputPath: joinRootAndRelative(normalizedTargetRoot, relativePath),
 			relativePath,
 			rootId: match.root.id
 		}
@@ -458,6 +886,6 @@ function isToolVmLeasePeek(value) {
 	return isVmCapabilityLease(record, "ssh-sandbox") && isToolVmLeaseId(Reflect.get(record, "leaseId")) && typeof Reflect.get(record, "agentId") === "string" && typeof Reflect.get(record, "createdAt") === "number" && typeof Reflect.get(record, "idleTtlMs") === "number" && typeof Reflect.get(record, "lastUsedAt") === "number" && typeof Reflect.get(record, "profileId") === "string" && isVmSshPublicEndpoint(Reflect.get(record, "ssh")) && typeof Reflect.get(record, "tcpSlot") === "number" && typeof Reflect.get(record, "workdir") === "string" && typeof Reflect.get(record, "zoneId") === "string" && !Reflect.has(record, deprecatedScopeKeyPropertyName);
 }
 //#endregion
-export { FORCE_IPV4_EGRESS_NODE_OPTIONS, OPENCLAW_STATE_SANDBOXES_VM_ROOT, OPENCLAW_STATE_VM_ROOT, TOOL_VM_SCRATCH_GUEST_ROOT, TOOL_VM_WORKSPACE_GUEST_ROOT, buildGatewaySessionLabel, buildToolSessionLabel, composeNodeOptions, controllerVmHost, createToolVmActiveUseHandle, createToolVmActiveUseId, createToolVmLeaseId, egressHostsForAudience, gatewayTypeValues, gatewayVmAllowedHosts, isToolVmActiveUseId, isToolVmLeaseId, isToolVmLeasePeek, isToolVmSshLease, isVmCapabilityLease, isVmSshEndpoint, isVmSshPublicEndpoint, mergeRuntimeGatewaySecrets, parseToolVmLeaseId, splitResolvedGatewaySecrets, splitResolvedSecretsByInjection, targetsAudience, translateRuntimePath, vmAudienceValues };
+export { ControllerRequestPolicyTransportError, FORCE_IPV4_EGRESS_NODE_OPTIONS, OPENCLAW_STATE_SANDBOXES_VM_ROOT, OPENCLAW_STATE_VM_ROOT, TOOL_VM_SCRATCH_GUEST_ROOT, TOOL_VM_WORKSPACE_GUEST_ROOT, agentVmHealthEventKinds, agentVmHealthResultKinds, buildGatewaySessionLabel, buildToolSessionLabel, composeNodeOptions, controllerRequestPolicies, controllerVmHost, createToolVmActiveUseHandle, createToolVmActiveUseId, createToolVmLeaseId, deriveZoneHealthSnapshot, drainControllerResponseBody, egressHostsForAudience, externalControllerRoutes, fetchControllerWithPolicy, gatewayControlLinkHealthPins, gatewayInternalControllerRequestOperations, gatewayTypeValues, gatewayVmAllowedHosts, genericControllerRequestEventOperations, healthEventBucketKey, isAgentVmHealthEvent, isToolVmActiveUseId, isToolVmLeaseId, isToolVmLeasePeek, isToolVmSshLease, isVmCapabilityLease, isVmSshEndpoint, isVmSshPublicEndpoint, mergeRuntimeGatewaySecrets, parseToolVmLeaseId, splitResolvedGatewaySecrets, splitResolvedSecretsByInjection, targetsAudience, translateRuntimePath, vmAudienceValues, workerInternalControllerRequestOperations, zoneHealthIssueKinds, zoneHealthStateKinds };
 
 //# sourceMappingURL=index.js.map