@junghanacs/entwurf 0.39.0 → 0.41.0

package/pi-extensions/lib/pi-retire-request.ts

@@ -0,0 +1,111 @@
+/** Pi core-side request adapter, not a public tool or authorization boundary.
+ * The caller supplies a CERTIFIED MetaIdentity and owns authorization, self-retire refusal,
+ * target locking and record freshness. No second lock, record scan or receiver admission
+ * implementation lives here. The receiver owns generation/TUI/idle/pending validation.
+ */
+import * as os from "node:os";
+import type { RetireResult } from "./control-retire.js";
+import { controlSocketPathIn, defaultControlSocketDir } from "./control-socket-path.js";
+import { type RpcRetireCommand, sendRpcCommand } from "./entwurf-control-rpc.ts";
+import type { MetaIdentity } from "./meta-session.js";
+import { SESSION_ID_RE } from "./session-id.js";
+
+type ReceiverRefusal = Extract<RetireResult, { boundary: "refused" }>["reason"];
+const RECEIVER_REFUSALS: readonly ReceiverRefusal[] = [
+	"target-closing",
+	"target-stale",
+	"target-context-unavailable",
+	"target-non-tui",
+	"target-busy",
+	"target-pending",
+];
+
+export type PiRetireRequestResult =
+	| { boundary: "shutdown-requested" }
+	| { boundary: "refused"; phase: "preflight"; reason: "target-backend-unsupported" | "target-identity-mismatch" }
+	| { boundary: "refused"; phase: "receiver"; reason: ReceiverRefusal }
+	| { boundary: "unknown"; reason: "malformed-response" | "transport-error" | "shutdown-call-failed" };
+
+function object(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+	const actual = Object.keys(value);
+	return actual.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+/** Closed wire combinations only. A malformed answer AFTER sending cannot prove no action.
+ * SDK request acceptance is not exit, persistence/flush, or no-further-model-activity evidence.
+ */
+export function parsePiRetireResponse(response: unknown): PiRetireRequestResult {
+	const malformed: PiRetireRequestResult = { boundary: "unknown", reason: "malformed-response" };
+	if (!object(response) || response.type !== "response" || response.command !== "retire") return malformed;
+	if (Object.keys(response).some((key) => !["type", "command", "success", "data", "error", "id"].includes(key))) {
+		return malformed;
+	}
+	if (Object.hasOwn(response, "id") && typeof response.id !== "string") return malformed;
+	const data = response.data;
+	if (!object(data)) return malformed;
+	if (response.success === true && data.boundary === "shutdown-requested") {
+		if (!exactKeys(data, ["boundary"]) || Object.hasOwn(response, "error")) return malformed;
+		return { boundary: "shutdown-requested" };
+	}
+	if (response.success !== false || !exactKeys(data, ["boundary", "reason"]) || response.error !== data.reason) {
+		return malformed;
+	}
+	if (data.boundary === "refused" && RECEIVER_REFUSALS.includes(data.reason as ReceiverRefusal)) {
+		return { boundary: "refused", phase: "receiver", reason: data.reason as ReceiverRefusal };
+	}
+	if (data.boundary === "unknown" && data.reason === "shutdown-call-failed") {
+		return { boundary: "unknown", reason: "shutdown-call-failed" };
+	}
+	return malformed;
+}
+
+export interface PiRetireRequestOptions {
+	/** Internal composition root's existing socket directory; never a target-supplied path. */
+	controlSocketDir?: string;
+	/** Bounds this ONE transport request; a timeout never starts a retry/fallback. */
+	timeoutMs?: number;
+	/** Existing RPC seam, injectable for deterministic wire-result tests. */
+	sendRpc?: (
+		socketPath: string,
+		command: RpcRetireCommand,
+		options: { timeout: number },
+	) => Promise<{ response: unknown }>;
+}
+
+export async function requestPiRetire(
+	target: MetaIdentity,
+	expected: { gardenId: string; nativeSessionId: string },
+	options: PiRetireRequestOptions = {},
+): Promise<PiRetireRequestResult> {
+	if (target.backend !== "pi") {
+		return { boundary: "refused", phase: "preflight", reason: "target-backend-unsupported" };
+	}
+	if (
+		target.gardenId !== expected.gardenId ||
+		target.nativeSessionId !== expected.nativeSessionId ||
+		!SESSION_ID_RE.test(target.gardenId) ||
+		target.nativeSessionId.length === 0
+	) {
+		return { boundary: "refused", phase: "preflight", reason: "target-identity-mismatch" };
+	}
+	const socketPath = controlSocketPathIn(
+		options.controlSocketDir ?? defaultControlSocketDir(os.homedir()),
+		target.gardenId,
+	);
+	try {
+		const { response } = await (options.sendRpc ?? sendRpcCommand)(
+			socketPath,
+			{ type: "retire", gardenId: target.gardenId, nativeSessionId: target.nativeSessionId },
+			{ timeout: options.timeoutMs ?? 5000 },
+		);
+		return parsePiRetireResponse(response);
+	} catch {
+		// The RPC API does not expose whether bytes were written. Even connection errors
+		// are conservatively unknown here; do not infer a safe pre-send refusal or retry.
+		return { boundary: "unknown", reason: "transport-error" };
+	}
+}

package/pi-extensions/lib/remote-pair-receive.ts

@@ -0,0 +1,184 @@
+/**
+ * remote-pair-receive — the RECEIVING half of #107's one declared remote pair (rail 1).
+ *
+ * The host that owns the target record runs this once per SSH call. It reads one JSON claim
+ * from stdin, checks it against the operator-written pair declaration, and hands a matching
+ * claim to the existing v2 dispatch. The record, owner and deliverability checks stay the
+ * dispatch's own: nothing here writes a mailbox, resolves a rail, or retries.
+ *
+ * Trust model (GLG, #107 D3 (a)): the boundary is the same operator's SSH account. The pair
+ * check is a SCOPE limit, not authentication: a claim whose `from`/`target` is not the declared
+ * pair is refused before any mutation. It does not detect that same account sending the
+ * declared gid falsely; nothing here claims to.
+ *
+ * Sender: the stdin claim is the only sender input. Ambient carriers (`PI_SESSION_ID`,
+ * `PI_AGENT_ID`, sender markers) in the SSH environment are never consulted, so this module
+ * does not import the authoritative-sender resolver at all.
+ *
+ * Display (rail 2b): the envelope keeps the existing `external-mcp` / non-replyable origin, so no
+ * receiver, control renderer or self-address table learns a new origin value. A `remote` field
+ * carries the route label and whether a route back is declared; the mailbox body renders it as
+ * `remote via <route>; reply route declared, not probed` (or `no reply route declared`), with the
+ * sender's cwd marked as a sender-host path. The pilot's display proof is the self-fetch mailbox
+ * body only: whether another rail (a live control socket, native-push injection) shows the same
+ * label is NOT PROVEN here, and nothing in this lane unifies the display across rails.
+ */
+
+import type { SenderEnvelope } from "./entwurf-control-rpc.ts";
+import type { EntwurfV2SurfaceRendered, SurfaceEntwurfV2Params } from "./entwurf-v2-surface.ts";
+import type { MailboxSenderEnvelope } from "./meta-mailbox-body.ts";
+import { requireGardenId } from "./meta-session.ts";
+
+/** One operator-declared pair, as written on the RECEIVING host. */
+export interface RemotePairDeclaration {
+	/** The sender's garden id on the other host. */
+	remoteGardenId: string;
+	/** The SSH alias this host uses to reach it (route label; never an identity). */
+	ssh: string;
+	/** The garden id on THIS host the remote sender may address. */
+	localGardenId: string;
+}
+
+/** What the sending host writes to stdin. */
+export interface RemoteClaim {
+	from: string;
+	fromAgentId: string;
+	/** A path on the SENDING host. Shown, never checked here. */
+	fromCwd: string;
+	target: string;
+	message: string;
+	wantsReply: boolean;
+}
+
+export type RemotePairRejectReason = "remote-pair-from-mismatch" | "remote-pair-target-mismatch";
+
+export type RemoteReceiveReceipt =
+	| { kind: "rejected"; reason: RemotePairRejectReason; detail: string }
+	| { kind: "dispatched"; isError: boolean; text: string };
+
+export interface RemoteReceiveDeps {
+	dispatch: (params: SurfaceEntwurfV2Params, sender: SenderEnvelope) => Promise<EntwurfV2SurfaceRendered>;
+	now?: () => Date;
+	/** Whether THIS host declares a route back to the sender. Shown, never probed. Default: none. */
+	replyRoute?: "declared" | "none";
+}
+
+const MESSAGE_CAP = 16000;
+
+/** Every Unicode control character (the class herdr-fresh-call.ts refuses). A header field is
+ * rendered unescaped into the body's `[entwurf received]` block, so a newline in one could forge a
+ * `session:` or `wants reply:` line. The message body keeps its newlines. */
+const CONTROL_CHAR = /\p{Cc}/u;
+
+export class RemotePairInputError extends Error {}
+
+function parseObject(text: string, what: string): Record<string, unknown> {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		throw new RemotePairInputError(`${what}: not JSON (${err instanceof Error ? err.message : String(err)})`);
+	}
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+		throw new RemotePairInputError(`${what}: must be a JSON object`);
+	}
+	return raw as Record<string, unknown>;
+}
+
+function requireExactKeys(obj: Record<string, unknown>, keys: readonly string[], what: string): void {
+	const got = Object.keys(obj).sort();
+	const want = [...keys].sort();
+	if (got.length !== want.length || got.some((k, i) => k !== want[i])) {
+		throw new RemotePairInputError(`${what}: keys must be exactly ${want.join(", ")} (got ${got.join(", ")})`);
+	}
+}
+
+function requireString(obj: Record<string, unknown>, key: string, what: string): string {
+	const v = obj[key];
+	if (typeof v !== "string" || v.length === 0) {
+		throw new RemotePairInputError(`${what}: "${key}" must be a non-empty string`);
+	}
+	return v;
+}
+
+/** A field that lands in the rendered sender header: non-empty and free of control characters. */
+function requireHeaderString(obj: Record<string, unknown>, key: string, what: string): string {
+	const v = requireString(obj, key, what);
+	if (CONTROL_CHAR.test(v)) {
+		throw new RemotePairInputError(`${what}: "${key}" must not contain control characters`);
+	}
+	return v;
+}
+
+export function parseRemoteClaim(text: string): RemoteClaim {
+	const what = "remote claim";
+	const obj = parseObject(text, what);
+	requireExactKeys(obj, ["from", "fromAgentId", "fromCwd", "target", "message", "wantsReply"], what);
+	const message = requireString(obj, "message", what);
+	if (message.length > MESSAGE_CAP) {
+		throw new RemotePairInputError(`${what}: "message" exceeds ${MESSAGE_CAP} chars`);
+	}
+	if (typeof obj.wantsReply !== "boolean") {
+		throw new RemotePairInputError(`${what}: "wantsReply" must be a boolean`);
+	}
+	return {
+		from: requireGardenId(obj.from),
+		fromAgentId: requireHeaderString(obj, "fromAgentId", what),
+		fromCwd: requireHeaderString(obj, "fromCwd", what),
+		target: requireGardenId(obj.target),
+		message,
+		wantsReply: obj.wantsReply,
+	};
+}
+
+/** The scope check. Null = inside the declared pair. */
+export function checkRemotePair(
+	claim: RemoteClaim,
+	decl: RemotePairDeclaration,
+): { reason: RemotePairRejectReason; detail: string } | null {
+	if (claim.from !== decl.remoteGardenId) {
+		return {
+			reason: "remote-pair-from-mismatch",
+			detail: `from ${claim.from} is not the declared remote ${decl.remoteGardenId}`,
+		};
+	}
+	if (claim.target !== decl.localGardenId) {
+		return {
+			reason: "remote-pair-target-mismatch",
+			detail: `target ${claim.target} is not the declared local ${decl.localGardenId}`,
+		};
+	}
+	return null;
+}
+
+export function buildRemoteSenderEnvelope(
+	claim: RemoteClaim,
+	decl: RemotePairDeclaration,
+	now: Date,
+	replyRoute: "declared" | "none" = "none",
+): SenderEnvelope & MailboxSenderEnvelope {
+	return {
+		sessionId: claim.from,
+		agentId: claim.fromAgentId,
+		cwd: claim.fromCwd,
+		timestamp: now.toISOString(),
+		origin: "external-mcp",
+		replyable: false,
+		remote: { via: decl.ssh, replyRoute },
+	};
+}
+
+export async function receiveRemoteClaim(
+	claim: RemoteClaim,
+	decl: RemotePairDeclaration,
+	deps: RemoteReceiveDeps,
+): Promise<RemoteReceiveReceipt> {
+	const mismatch = checkRemotePair(claim, decl);
+	if (mismatch) return { kind: "rejected", ...mismatch };
+	const sender = buildRemoteSenderEnvelope(claim, decl, (deps.now ?? (() => new Date()))(), deps.replyRoute);
+	const rendered = await deps.dispatch(
+		{ target: claim.target, intent: "fire-and-forget", message: claim.message, wants_reply: claim.wantsReply },
+		sender,
+	);
+	return { kind: "dispatched", isError: rendered.isError, text: rendered.text };
+}

package/pi-extensions/lib/remote-pair-send.ts

@@ -0,0 +1,325 @@
+/**
+ * remote-pair-send — the SENDING half of #107's one declared remote pair (rail 2a).
+ *
+ * It sits in front of the local v2 decider, at the surface. With no route declaration, or a target
+ * the declaration does not name, the local path runs unchanged. When the declaration names the
+ * target, any local trace of that gid (a record entry in any state, or anything at its control
+ * socket path) fails closed as an ambiguity before transport. Otherwise the call runs over one
+ * transport call: no synthetic record, no new backend, no new rail plan, and no retry.
+ *
+ * Sender: only the caller's authoritative envelope becomes the claim. It must be the declared local
+ * citizen; an anonymous envelope or another gid is refused before transport. The model chooses
+ * neither host nor command: both come from the operator's declaration.
+ *
+ * Remote command: ssh joins the remote words into one shell string. So the alias and the remote
+ * declaration path are held to a narrow POSIX-safe charset that needs no quoting, and the command
+ * is the fixed `entwurf remote-pair-receive --pair <path>`. There is no quoting engine here.
+ *
+ * Receipt: a result is decided only when the exit code and the one stdout JSON line agree
+ * (see {@link classifyRemoteReceipt}). Everything else is `remote-indeterminate`: the other host
+ * may or may not have enqueued. Read and answer stay unknown until a reply arrives.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { controlSocketPathIn } from "./control-socket-path.js";
+import type { SenderEnvelope } from "./entwurf-control-rpc.ts";
+import type { EntwurfV2SurfaceRendered, SurfaceEntwurfV2Params } from "./entwurf-v2-surface.ts";
+import { defaultMetaSessionsDir, metaRecordExistsByGardenId, requireGardenId } from "./meta-session.ts";
+import type { RemoteClaim, RemotePairRejectReason } from "./remote-pair-receive.ts";
+import { inspectControlSocketPath } from "./socket-discovery.ts";
+
+/** The SENDING host's declaration of its one remote pair. */
+export interface RemoteRouteDeclaration {
+	/** The target's garden id on the other host. */
+	remoteGardenId: string;
+	/** SSH alias for the other host (route label; never an identity). */
+	ssh: string;
+	/** The garden id on THIS host that may send to it. */
+	localGardenId: string;
+	/** Absolute path of the other host's pair declaration, passed to its receive entry. */
+	remotePairFile: string;
+}
+
+export interface RemoteTransportResult {
+	exitCode: number | null;
+	signal: string | null;
+	timedOut: boolean;
+	stdout: string;
+	stderr: string;
+}
+
+export interface RemoteTransport {
+	run(argv: readonly string[], stdin: string, timeoutMs: number): Promise<RemoteTransportResult>;
+}
+
+export type RemoteSendOutcome =
+	| { kind: "remote-accepted"; text: string }
+	| { kind: "remote-pair-refused"; reason: RemotePairRejectReason; detail: string }
+	| { kind: "remote-reported-error"; text: string }
+	| { kind: "remote-invalid"; detail: string }
+	| { kind: "remote-indeterminate"; why: string; exitCode: number | null; stderrTail: string };
+
+export class RemoteRouteDeclarationError extends Error {}
+
+const SSH_ALIAS = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const REMOTE_PATH = /^\/[A-Za-z0-9._/-]+$/;
+const CONNECT_TIMEOUT_SECONDS = 10;
+export const REMOTE_SEND_TIMEOUT_MS = 30_000;
+const PAIR_REJECT_REASONS: readonly string[] = ["remote-pair-from-mismatch", "remote-pair-target-mismatch"];
+
+export function parseRemoteRouteDeclaration(text: string): RemoteRouteDeclaration {
+	const what = "remote route declaration";
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		throw new RemoteRouteDeclarationError(`${what}: not JSON (${err instanceof Error ? err.message : String(err)})`);
+	}
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+		throw new RemoteRouteDeclarationError(`${what}: must be a JSON object`);
+	}
+	const obj = raw as Record<string, unknown>;
+	const want = ["localGardenId", "remoteGardenId", "remotePairFile", "ssh"];
+	const got = Object.keys(obj).sort();
+	if (got.length !== want.length || got.some((k, i) => k !== want[i])) {
+		throw new RemoteRouteDeclarationError(`${what}: keys must be exactly ${want.join(", ")} (got ${got.join(", ")})`);
+	}
+	const { ssh, remotePairFile } = obj;
+	if (typeof ssh !== "string" || !SSH_ALIAS.test(ssh)) {
+		throw new RemoteRouteDeclarationError(`${what}: "ssh" must be an alias matching ${SSH_ALIAS}`);
+	}
+	if (
+		typeof remotePairFile !== "string" ||
+		!REMOTE_PATH.test(remotePairFile) ||
+		remotePairFile.split("/").includes("..")
+	) {
+		throw new RemoteRouteDeclarationError(
+			`${what}: "remotePairFile" must be an absolute path matching ${REMOTE_PATH} with no ".." segment`,
+		);
+	}
+	return {
+		remoteGardenId: requireGardenId(obj.remoteGardenId),
+		ssh,
+		localGardenId: requireGardenId(obj.localGardenId),
+		remotePairFile,
+	};
+}
+
+/** The one argv the transport runs. Every word is inside the no-quoting charset above. */
+export function remoteReceiveArgv(route: RemoteRouteDeclaration): string[] {
+	return [
+		"ssh",
+		"-o",
+		"BatchMode=yes",
+		"-o",
+		`ConnectTimeout=${CONNECT_TIMEOUT_SECONDS}`,
+		route.ssh,
+		"entwurf",
+		"remote-pair-receive",
+		"--pair",
+		route.remotePairFile,
+	];
+}
+
+function tail(s: string): string {
+	return s.length > 400 ? s.slice(-400) : s;
+}
+
+/**
+ * Decide only on agreement. 0 + dispatched/!isError = accepted; 3 + rejected(pair reason) = pair
+ * refused; 4 + dispatched/isError = the other host reported an error while processing (its own text
+ * says what is known, e.g. `retry-safe: false` after a possible write; this line infers neither
+ * delivery nor non-delivery); 2 + invalid = it refused our
+ * input. Any other exit, a signal, a timeout, no line, more than one line, non-JSON, or a JSON
+ * kind/field that disagrees with the exit is indeterminate.
+ */
+export function classifyRemoteReceipt(r: RemoteTransportResult): RemoteSendOutcome {
+	const indeterminate = (why: string): RemoteSendOutcome => ({
+		kind: "remote-indeterminate",
+		why,
+		exitCode: r.exitCode,
+		stderrTail: tail(r.stderr),
+	});
+	if (r.timedOut) return indeterminate("timed out");
+	if (r.signal !== null) return indeterminate(`ended by signal ${r.signal}`);
+	if (r.exitCode === null) {
+		return indeterminate(
+			r.stderr.startsWith("spawn failed")
+				? "the transport did not start (spawn failed)"
+				: "did not exit (no exit code)",
+		);
+	}
+	if (![0, 2, 3, 4].includes(r.exitCode)) return indeterminate(`exit ${r.exitCode}`);
+	const nl = r.stdout.indexOf("\n");
+	if (nl === -1 || nl !== r.stdout.length - 1) return indeterminate("stdout is not exactly one line");
+	let j: unknown;
+	try {
+		j = JSON.parse(r.stdout);
+	} catch {
+		return indeterminate("stdout is not JSON");
+	}
+	if (j === null || typeof j !== "object" || Array.isArray(j)) return indeterminate("stdout is not a JSON object");
+	const o = j as Record<string, unknown>;
+	const keys = Object.keys(o).sort().join(",");
+	if (r.exitCode === 0 && keys === "isError,kind,text" && o.kind === "dispatched" && o.isError === false) {
+		if (typeof o.text === "string") return { kind: "remote-accepted", text: o.text };
+	}
+	if (r.exitCode === 4 && keys === "isError,kind,text" && o.kind === "dispatched" && o.isError === true) {
+		if (typeof o.text === "string") return { kind: "remote-reported-error", text: o.text };
+	}
+	if (r.exitCode === 3 && keys === "detail,kind,reason" && o.kind === "rejected") {
+		if (typeof o.reason === "string" && PAIR_REJECT_REASONS.includes(o.reason) && typeof o.detail === "string") {
+			return { kind: "remote-pair-refused", reason: o.reason as RemotePairRejectReason, detail: o.detail };
+		}
+	}
+	if (r.exitCode === 2 && keys === "detail,kind" && o.kind === "invalid" && typeof o.detail === "string") {
+		return { kind: "remote-invalid", detail: o.detail };
+	}
+	return indeterminate(`exit ${r.exitCode} disagrees with its receipt`);
+}
+
+function render(route: RemoteRouteDeclaration, o: RemoteSendOutcome): EntwurfV2SurfaceRendered {
+	const via = `via ${route.ssh}`;
+	switch (o.kind) {
+		case "remote-accepted":
+			return {
+				isError: false,
+				text: `entwurf_v2 remote ${via} → accepted by the other host (its fact; read/answer unknown until a reply arrives; paths below are on the other host)\n${o.text}`,
+			};
+		case "remote-reported-error":
+			// The other host's dispatch returned isError. That can follow a write (an enqueue whose
+			// stamp or signal then threw is `retry-safe: false`), so this header claims neither
+			// non-delivery nor safety to resend: the other host's own text below is the fact.
+			return {
+				isError: true,
+				text: `entwurf_v2 remote ${via} → the other host reported an error while processing; read its receipt below, delivery is not inferred from this line; not retried (paths below are on the other host)\n${o.text}`,
+			};
+		case "remote-pair-refused":
+			return {
+				isError: true,
+				text: `entwurf_v2 remote ${via} → refused by the other host's pair: ${o.reason} (${o.detail})`,
+			};
+		case "remote-invalid":
+			return { isError: true, text: `entwurf_v2 remote ${via} → the other host refused the input: ${o.detail}` };
+		case "remote-indeterminate":
+			return {
+				isError: true,
+				text:
+					`entwurf_v2 remote ${via} → indeterminate: ${o.why}. The other host may or may not have enqueued; ` +
+					`not retried.${o.stderrTail ? `\n${o.stderrTail}` : ""}`,
+			};
+	}
+}
+
+function refuse(text: string): EntwurfV2SurfaceRendered {
+	return { isError: true, text: `entwurf_v2 rejected: ${text}` };
+}
+
+export interface RemoteRouteOptions {
+	senderProvider: () => SenderEnvelope | undefined;
+	/** The declaration, already read; null = no remote pair on this host. */
+	route: RemoteRouteDeclaration | null;
+	/** Any local trace of this gid: a record entry in any state, or anything at its socket path. */
+	localTrace: (gardenId: string) => Promise<boolean>;
+	transport: RemoteTransport;
+	/** The existing local surface, run unchanged when the route does not apply. */
+	runLocal: (
+		params: SurfaceEntwurfV2Params,
+		opts: { senderProvider: () => SenderEnvelope | undefined },
+	) => Promise<EntwurfV2SurfaceRendered>;
+	timeoutMs?: number;
+}
+
+export async function runEntwurfV2WithRemoteRoute(
+	params: SurfaceEntwurfV2Params,
+	opts: RemoteRouteOptions,
+): Promise<EntwurfV2SurfaceRendered> {
+	const route = opts.route;
+	if (route === null || params.target !== route.remoteGardenId) {
+		return opts.runLocal(params, { senderProvider: opts.senderProvider });
+	}
+	if (await opts.localTrace(route.remoteGardenId)) {
+		return refuse(
+			`remote-route-local-conflict: ${route.remoteGardenId} is declared remote ${`via ${route.ssh}`} but this host also has a local trace of it; not choosing`,
+		);
+	}
+	const sender = opts.senderProvider();
+	if (!sender || sender.origin === "external-mcp" || sender.sessionId !== route.localGardenId) {
+		return refuse(
+			`remote-sender-not-declared: only ${route.localGardenId} may send over this route (sender: ${sender ? sender.sessionId : "none"})`,
+		);
+	}
+	const claim: RemoteClaim = {
+		from: sender.sessionId,
+		fromAgentId: sender.agentId,
+		fromCwd: sender.cwd,
+		target: route.remoteGardenId,
+		message: params.message,
+		wantsReply: params.wants_reply ?? false,
+	};
+	const result = await opts.transport.run(
+		remoteReceiveArgv(route),
+		JSON.stringify(claim),
+		opts.timeoutMs ?? REMOTE_SEND_TIMEOUT_MS,
+	);
+	return render(route, classifyRemoteReceipt(result));
+}
+
+/**
+ * The production local-trace fact: the store's own record-entry inspection (absent vs anything
+ * else — readable, unreadable, symlinked or drifted all count) and the control-socket path
+ * inspection, in EVERY socket dir the caller names. The bridge's `ENTWURF_DIR` can differ from the
+ * decider's canonical dir, so both are passed and a trace in either one means this host already
+ * answers to the gid.
+ */
+export function makeLocalTraceFact(dirs: { sessionsDir: string; controlSocketDirs: readonly string[] }) {
+	const socketDirs = [...new Set(dirs.controlSocketDirs.map((d) => path.resolve(d)))];
+	return async (gardenId: string): Promise<boolean> => {
+		if (metaRecordExistsByGardenId(gardenId, dirs.sessionsDir)) return true;
+		for (const dir of socketDirs) {
+			const inspection = await inspectControlSocketPath(controlSocketPathIn(dir, gardenId));
+			if (inspection.kind !== "absent") return true;
+		}
+		return false;
+	};
+}
+
+/** The operator's opt-in file name. One per host; it declares that host's one remote pair. */
+export const REMOTE_PAIR_OPT_IN_FILE = "entwurf-remote-pair.json";
+
+/**
+ * Where the opt-in file lives: beside the meta-record store, i.e. the pi agent dir unless an
+ * `ENTWURF_META_SESSIONS_DIR` override relocates the store (then the file follows the store it
+ * pairs). Read-only reuse of the existing root resolution; nothing here writes.
+ */
+export function remotePairOptInPath(): string {
+	return path.join(path.dirname(defaultMetaSessionsDir()), REMOTE_PAIR_OPT_IN_FILE);
+}
+
+/**
+ * Read the opt-in file once, at the moment of use (no cache). Absent is the ONLY "off". A
+ * symlink, a non-regular entry, an unreadable file or an invalid declaration throws: the operator
+ * opted in, so a broken opt-in is refused rather than read as off.
+ *
+ * The bridge this declares is the operator's to build and secure (for example a private network
+ * such as Tailscale, plus SSH authentication and permissions). Entwurf only walks the declared
+ * route: it installs, configures, discovers and verifies none of it, and never retries.
+ */
+export function readRemotePairOptIn(file: string): RemoteRouteDeclaration | null {
+	let st: fs.Stats;
+	try {
+		st = fs.lstatSync(file);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw err;
+	}
+	if (!st.isFile()) {
+		throw new RemoteRouteDeclarationError(`remote pair opt-in ${file} must be a regular non-symlink file`);
+	}
+	try {
+		return parseRemoteRouteDeclaration(fs.readFileSync(file, "utf8"));
+	} catch (err) {
+		throw new RemoteRouteDeclarationError(`${file}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}