@junghanacs/entwurf 0.38.1 → 0.40.0

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/pi-extensions/lib/socket-discovery.js

@@ -51,7 +51,7 @@
  */
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
-import { CONTROL_SOCKET_SUFFIX, controlSocketPathIn, defaultControlSocketDir, gardenIdFromSocketFilename, } from "./control-socket-path.js";
+import { CONTROL_SOCKET_SUFFIX, controlSocketPathIn, defaultControlSocketDir, gardenIdFromSocketFilename, WIN32_PIPE_PREFIX, } from "./control-socket-path.js";
 import { SESSION_ID_RE } from "./session-id.js";
 import { probeSocketLiveness } from "./socket-probe.js";
 /** Canonical control-socket directory; the socket filename IS the gardenId
@@ -81,7 +81,9 @@ export function controlSocketPath(gardenId, dir = CONTROL_SOCKET_DIR) {
  * `record-less-socket` reject (a diagnostic state) — no probe, no acceptance.
  */
 export function isRecordLessSocketCandidate(inspection) {
-    return inspection.kind === "socket-file";
+    // A Windows pipe name (#78) is never lstat-ed (see inspectControlSocketPath), so its
+    // `socket-file` carries no presence evidence and cannot confirm a record-less socket.
+    return inspection.kind === "socket-file" && !inspection.socketPath.startsWith(WIN32_PIPE_PREFIX);
 }
 /**
  * Inspect the EXACT control-socket path given (no gid re-derivation) and classify it by
@@ -94,6 +96,12 @@ export function isRecordLessSocketCandidate(inspection) {
  * symlink is caught as an address-conflict and never connected, P1).
  */
 export async function inspectControlSocketPath(socketPath, lstatFn = (p) => fs.lstat(p)) {
+    // Windows (#78): the address is a named pipe. The pipe filesystem has no symlinks to
+    // catch, and opening the name to stat it would CONNECT to it and consume an instance.
+    // So the name is never stat-ed: it is safe to probe because the probe itself refuses a
+    // pipe whose owner is not this token's expected owner before any byte.
+    if (socketPath.startsWith(WIN32_PIPE_PREFIX))
+        return { kind: "socket-file", socketPath };
     let st;
     try {
         st = await lstatFn(socketPath);
@@ -160,8 +168,12 @@ export async function mapInspectionToLiveness(inspection, probeSocket) {
  */
 export async function scanSocketProbes(piCitizenGardenIds, deps = {}) {
     const dir = deps.dir ?? CONTROL_SOCKET_DIR;
+    // Windows (#78) has no socket files to list and nothing scans the pipe namespace: the
+    // candidates are the record-backed citizens alone.
     const readdir = deps.readdir ??
         (async (d) => {
+            if (process.platform === "win32")
+                return [];
             const dirents = await fs.readdir(d, { withFileTypes: true });
             return dirents.map((e) => ({ name: e.name, isSymbolicLink: e.isSymbolicLink() }));
         });

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

@@ -28,6 +28,7 @@
  * hidden — `entwurf_peers` shows it and the v2 decider rejects on it by name.
  */
 import * as net from "node:net";
+import { win32Native } from "./win32-native.js";
 export const DEFAULT_PROBE_TIMEOUT_MS = 300;
 /**
  * Pure classification of a connect-time error code into liveness. Only the two
@@ -56,6 +57,8 @@ export function shouldUnlinkOnGc(liveness) {
  */
 export async function probeSocketLiveness(socketPath, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    if (process.platform === "win32")
+        return await probePipeLiveness(socketPath, timeoutMs);
     return await new Promise((resolve) => {
         const socket = net.createConnection(socketPath);
         const timer = setTimeout(() => {
@@ -76,3 +79,21 @@ export async function probeSocketLiveness(socketPath, opts = {}) {
         });
     });
 }
+/**
+ * The Windows probe (#78): the control address is a named pipe, and a connect alone would
+ * talk to whoever holds the name. The addon connects within one deadline and refuses a pipe
+ * whose owner is not this token's expected owner (`EPERM`) before any byte. Only `ENOENT`
+ * (no instance) is dead; a refused owner, a busy pipe past the deadline and every Win32
+ * failure stay indeterminate. A missing or drifted addon is not a liveness fact: that
+ * refusal throws.
+ */
+async function probePipeLiveness(pipeName, timeoutMs) {
+    const native = win32Native();
+    try {
+        await native.pipeProbe(pipeName, Math.max(0, Math.floor(timeoutMs)));
+        return "alive";
+    }
+    catch (err) {
+        return classifyConnectError(err.code);
+    }
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/win32-native.js

@@ -0,0 +1,182 @@
+/**
+ * win32-native — the Windows preview's native surface (#78), and the only way to reach it.
+ *
+ * Node cannot open a file without following a final-component reparse point on Windows
+ * (libuv `UV_FS_O_NOFOLLOW` is 0), and it cannot check who owns a named pipe before
+ * talking to it. Those two capabilities come from one Entwurf-owned N-API addon,
+ * `native/win32-x64/entwurf_win.node`, built in CI from `native/win32/entwurf_win.c` and
+ * shipped beside `native/win32-x64/manifest.json`. This module verifies the manifest and
+ * the addon bytes BEFORE `process.dlopen`, and refuses by name otherwise:
+ *
+ *   ENTWURF_WIN32_UNSUPPORTED     not win32-x64, no addon in this install (an ordinary
+ *                                 Linux pack), a Node without the N-API floor, or a
+ *                                 verified addon this host cannot load
+ *   ENTWURF_WIN32_NATIVE_DRIFT    the manifest is malformed, or the addon bytes are not the
+ *                                 bytes the manifest names
+ *
+ * There is no repair, no download and no fallback: a refusal is the whole answer.
+ *
+ * Authored as `.js` for the reason `control-socket-path.js` is: it is imported from the
+ * tsc-emit root program and from the strip-types lanes alike. `meta-session.ts` reaches it
+ * only through a win32-only `createRequire`, so the installers that copy `meta-session.ts`
+ * on their own are unchanged on Linux and macOS. Keep dependency-free except node builtins.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+export const WIN32_UNSUPPORTED_CODE = "ENTWURF_WIN32_UNSUPPORTED";
+export const WIN32_DRIFT_CODE = "ENTWURF_WIN32_NATIVE_DRIFT";
+const PACKAGE_NAME = "@junghanacs/entwurf";
+const NATIVE_DIR = path.join("native", "win32-x64");
+const ADDON_FILE = "entwurf_win.node";
+const SHA256 = /^[0-9a-f]{64}$/;
+// The addon is built against exactly this N-API version (native/win32/binding.gyp, build.mjs). A
+// manifest that declares any other value describes some other build: drift, not a floor to honour.
+const ADDON_NAPI_VERSION = 8;
+// One addon object per process, even if two module instances of this file exist (a
+// transpiling loader and Node's own loader can each evaluate it once).
+const SLOT = Symbol.for("entwurf.win32-native.addon");
+// DOS device names open a device, not a file, at any directory. The addon's GetFileType
+// check refuses a non-disk handle anyway; this keeps the open from ever being attempted.
+const DOS_DEVICE = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)$/i;
+/**
+ * @param {string} code
+ * @param {string} message
+ * @param {unknown} [cause]
+ * @returns {Error & { code: string }}
+ */
+function refusal(code, message, cause) {
+    const err = /** @type {Error & { code: string }} */ (new Error(message, cause === undefined ? undefined : { cause }));
+    err.code = code;
+    return err;
+}
+/**
+ * The package root, found from where THIS module lives: the source depth
+ * (`<root>/pi-extensions/lib/`) first, then the compiled depth
+ * (`<root>/mcp/entwurf-bridge/dist/pi-extensions/lib/`). The root is the directory whose
+ * `package.json` names this package; `null` when neither depth does.
+ *
+ * @param {string} [from]
+ * @returns {string | null}
+ */
+export function win32NativePackageRoot(from = path.dirname(fileURLToPath(import.meta.url))) {
+    for (const up of [
+        ["..", ".."],
+        ["..", "..", "..", "..", ".."],
+    ]) {
+        const root = path.resolve(from, ...up);
+        let name;
+        try {
+            name = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"))?.name;
+        }
+        catch {
+            continue;
+        }
+        if (name === PACKAGE_NAME)
+            return root;
+    }
+    return null;
+}
+/**
+ * Verify `<root>/native/win32-x64/` and return the addon path to load. Pure apart from
+ * reading the two files, so the refusals are provable on any host.
+ *
+ * @param {string} root
+ * @param {{ napi?: string | undefined }} [versions]
+ * @returns {{ addonPath: string, sha256: string, napiVersion: number }}
+ */
+export function verifyWin32NativeAt(root, versions = process.versions) {
+    const dir = path.join(root, NATIVE_DIR);
+    const manifestPath = path.join(dir, "manifest.json");
+    let raw;
+    try {
+        raw = fs.readFileSync(manifestPath, "utf8");
+    }
+    catch (err) {
+        if ( /** @type {{ code?: unknown }} */(err).code === "ENOENT") {
+            throw refusal(WIN32_UNSUPPORTED_CODE, `this entwurf install carries no Windows addon (${manifestPath} is absent): only the Windows preview ` +
+                "artifact runs on Windows; an ordinary pack does not.");
+        }
+        throw refusal(WIN32_DRIFT_CODE, `cannot read ${manifestPath}`, err);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(raw);
+    }
+    catch (err) {
+        throw refusal(WIN32_DRIFT_CODE, `${manifestPath} is not JSON`, err);
+    }
+    if (manifest?.schema !== 1 ||
+        manifest.platform !== "win32" ||
+        manifest.arch !== "x64" ||
+        manifest.file !== ADDON_FILE ||
+        typeof manifest.sha256 !== "string" ||
+        !SHA256.test(manifest.sha256) ||
+        manifest.napiVersion !== ADDON_NAPI_VERSION) {
+        throw refusal(WIN32_DRIFT_CODE, `${manifestPath} does not describe one win32-x64 ${ADDON_FILE}`);
+    }
+    const napi = Number(versions.napi);
+    if (!(napi >= ADDON_NAPI_VERSION)) {
+        throw refusal(WIN32_UNSUPPORTED_CODE, `the Windows addon needs N-API ${ADDON_NAPI_VERSION}; this Node offers ${versions.napi ?? "none"}`);
+    }
+    const addonPath = path.join(dir, ADDON_FILE);
+    let bytes;
+    try {
+        bytes = fs.readFileSync(addonPath);
+    }
+    catch (err) {
+        throw refusal(WIN32_DRIFT_CODE, `the manifest names ${addonPath}, which cannot be read`, err);
+    }
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    if (sha256 !== manifest.sha256) {
+        throw refusal(WIN32_DRIFT_CODE, `${addonPath} is not the addon its manifest names (sha256 ${sha256} != ${manifest.sha256})`);
+    }
+    return { addonPath, sha256, napiVersion: ADDON_NAPI_VERSION };
+}
+/**
+ * @typedef {object} Win32NativeAddon
+ * @property {(file: string) => Buffer} readNoFollow
+ * @property {(name: string, line: string, timeoutMs: number) => Promise<{ responseLine: string, serverPid: number }>} pipeRpc
+ * @property {(name: string, timeoutMs: number) => Promise<{ serverPid: number }>} pipeProbe
+ * @property {() => { live: number, cancelledIncomplete: number }} ioStats
+ */
+/** @returns {Win32NativeAddon} */
+export function win32Native() {
+    const held = /** @type {Record<symbol, Win32NativeAddon | undefined>} */ ( /** @type {unknown} */(process))[SLOT];
+    if (held)
+        return held;
+    if (process.platform !== "win32" || process.arch !== "x64") {
+        throw refusal(WIN32_UNSUPPORTED_CODE, `the Windows native surface exists only on win32-x64, not ${process.platform}-${process.arch}`);
+    }
+    const root = win32NativePackageRoot();
+    if (root === null) {
+        throw refusal(WIN32_UNSUPPORTED_CODE, `cannot find the ${PACKAGE_NAME} package root beside this module`);
+    }
+    const { addonPath } = verifyWin32NativeAt(root);
+    const module = { exports: {} };
+    try {
+        process.dlopen(module, addonPath);
+    }
+    catch (err) {
+        throw refusal(WIN32_UNSUPPORTED_CODE, `this host cannot load the verified Windows addon ${addonPath}`, err);
+    }
+    const addon = /** @type {Win32NativeAddon} */ (module.exports);
+    /** @type {Record<symbol, Win32NativeAddon | undefined>} */ ( /** @type {unknown} */(process))[SLOT] = addon;
+    return addon;
+}
+/**
+ * Read a record's bytes on Windows, refusing a final-component reparse point (`ELOOP`) and
+ * a non-regular entry (`ENTWURF_ENOTREG`) on the very handle the read uses. Over 16 MiB is
+ * `EFBIG`; other Win32 failures are `EWIN32_<n>`.
+ *
+ * @param {string} file
+ * @returns {Buffer}
+ */
+export function win32ReadNoFollow(file) {
+    const stem = path.win32.basename(file).split(".")[0].replace(/[ ]+$/, "");
+    if (DOS_DEVICE.test(stem)) {
+        throw refusal("ENTWURF_ENOTREG", `${path.win32.basename(file)} names a DOS device, never a record`);
+    }
+    return win32Native().readNoFollow(file);
+}

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);