@junghanacs/entwurf 0.39.0 → 0.40.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-receive.js

@@ -0,0 +1,123 @@
+/**
+ * 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 { requireGardenId } from "./meta-session.js";
+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, what) {
+    let raw;
+    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;
+}
+function requireExactKeys(obj, keys, what) {
+    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, key, what) {
+    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, key, what) {
+    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) {
+    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, decl) {
+    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, decl, now, replyRoute = "none") {
+    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, decl, deps) {
+    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/mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-send.js

@@ -0,0 +1,259 @@
+/**
+ * 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 { defaultMetaSessionsDir, metaRecordExistsByGardenId, requireGardenId } from "./meta-session.js";
+import { inspectControlSocketPath } from "./socket-discovery.js";
+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 = ["remote-pair-from-mismatch", "remote-pair-target-mismatch"];
+export function parseRemoteRouteDeclaration(text) {
+    const what = "remote route declaration";
+    let raw;
+    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;
+    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) {
+    return [
+        "ssh",
+        "-o",
+        "BatchMode=yes",
+        "-o",
+        `ConnectTimeout=${CONNECT_TIMEOUT_SECONDS}`,
+        route.ssh,
+        "entwurf",
+        "remote-pair-receive",
+        "--pair",
+        route.remotePairFile,
+    ];
+}
+function tail(s) {
+    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) {
+    const indeterminate = (why) => ({
+        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;
+    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;
+    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, 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, o) {
+    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) {
+    return { isError: true, text: `entwurf_v2 rejected: ${text}` };
+}
+export async function runEntwurfV2WithRemoteRoute(params, opts) {
+    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 = {
+        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) {
+    const socketDirs = [...new Set(dirs.controlSocketDirs.map((d) => path.resolve(d)))];
+    return async (gardenId) => {
+        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() {
+    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) {
+    let st;
+    try {
+        st = fs.lstatSync(file);
+    }
+    catch (err) {
+        if (err.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/mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-transport.js

@@ -0,0 +1,80 @@
+/**
+ * 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";
+const CAPTURE_CAP = 64 * 1024;
+const KILL_GRACE_MS = 2000;
+const FINAL_GRACE_MS = 2000;
+function capped(chunks, size, chunk) {
+    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 = {
+    run(argv, stdin, timeoutMs) {
+        return new Promise((resolve) => {
+            const out = [];
+            const err = [];
+            const outN = { n: 0 };
+            const errN = { n: 0 };
+            let timedOut = false;
+            let spawnError = null;
+            let settled = false;
+            const child = spawn(argv[0], argv.slice(1), { shell: false, stdio: ["pipe", "pipe", "pipe"] });
+            let killTimer;
+            let finalTimer;
+            const settle = (code, signal) => {
+                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) => capped(out, outN, c));
+            child.stderr.on("data", (c) => 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/mcp/entwurf-bridge/dist/scripts/remote-pair-receive.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * remote-pair-receive — `entwurf remote-pair-receive --pair <absolute file>` (#107 rail 1).
+ *
+ * The receiving host's entry for one declared remote pair. The sending host runs it over one
+ * SSH call and writes one JSON claim to stdin. This entry reads the operator-named pair
+ * declaration once, applies the pair scope check, and hands a matching claim to the existing
+ * v2 dispatch. The scope and trust model are in pi-extensions/lib/remote-pair-receive.ts.
+ *
+ * Scope: `--pair` must name THIS host's own opt-in file (`remotePairOptInPath()`), absolute and
+ * normalized-equal; any other path — even a valid declaration — is exit 2. That one file is the pair
+ * this host accepts and, because it names the sender's host as its route, the declared route back.
+ * The sender's declaration carries the path only so the argv shape is explicit; it selects nothing.
+ *
+ * EXIT CONTRACT (stdout carries a JSON receipt line only where named):
+ *   0 dispatched, the dispatch did not report an error — receipt on stdout
+ *   4 dispatched, the dispatch reported an error (its text says what is known, e.g. a
+ *     rejection or `retry-safe: false` after a possible write) — receipt
+ *   3 refused by the pair scope check, no dispatch ran — receipt
+ *   2 --pair is not this host's opt-in, the opt-in is absent/broken, or the claim is invalid; no
+ *     dispatch ran — `{kind:"invalid"}` receipt;
+ *     wrong argv is ALSO 2 but prints usage on stderr only, with no receipt
+ *   1 an uncaught dispatch/store throw (crash, don't warn) — no receipt; stderr carries the
+ *     error. The sending host reads that as indeterminate.
+ */
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { runAndRenderEntwurfV2FromSurface } from "../pi-extensions/lib/entwurf-v2-surface.js";
+import { parseRemoteClaim, receiveRemoteClaim, } from "../pi-extensions/lib/remote-pair-receive.js";
+import { readRemotePairOptIn, remotePairOptInPath } from "../pi-extensions/lib/remote-pair-send.js";
+function emit(receipt, code) {
+    process.stdout.write(`${JSON.stringify(receipt)}\n`);
+    process.exit(code);
+}
+const args = process.argv.slice(2);
+if (args.length !== 2 || args[0] !== "--pair") {
+    console.error("usage: entwurf remote-pair-receive --pair <this host's opt-in file>  (claim JSON on stdin)");
+    process.exit(2);
+}
+const pairFile = args[1];
+let decl;
+let claim;
+try {
+    // The scope is THIS host's own opt-in, never a file the sender picks: `--pair` must name it
+    // exactly (absolute, normalized), and that one file is read for this receive.
+    const own = remotePairOptInPath();
+    if (!path.isAbsolute(pairFile) || path.normalize(pairFile) !== own) {
+        throw new Error(`--pair must be this host's opt-in file ${own} (got ${pairFile})`);
+    }
+    const route = readRemotePairOptIn(own);
+    if (route === null)
+        throw new Error(`this host has no remote pair opt-in (${own} is absent)`);
+    decl = { remoteGardenId: route.remoteGardenId, ssh: route.ssh, localGardenId: route.localGardenId };
+    claim = parseRemoteClaim(readFileSync(0, "utf8"));
+}
+catch (err) {
+    emit({ kind: "invalid", detail: err instanceof Error ? err.message : String(err) }, 2);
+}
+const receipt = await receiveRemoteClaim(claim, decl, {
+    dispatch: (params, sender) => runAndRenderEntwurfV2FromSurface(params, { senderProvider: () => sender }),
+    // The scope file IS this host's own opt-in, and it names the sender's host as its route: a
+    // matching claim always has a declared route back. Declared, not probed.
+    replyRoute: "declared",
+});
+emit(receipt, receipt.kind === "rejected" ? 3 : receipt.isError ? 4 : 0);

package/mcp/entwurf-bridge/src/index.ts

@@ -108,6 +108,14 @@ import {
 } from "../../../pi-extensions/lib/meta-session.ts";
 import { RESUME_CALL_REJECT_HINT, resumeCall } from "../../../pi-extensions/lib/mux-resume-call.ts";
 import { registerNativeConversation } from "../../../pi-extensions/lib/native-push/register.ts";
+import {
+	makeLocalTraceFact,
+	readRemotePairOptIn,
+	remotePairOptInPath,
+	runEntwurfV2WithRemoteRoute,
+} from "../../../pi-extensions/lib/remote-pair-send.ts";
+import { processTransport } from "../../../pi-extensions/lib/remote-pair-transport.ts";
+import { CONTROL_SOCKET_DIR } from "../../../pi-extensions/lib/socket-discovery.ts";
 import { probeSocketLiveness } from "../../../pi-extensions/lib/socket-probe.ts";
 
 const HOME = os.homedir();
@@ -520,12 +528,24 @@ server.tool(
 			// Resolved ONCE so the dispatch-moment timestamp is fixed and the control RPC sender
 			// + the mailbox body sender share one envelope. No replyability gate (see above).
 			const sender = await buildSendSenderEnvelope({ requestMeta: extra._meta });
-			const rendered = await runAndRenderEntwurfV2FromSurface(
+			// #107: the operator's remote-pair opt-in is read per send. Absent = off and the local
+			// surface below runs exactly as before; a declared target goes over that one route.
+			const rendered = await runEntwurfV2WithRemoteRoute(
 				{ target, intent, message, mode, wants_reply },
-				// No trust-preflight inputs are passed, and none exist to pass: the preflight on this
-				// path guarded the resume verdict and left with `owned-outcome`. `senderProvider` is
-				// the whole options surface now.
-				{ senderProvider: () => sender },
+				{
+					senderProvider: () => sender,
+					route: readRemotePairOptIn(remotePairOptInPath()),
+					// The decider's canonical socket dir AND this bridge's ENTWURF_DIR: a trace in either is local.
+					localTrace: makeLocalTraceFact({
+						sessionsDir: defaultMetaSessionsDir(),
+						controlSocketDirs: [CONTROL_SOCKET_DIR, ENTWURF_DIR],
+					}),
+					transport: processTransport,
+					// No trust-preflight inputs are passed, and none exist to pass: the preflight on this
+					// path guarded the resume verdict and left with `owned-outcome`. `senderProvider` is
+					// the whole options surface now.
+					runLocal: (params, opts) => runAndRenderEntwurfV2FromSurface(params, opts),
+				},
 			);
 			return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
 		} catch (err) {

package/mcp/entwurf-bridge/tsconfig.build.json

@@ -141,6 +141,12 @@
 	// only repo import is meta-session.ts, ALREADY emitted for the store-doctor, so this adds
 	// ONE leaf JS and ZERO new deps. It is an omp-loaded extension module, never in
 	// index.ts's boot closure, so check-entwurf-bridge-pi-free is unaffected.
+	// WHY remote-pair-receive rides THIS build (#107): the sending host's ssh runs the receiving
+	// host's `entwurf remote-pair-receive`, and on an installed host run.sh lives under
+	// node_modules, where run_ts needs a compiled twin. Its repo imports (remote-pair-receive,
+	// remote-pair-send, entwurf-v2-surface, meta-session) are ALREADY emitted for the bridge's own
+	// entwurf_v2 handler, so this adds ONE leaf JS and ZERO new deps. It is never in index.ts's boot
+	// closure.
 	"include": [
 		"./src/index.ts",
 		"../../protocol.js",
@@ -156,6 +162,7 @@
 		"../../scripts/omp-receive-facts.ts",
 		"../../scripts/codex-socket-path.ts",
 		"../../scripts/codex-socket-classify.ts",
+		"../../scripts/remote-pair-receive.ts",
 		"../../pi-extensions/meta-bridge-hook.ts",
 		"../../pi-extensions/meta-bridge-hook-copilot.ts",
 		"../../pi-extensions/meta-bridge-hook-codex.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.39.0",
+	"version": "0.40.0",
 	"description": "Visible sibling sessions across independent agent harnesses: launch in Herdr or tmux, reopen pi in tmux, and deliver messages by garden id; native bridges and Claude/Cortex ACP adapters.",
 	"license": "MIT",
 	"author": {
@@ -195,7 +195,7 @@
 		"check:full": "bash scripts/check-elapsed.sh check:full check:core check:hermetic check:package",
 		"check:core": "pnpm run check:toolchain && pnpm run check:vitest && pnpm run check:contracts",
 		"check:toolchain": "pnpm lint && pnpm typecheck",
-		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-pi-queue-oracle && ./run.sh check-tests-beside-behavior",
+		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-pi-queue-oracle && ./run.sh check-tests-beside-behavior && ./run.sh check-remote-pair-installed-audit",
 		"check:contracts": "./run.sh check-demo-reproducibility && ./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-runner && ./run.sh check-control-send-receipt && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-win32-preview && ./run.sh check-pack-win32-carrier && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-acp-foreground-only && ./run.sh check-acp-set-model-readback && ./run.sh check-acp-vendor-rejection && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push && ./run.sh check-pi-durable-beside && ./run.sh check-pi-durable-carrier && ./run.sh check-pi-durable-native-module",
 		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-meta-hook-session-switch && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-pi-launch && ./run.sh check-codex-app-server-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-birth-hook && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-peer-facts && ./run.sh check-herdr-plugin && ./run.sh check-herdr-plugin-profile && ./run.sh check-herdr-plugin-build && ./run.sh check-herdr-runtime-bootstrap && ./run.sh check-herdr-activation && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-usage-accounting && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-typing-call-fence && ./run.sh check-gate-manifests && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex && ./run.sh check-codex-bridge-identity && ./run.sh check-pi-bridge-sender && ./run.sh check-pi-mcp-register && ./run.sh check-pi-mcp-bridge && ./run.sh check-codex-birth-hook && ./run.sh smoke-codex-config-state && ./run.sh smoke-codex-birth && ./run.sh check-herdr-sandbox",
 		"check:package": "./run.sh check-install-surface && ./run.sh smoke-meta-install-state && ./run.sh smoke-agy-install-state && ./run.sh smoke-setup-verdict && ./run.sh check-pack-pin-matcher && ./run.sh check-pack-consumer-roots && ./run.sh check-package-source-routing && ./run.sh check-install-preflight && ./run.sh check-pack"

package/pi-extensions/lib/meta-mailbox-body.ts

@@ -35,6 +35,9 @@ export interface MailboxSenderEnvelope {
 	timestamp: string; // ISO 8601 UTC
 	origin?: "pi-session" | "external-mcp" | "meta-session";
 	replyable?: boolean;
+	/** #107: set only by the receiving half of a declared remote pair. `via` is the route label;
+	 * `replyRoute` says whether this host declares a route back. Neither is a probe. */
+	remote?: { via: string; replyRoute: "declared" | "none" };
 }
 
 /** `~`-abbreviate a home-relative cwd for display. Reads process.env.HOME. */
@@ -72,14 +75,20 @@ export function formatMetaMailboxBody(sender: MailboxSenderEnvelope, message: st
 	const replyable = sender.replyable === true;
 	const isMeta = sender.origin === "meta-session";
 	const kind = isMeta ? "meta-session, " : "";
+	// A remote sender is never replyable here: no reply route was probed. Its cwd is a path on the
+	// SENDING host, so it is neither abbreviated against this host's HOME nor shown as a local path.
+	const remote = !replyable ? sender.remote : undefined;
 	const sessionLine = replyable
 		? `${sender.sessionId} (${kind}replyable — reply via entwurf_v2 to this sessionId, intent=fire-and-forget)`
-		: isMeta
-			? `${sender.sessionId} (meta-session, non-replyable)`
-			: `${sender.sessionId} (external, non-replyable)`;
+		: remote
+			? `${sender.sessionId} (remote via ${remote.via}; ${remote.replyRoute === "declared" ? "reply route declared, not probed" : "no reply route declared"})`
+			: isMeta
+				? `${sender.sessionId} (meta-session, non-replyable)`
+				: `${sender.sessionId} (external, non-replyable)`;
+	const where = remote ? `${sender.cwd} (sender-host path)` : abbreviateHome(sender.cwd);
 	return (
 		`[entwurf received ⟵]\n` +
-		`  from:        ${sender.agentId} @ ${abbreviateHome(sender.cwd)}\n` +
+		`  from:        ${sender.agentId} @ ${where}\n` +
 		`  session:     ${sessionLine}\n` +
 		`  at:          ${formatKstTimestamp(sender.timestamp)}\n` +
 		`  wants reply: ${wantsReply ? "yes" : "no"}\n` +