@junghanacs/entwurf 0.38.1 → 0.40.0

package/docs/setup-clean-host.md

@@ -18,7 +18,8 @@ evidence split, and its three states must not collapse into "macOS is supported"
   ACP turn, mux. Wiring may be written; that is not a rail receipt. The remaining
   unmeasured Darwin doctor reason is per-process environment DISCOVERY
   (start-key is portable).
-- **UNSUPPORTED** — native Windows only. macOS is never this.
+- **UNSUPPORTED** — native Windows `setup` and its harness rails. macOS is never this.
+  An experimental native-Windows Pi preview (core 0.39.0) exists outside `setup`; see [BASELINE](../BASELINE.md#release-host-baseline).
 
 ## Requirements
 
@@ -242,7 +243,8 @@ message. These are harness tools, not shell subcommands; pi exposes them through
 Pi's built-in MCP as `mcp__entwurf_bridge__<verb>`. The bridge has eight tools;
 pi hides `entwurf_inbox_read` and `entwurf_register_native`, leaving six active.
 Tool-call ingress is MCP; delivery to a pi citizen is still its record-addressed
-Unix control socket. A boot/listing from `check-bridge` is not a model-turn or
+control address (a Unix socket; a named pipe on the experimental native-Windows Pi
+preview). A boot/listing from `check-bridge` is not a model-turn or
 native-rail acceptance.
 
 To inspect the ACP provider from a project-local package instead of a global one:
@@ -447,6 +449,34 @@ The owned source is formatted at upstream width (`biome.json` override, indentWi
 per-file exception. A formatting change to an owned file changes its emitted bytes. So it is
 re-emitted with `--write`, and its generated digest is reviewed like any other carrier change.
 
+## 2c. Optional remote pair between two hosts (#107)
+
+This lets one declared pair of existing citizens on two hosts reach each other over SSH that you already run. [DELIVERY](../DELIVERY.md#remote-pair-107-one-declared-pair-across-two-hosts) owns the contract. The machine boundary is set by a person, and nothing here is automatic.
+
+1. **Connect the hosts yourself.** Use a private network (Tailscale or similar is recommended) and SSH keys and authorization you already trust. From each host, `ssh -o BatchMode=yes <alias> true` must succeed non-interactively, and the other host's non-interactive `command -v entwurf` must resolve to the installation you intend. Entwurf edits no SSH config, key, known-hosts file or network setting. Whatever SSH itself writes under your own policy, such as host-key updates, stays yours.
+2. **Run the accepted bytes on both hosts, in the processes that matter.** See [applying new source to a running host](#applying-new-source-to-a-running-host). A pulled checkout or a green setup line does not, by itself, show what a running bridge loaded.
+3. **Write one file on each host,** at `remotePairOptInPath()`. That is the pi agent dir unless `ENTWURF_META_SESSIONS_DIR` moves the meta-record store. Check that the sending bridge's environment and the SSH receive environment resolve the same path. Use mode `0600` and never overwrite a file you did not inspect:
+
+   ```json
+   {
+     "remoteGardenId": "<the other host's garden id>",
+     "ssh": "<your existing alias for the other host>",
+     "localGardenId": "<this host's garden id that talks to it>",
+     "remotePairFile": "<absolute path of the other host's own file>"
+   }
+   ```
+
+   The two files mirror each other: one host's `remoteGardenId` is the other's `localGardenId`. The other host's `remotePairFile` must spell this path as it is normalized, not through a symlinked alias.
+
+   To check a file, read it with the repository's internal parser from a source checkout. Use the same agent/store-root settings the bridge runs with. This is a read-only dev-clone check: there is no installed operator validation verb, and it performs no send and no model input.
+
+   ```bash
+   node --experimental-strip-types -e 'import("./pi-extensions/lib/remote-pair-send.ts").then(m=>console.log(m.readRemotePairOptIn(m.remotePairOptInPath())))'
+   ```
+
+   Do not validate the configuration by sending a test message.
+4. **Use it only between siblings you have open.** The measured self-fetch pair must be active and armed, and the target rail's own admission still applies. Delivery never starts, resumes or wakes an OFF citizen. To an active, armed one it rings the normal doorbell, which may start a turn at once in the receiving TUI. Remove the file to switch the pair off; there is nothing to stop or reconnect.
+
 ## 3. Optional Claude Code native citizen
 
 This rail is CERTIFIED on Linux; on macOS it is NOT CERTIFIED — pending physical
@@ -1126,6 +1156,17 @@ run `pnpm install` when the lockfile changed and `pnpm run build-bridge` before
 artifact-consuming checks such as `./run.sh check-bridge-delivery`; ignored dist
 may be missing or stale. Installed mode never bootstraps pnpm in `node_modules`.
 
+### Applying new source to a running host
+
+New source on disk is not a fresh runtime. A pi-durable host spawns the compiled bridge `mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js` even from a checkout (the bootstrap's `PACKAGED_BRIDGE_ENTRY`). Ordinary `start.sh` in a checkout runs the TypeScript source instead. An already-running bridge keeps the modules it loaded. So, for a host that has to run new bridge code:
+
+1. Build once from the checkout (`pnpm run build-bridge`, or its body `bash scripts/with-dist-lock.sh bash scripts/build-bridge.sh` when no package lifecycle should run).
+2. Compare the whole compiled output with the accepted candidate's, as a file-set and hash manifest. A hash of the selected entry alone is not enough: the entry can stay identical while a helper it loads differs. Check the pinned SDK set separately, and that the new process started after the build.
+3. Close the visible session and reopen it with its own native same-id resume.
+4. Confirm `entwurf_self` names the same garden id, and that the receiver/owner join points at the new process, whose bridge child started after the build.
+
+A per-component setup PASS or a `git pull` does not show which bytes a running bridge loaded. On 2026-10-20 one host of the #107 pair still selected a pre-feature dist after a pull and a green setup. The cause was not traced. A hash check caught it before the first message, and a manual build and visible resume fixed it. Entwurf adds no auto-build, reload or watcher for this.
+
 ## 8. Release acceptance versus host acceptance
 
 - `entwurf check-bridge`: installed MCP bytes boot; no backend auth.

package/mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js

@@ -84,6 +84,10 @@ import { probeNativeSenderAlive, reconcileSenderIdentityClaims, resolveCodexRequ
 import { applyOmpBridgeChildRootPolicy, defaultMetaMailboxDir, defaultMetaSessionsDir, makeStoreRecordReader, readActiveStoreEntries, readMetaIdentityByGardenId, readMetaInbox, readMetaReceiverMarker, readMetaSenderMarker, requireBackend, } from "../../../pi-extensions/lib/meta-session.js";
 import { RESUME_CALL_REJECT_HINT, resumeCall } from "../../../pi-extensions/lib/mux-resume-call.js";
 import { registerNativeConversation } from "../../../pi-extensions/lib/native-push/register.js";
+import { makeLocalTraceFact, readRemotePairOptIn, remotePairOptInPath, runEntwurfV2WithRemoteRoute, } from "../../../pi-extensions/lib/remote-pair-send.js";
+import { processTransport } from "../../../pi-extensions/lib/remote-pair-transport.js";
+import { CONTROL_SOCKET_DIR } from "../../../pi-extensions/lib/socket-discovery.js";
+import { probeSocketLiveness } from "../../../pi-extensions/lib/socket-probe.js";
 const HOME = os.homedir();
 // ============================================================================
 // OMP root policy — FIRST, before any lazy default-root consumer (#87 B1).
@@ -110,6 +114,14 @@ catch (err) {
 // Directory SOURCE is this adapter's own policy — the bridge honours an explicit
 // ENTWURF_DIR override the pi side does not. The path GRAMMAR is the shared leaf.
 const ENTWURF_DIR = process.env.ENTWURF_DIR ?? defaultControlSocketDir(HOME);
+/** Is this session's own control address up? A socket file's presence on Linux/macOS. On
+ * Windows (#78) the address is a named pipe, which has no file to look at and must not be
+ * opened by a stat (that connects): the owner-validated probe answers instead. */
+async function controlAddressPresent(socketPath) {
+    if (process.platform === "win32")
+        return (await probeSocketLiveness(socketPath)) === "alive";
+    return existsSync(socketPath);
+}
 // ============================================================================
 // Live control-socket discovery for entwurf_peers lives in the TS fact-provider
 // (pi-extensions/lib/entwurf-fact-provider.ts → listEntwurfFacts), which the
@@ -171,7 +183,7 @@ class EntwurfSenderIdentityError extends Error {
             "the send is then marked external/non-replyable).");
     }
 }
-function buildStrictPiSenderEnvelope() {
+async function buildStrictPiSenderEnvelope() {
     const sessionId = process.env.PI_SESSION_ID?.trim();
     const agentId = process.env.PI_AGENT_ID?.trim();
     const cwd = process.cwd();
@@ -195,7 +207,7 @@ function buildStrictPiSenderEnvelope() {
     const socketPath = controlSocketPathIn(ENTWURF_DIR, sessionId);
     const self = computeSelfAddressability({
         origin: "pi-session",
-        socketAlive: existsSync(socketPath),
+        socketAlive: await controlAddressPresent(socketPath),
         socketPathComputable: true,
     });
     return {
@@ -258,7 +270,7 @@ async function buildMetaSenderEnvelope(identity, cwd, trustedMarker) {
 async function resolveAuthoritativeSender(context, cwd = process.cwd()) {
     const sessionId = process.env.PI_SESSION_ID?.trim();
     const agentId = process.env.PI_AGENT_ID?.trim();
-    const pi = sessionId && agentId && cwd ? buildStrictPiSenderEnvelope() : null;
+    const pi = sessionId && agentId && cwd ? await buildStrictPiSenderEnvelope() : null;
     const marker = resolveTrustedMetaSenderIdentity({
         markerPath: process.env.ENTWURF_META_SENDER_MARKER?.trim() || undefined,
     });
@@ -422,11 +434,22 @@ server.tool("entwurf_v2", "CANONICAL DELIVERY SURFACE for garden ids: message, r
         // 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({ 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 });
+        // #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 }, {
+            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) {
@@ -463,7 +486,7 @@ server.tool("entwurf_self", "Return this caller's authoritative identity envelop
             // live socket). The old code synthesized the path and printed it as if
             // it existed — a lie when the session has no --entwurf-control (SE-1).
             const socketPath = controlSocketPathIn(ENTWURF_DIR, sender.sessionId);
-            const socketState = existsSync(socketPath) ? "alive" : "expected";
+            const socketState = (await controlAddressPresent(socketPath)) ? "alive" : "expected";
             extra.socketPath = socketPath;
             extra.socketState = socketState;
             lines.push(socketState === "alive"

package/mcp/entwurf-bridge/dist/pi-extensions/lib/control-socket-path.js

@@ -24,8 +24,17 @@
  * adapter keeps its own root policy: the pi side derives from HOME, the MCP
  * bridge honours `ENTWURF_DIR`. What is unified is the grammar, not the policy.
  *
- * Keep dependency-free except `node:path`.
+ * Windows (#78) has no socket files: the address is a named pipe,
+ * `\\.\pipe\entwurf-<sha256(canonRoot(dir))[:16]>-<gardenId>`. The digest keeps two
+ * store roots on one host apart without putting a path in the pipe namespace; it is not
+ * a new address axis (still the garden id plus the store root). The inverse grammar has
+ * no Windows half because nothing scans the pipe namespace: candidates come from records.
+ *
+ * Keep dependency-free except node builtins (`node:path`, and `node:crypto`/`node:fs`
+ * for the Windows root canonicalisation only).
  */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
 import * as path from "node:path";
 /** Control-socket filename suffix. The stem is a bare garden id. */
 export const CONTROL_SOCKET_SUFFIX = ".sock";
@@ -47,8 +56,54 @@ export function defaultControlSocketDir(home) {
  * @returns {string}
  */
 export function controlSocketPathIn(dir, gardenId) {
+    if (process.platform === "win32")
+        return win32PipeNameFor(dir, gardenId);
     return path.join(dir, `${gardenId}${CONTROL_SOCKET_SUFFIX}`);
 }
+/** Every Windows control pipe this package names starts here. */
+export const WIN32_PIPE_PREFIX = "\\\\.\\pipe\\entwurf-";
+/**
+ * The one spelling of a Windows store root, so Pi A, Pi B, the bridge and peer-facts
+ * derive the same pipe name from differently written paths. The nearest EXISTING ancestor
+ * of `path.win32.resolve(dir)` goes through `realpath` (8.3 names expanded, case from the
+ * filesystem); the components below it are appended as written. Separators become `\`,
+ * there is no trailing separator, and the whole string is lower-cased. Nothing is created
+ * or touched, so the control dir need not exist yet. A failure other than ENOENT throws.
+ *
+ * @param {string} dir
+ * @param {(p: string) => string} [realpath]
+ * @returns {string}
+ */
+export function canonRootWin32(dir, realpath = fs.realpathSync.native) {
+    let head = path.win32.resolve(dir);
+    /** @type {string[]} */
+    const tail = [];
+    for (;;) {
+        try {
+            const joined = path.win32.join(realpath(head), ...tail);
+            return joined.replace(/[\\/]+$/, "").toLowerCase();
+        }
+        catch (err) {
+            const parent = path.win32.dirname(head);
+            if ( /** @type {{ code?: unknown }} */(err).code !== "ENOENT" || parent === head)
+                throw err;
+            tail.unshift(path.win32.basename(head));
+            head = parent;
+        }
+    }
+}
+/**
+ * Forward grammar on Windows: `\\.\pipe\entwurf-<16 hex>-<gardenId>`.
+ *
+ * @param {string} dir
+ * @param {string} gardenId
+ * @param {(p: string) => string} [realpath]
+ * @returns {string}
+ */
+export function win32PipeNameFor(dir, gardenId, realpath) {
+    const digest = createHash("sha256").update(canonRootWin32(dir, realpath), "utf8").digest("hex").slice(0, 16);
+    return `${WIN32_PIPE_PREFIX}${digest}-${gardenId}`;
+}
 /**
  * Inverse grammar: a socket filename back to its garden id, or `null` when the
  * name does not carry the suffix.

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-control-rpc.js

@@ -14,6 +14,7 @@
  * asked to open, and touches nothing pi-specific — it is a pure transport over a path.
  */
 import * as net from "node:net";
+import { win32Native } from "./win32-native.js";
 /**
  * THE `<sender_info>` synthesis — the one place the sender envelope becomes
  * message text. ONE consumer since the visible-first cut (#50 C3):
@@ -101,6 +102,8 @@ export async function fetchControlSocketRuntimeInfo(socketPath, options = {}) {
 }
 export async function sendRpcCommand(socketPath, command, options = {}) {
     const { timeout = 5000 } = options;
+    if (process.platform === "win32")
+        return await sendPipeRpcCommand(socketPath, command, timeout);
     return new Promise((resolve, reject) => {
         const socket = net.createConnection(socketPath);
         socket.setEncoding("utf8");
@@ -173,3 +176,25 @@ export async function sendRpcCommand(socketPath, command, options = {}) {
         });
     });
 }
+/**
+ * The Windows client (#78). The addon makes one owner-validated connect, writes the request
+ * line and returns the first response line, all inside one deadline; a timeout is
+ * `ETIMEDOUT`, a pipe owned by anyone but this token's expected owner is `EPERM` before any
+ * byte. The protocol is request-bound on its own connection, so that first line IS the
+ * answer: anything other than this command's response is refused, never waited past.
+ */
+async function sendPipeRpcCommand(pipeName, command, timeout) {
+    const { responseLine } = await win32Native().pipeRpc(pipeName, JSON.stringify(command), Math.max(0, Math.floor(timeout)));
+    let msg;
+    try {
+        msg = JSON.parse(responseLine.trim());
+    }
+    catch {
+        throw new Error(`control pipe answered ${command.type} with a line that is not JSON`);
+    }
+    const response = msg;
+    if (response?.type !== "response" || response.command !== command.type) {
+        throw new Error(`control pipe answered something other than the ${command.type} response`);
+    }
+    return { response };
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-mailbox-body.js

@@ -60,13 +60,19 @@ export function formatMetaMailboxBody(sender, message, wantsReply) {
     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` +

package/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js

@@ -52,6 +52,7 @@
 import { execFileSync } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
 import * as os from "node:os";
 import * as path from "node:path";
 import { generateSessionId, SESSION_ID_RE } from "./session-id.js";
@@ -845,6 +846,8 @@ const O_NONBLOCK_FLAG = typeof fs.constants.O_NONBLOCK === "number" ? fs.constan
  * Shaping a message is the job of the caller that knows what the answer is FOR.
  */
 export function readStoreRecordFile(file) {
+    if (process.platform === "win32")
+        return win32RecordReader()(file).toString("utf8");
     if (O_NOFOLLOW_FLAG === 0) {
         throw new MetaRecordError(`cannot read meta-record ${path.basename(file)} safely: this platform exposes no O_NOFOLLOW, so a record ` +
             "read cannot refuse a symlink swapped in at the final component. entwurf certifies Linux only.");
@@ -863,6 +866,17 @@ export function readStoreRecordFile(file) {
         fs.closeSync(fd);
     }
 }
+/**
+ * Windows has no `O_NOFOLLOW` (libuv defines it as 0), so the same three decisions — a
+ * final-component reparse point refused as `ELOOP`, a non-regular entry as
+ * `ENTWURF_ENOTREG`, both on the handle the read uses — are made by the preview addon
+ * (#78). It is reached only here and only on win32, through `createRequire`, so the
+ * installers that copy this file without its siblings never load it on Linux or macOS.
+ */
+function win32RecordReader() {
+    const native = createRequire(import.meta.url)("./win32-native.js");
+    return native.win32ReadNoFollow;
+}
 /** The reader every store-WIDE scan pairs with {@link readActiveStoreEntries}. The
  * caller's entry kind decides the POLICY — whether a non-regular entry is a defect
  * (certification), a diagnostic (listing) or a non-candidate (the rival scan) — because

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