@junghanacs/entwurf 0.39.0 → 0.40.0

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)}`);
+	}
+}

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

@@ -0,0 +1,81 @@
+/**
+ * remote-pair-transport — the production process adapter behind #107's `RemoteTransport` (rail 2c).
+ *
+ * One child per send: `spawn(argv[0], argv.slice(1))` with no shell, stdin written once and closed,
+ * stdout and stderr captured separately. On the bound it signals ITS OWN child only (TERM, then KILL
+ * after a short grace); if the pipes are still held after one more grace, it closes its own read ends
+ * and settles as a timeout rather than waiting for a close that may never come. It is not a process manager: it tracks no
+ * other process, scans nothing, and never retries. Classification belongs to
+ * `classifyRemoteReceipt`; this module only reports what the child did.
+ */
+
+import { spawn } from "node:child_process";
+import type { RemoteTransport, RemoteTransportResult } from "./remote-pair-send.ts";
+
+const CAPTURE_CAP = 64 * 1024;
+const KILL_GRACE_MS = 2000;
+const FINAL_GRACE_MS = 2000;
+
+function capped(chunks: Buffer[], size: { n: number }, chunk: Buffer): void {
+	if (size.n >= CAPTURE_CAP) return;
+	const room = CAPTURE_CAP - size.n;
+	const piece = chunk.length > room ? chunk.subarray(0, room) : chunk;
+	chunks.push(piece);
+	size.n += piece.length;
+}
+
+export const processTransport: RemoteTransport = {
+	run(argv, stdin, timeoutMs): Promise<RemoteTransportResult> {
+		return new Promise((resolve) => {
+			const out: Buffer[] = [];
+			const err: Buffer[] = [];
+			const outN = { n: 0 };
+			const errN = { n: 0 };
+			let timedOut = false;
+			let spawnError: string | null = null;
+			let settled = false;
+			const child = spawn(argv[0], argv.slice(1), { shell: false, stdio: ["pipe", "pipe", "pipe"] });
+			let killTimer: NodeJS.Timeout | undefined;
+			let finalTimer: NodeJS.Timeout | undefined;
+			const settle = (code: number | null, signal: NodeJS.Signals | null): void => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(bound);
+				if (killTimer) clearTimeout(killTimer);
+				if (finalTimer) clearTimeout(finalTimer);
+				const stderr = Buffer.concat(err).toString("utf8");
+				resolve({
+					exitCode: spawnError ? null : code,
+					signal: spawnError ? null : signal,
+					timedOut,
+					stdout: Buffer.concat(out).toString("utf8"),
+					stderr: spawnError ? `spawn failed: ${spawnError}${stderr ? `\n${stderr}` : ""}` : stderr,
+				});
+			};
+			const bound = setTimeout(() => {
+				timedOut = true;
+				child.kill("SIGTERM");
+				killTimer = setTimeout(() => {
+					child.kill("SIGKILL");
+					// Something else may still hold our stdout/stderr pipes (an inherited descendant,
+					// an ssh ControlMaster). We do not chase it: after one more grace we close OUR read
+					// ends and settle as a timeout, which the receipt reads as indeterminate.
+					finalTimer = setTimeout(() => {
+						child.stdout.destroy();
+						child.stderr.destroy();
+						settle(child.exitCode, child.signalCode);
+					}, FINAL_GRACE_MS);
+				}, KILL_GRACE_MS);
+			}, timeoutMs);
+			child.stdout.on("data", (c: Buffer) => capped(out, outN, c));
+			child.stderr.on("data", (c: Buffer) => capped(err, errN, c));
+			child.on("error", (e) => {
+				spawnError = e.message;
+			});
+			// A child that exits before reading stdin closes the pipe; that is its outcome, not ours.
+			child.stdin.on("error", () => {});
+			child.on("close", (code, signal) => settle(code, signal));
+			child.stdin.end(stdin);
+		});
+	},
+};

package/run.sh

@@ -328,6 +328,9 @@ Usage:
   ./run.sh meta-bridge-prune          # 1.0.0 meta-bridge Phase 4: LISTING-ONLY store hygiene — classify orphan/stale/ambiguous/keep, print manual rm commands, delete NOTHING ([dir] [--ttl-days N])
   ./run.sh meta-bridge-fresh-cut      # the ONE generation verb (the verb every v3-only rejection names): quiesce-check live sockets/markers/native-push conversations (refusing any surface it cannot inspect), archive meta-sessions/ + meta-mailbox/ to `<dir>.archive-<ts>`, clear dead transport residue, open an empty v3 generation. No migration, no restore — the archive is forensic only. EXIT CONTRACT (#54, `--help` prints it): 0 complete / 1 NOTHING MOVED (re-run, do not setup) / 2 usage / 3 cut transition incomplete (inspect) / 4 cut complete but residue cleanup failed (`setup` may run; re-run only before new citizen birth, otherwise remove residue manually)
   ./run.sh meta-facts                 # #65 owner-normalized READ-ONLY store projection: deterministic JSON {schemaVersion:1, storeDir, citizens: full v3 records sorted by gardenId, defects: {filename,message}} — THE listing contract emitted by the owner so consumers stop copying the certification. No liveness/sockets/transcript contents. EXIT: 0 readable (defects in-band; missing store = empty), 2 usage, 3 unreadable ([dir])
+  ./run.sh check-remote-pair-installed # #107 rail 3, CHECKOUT-ONLY: install a caller-supplied candidate tarball (--tgz <abs>) into a sandboxed consumer prefix, check its compiled remote-pair surface, run the installed `entwurf remote-pair-receive` (usage exit 2 = twin reached), run the T2 roundtrip cells against the installed bridge+entry, and audit that the subject processes resolve every module inside the consumer prefix (with a checkout control). Never repacks; no real ssh, no model
+  ./run.sh check-remote-pair-installed-audit # #107 rail 3: the deterministic counterpart of check-remote-pair-installed — its checkout-invisibility acceptance primitive proven on synthetic logs (real path, root boundary). In check:vitest
+  ./run.sh remote-pair-receive        # #107 rail 1: the RECEIVING half of one operator-declared remote pair. Reads ONE JSON claim {from,fromAgentId,fromCwd,target,message,wantsReply} on stdin, refuses a from/target outside the declared pair before any mutation (a scope limit under the same-operator SSH account trust model, not authentication), then hands a match to the existing v2 dispatch. Ambient sender carriers are never read. Installed, run_ts runs its compiled twin (dist/scripts/remote-pair-receive.js). EXIT: 0 dispatched / 4 dispatched, the dispatch reported an error (delivery not inferred) / 3 pair refused / 2 invalid claim or declaration (JSON receipt) or wrong argv (usage on stderr, no receipt) / 1 uncaught dispatch or store throw (no receipt; the sender reads it as indeterminate) (--pair <absolute declaration file>)
   ./run.sh peer-facts                 # #116 M2-a owner-normalized READ-ONLY peer projection: the same listEntwurfFacts provider through the same renderer entwurf_peers uses, emitted as deterministic JSON {schemaVersion:1, storeDir, peers, diagnostics} so a consumer never re-implements the placement join (whose pi half is a measured vendor floor). NOT the same bytes as an entwurf_peers call and deliberately so: that surface is a human listing (observationLimit, text over the wire), this is a machine projection with UNBOUNDED observation, because a rationed row says `unobserved` and a machine cannot tell that from "nobody could look". `placement` stays a STRUCTURED tagged union ({kind:"herdr-pane",paneId} / unobserved / none / ambiguous) — never the human `herdr <pane>` string. Publishes NO socket coordinate (ENTWURF_DIR selects what is PROBED, #50 C4) and NO herdr agent_status / interactive_ready / screen text. One placement read per listing, no watcher. EXIT: 0 readable (diagnostics in-band; missing store = empty), 2 usage, 3 unreadable ([dir])
   ./run.sh meta-bridge-managed-keys   # 0.10.0 meta-bridge: print the SSOT of settings keys entwurf OWNS (consumers read this to stay disjoint — keyset-owner invariant)
   ./run.sh check-keyset-overlap <fragment.json...>  # 0.10.0 meta-bridge: PREVENTIVE keyset guard — fail if a consumer fragment collides with any pi-owned key (cross-repo; not in pnpm check)
@@ -3387,6 +3390,17 @@ check_acp_sdk_surface() {
   run_vitest test/acp-sdk-surface.contract.test.ts
 }
 
+check_remote_pair_installed_audit() {
+  # #107 rail 3. The deterministic counterpart of `check-remote-pair-installed`: that gate needs a
+  # caller-supplied tarball, so it cannot run in the floor or carry mutants, and its
+  # checkout-invisibility verdict rests on one acceptance primitive
+  # (scripts/lib/remote-pair-installed-audit.ts). This proves that primitive on tiny synthetic
+  # logs and files. `test/**` is not discovered by check-tests-beside-behavior, so it needs this
+  # public coordinate. Zero network, zero child process.
+  section "remote-pair installed-closure audit (synthetic logs)"
+  run_vitest test/remote-pair-installed-audit.test.ts
+}
+
 check_pi_queue_oracle() {
   # #120 P2. The PUBLIC execution coordinate for `test/pi-queue.oracle.test.ts`, and the reason it
   # needs one: the discovery door below selects `pi-extensions/**/*.test.ts` and
@@ -3829,6 +3843,12 @@ check_pack() {
     # out: the placement join it emits is the copy a herdr-side consumer would
     # otherwise fork, and such a consumer runs against an installed host.
     "mcp/entwurf-bridge/dist/scripts/peer-facts.js"
+    # #107 — the receiving host's entry the sender's ssh runs (run_ts twin), plus the three
+    # remote-pair libs the bridge's entwurf_v2 handler and that entry import.
+    "mcp/entwurf-bridge/dist/scripts/remote-pair-receive.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-receive.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-send.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-transport.js"
     # #87 Bundle B — omp-receive-doctor drives this operator projection through
     # run.sh, so installed node_modules must have the compiled twin too.
     "mcp/entwurf-bridge/dist/scripts/omp-receive-facts.js"
@@ -4570,6 +4590,12 @@ _check_pack_install_impl() {
     "mcp/entwurf-bridge/dist/scripts/meta-facts.js"
     # #116 M2-a — the owner-normalized peer projection (see check-pack).
     "mcp/entwurf-bridge/dist/scripts/peer-facts.js"
+    # #107 — the receiving host's entry the sender's ssh runs (run_ts twin), plus the three
+    # remote-pair libs the bridge's entwurf_v2 handler and that entry import.
+    "mcp/entwurf-bridge/dist/scripts/remote-pair-receive.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-receive.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-send.js"
+    "mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-transport.js"
     # #87 Bundle B — omp-receive-doctor reaches this through the installed dispatcher.
     "mcp/entwurf-bridge/dist/scripts/omp-receive-facts.js"
     # 0.12.5 — node_modules-safe plugin hook + lib (see check-pack). The installed
@@ -8412,6 +8438,21 @@ case "$cmd" in
     shift || true
     run_ts scripts/meta-facts.ts "$@"
     ;;
+  check-remote-pair-installed)
+    # #107 rail 3, CHECKOUT-ONLY install gate: installs a caller-supplied candidate tarball into a
+    # sandboxed consumer prefix and drives that install's bridge and entry through the T2 scene,
+    # auditing that the subject processes resolve nothing outside the prefix. Never repacks.
+    shift || true
+    run_ts scripts/check-remote-pair-installed.ts "$@"
+    ;;
+  remote-pair-receive)
+    # #107 rail 1: the receiving host's entry for one declared remote pair. The pair
+    # check runs before the v2 dispatch, so a claim outside the pair mutates nothing;
+    # a match reaches the same record/owner/deliverability checks every local send does.
+    # Installed, run_ts runs its compiled twin; the sending host's ssh reaches it through the bin.
+    shift || true
+    run_ts scripts/remote-pair-receive.ts "$@"
+    ;;
   peer-facts)
     # #116 M2-a READ-ONLY projection of the OBSERVED peer listing: one provider
     # (`listEntwurfFacts`) through one renderer (`renderEntwurfPeers().payload`), so
@@ -8481,6 +8522,9 @@ case "$cmd" in
   check-pi-queue-oracle)
     check_pi_queue_oracle
     ;;
+  check-remote-pair-installed-audit)
+    check_remote_pair_installed_audit
+    ;;
   check-demo-reproducibility)
     check_demo_reproducibility
     ;;