@junghanacs/entwurf 0.39.0 → 0.40.0

package/scripts/mutants/remote-pair-send.json

@@ -0,0 +1,194 @@
+{
+	"schemaVersion": 1,
+	"lane": "remote-pair-send",
+	"mutants": [
+		{
+			"claim": "REMOTE-ROUTE-UNDECLARED-LOCAL-UNCHANGED",
+			"title": "a declared route captures every target, so a gid the declaration never named is sent to the other host instead of the local decider",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["\tif (route === null || params.target !== route.remoteGardenId) {"],
+			"replace": ["\tif (route === null) {"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUTE-UNDECLARED-LOCAL-UNCHANGED]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUTE-LOCAL-CONFLICT-FAILS-CLOSED",
+			"title": "a declared remote gid that this host also answers to is sent away anyway, so two hosts' citizens share one address and the sender silently picks the remote",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["\tif (await opts.localTrace(route.remoteGardenId)) {"],
+			"replace": ["\tif (Boolean(0)) {"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUTE-LOCAL-CONFLICT-FAILS-CLOSED]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUTE-SENDER-MUST-BE-DECLARED",
+			"title": "any present envelope may use the route, so an anonymous caller or another citizen on this host speaks to the other host as the declared sender",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["\tif (!sender || sender.origin === \"external-mcp\" || sender.sessionId !== route.localGardenId) {"],
+			"replace": ["\tif (!sender || Boolean(0)) {"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUTE-SENDER-MUST-BE-DECLARED]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUTE-EXACT-ARGV-ONCE",
+			"title": "the transport runs ssh without BatchMode, so a missing key turns into an interactive prompt nobody can answer instead of a bounded failure",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["\t\t\"BatchMode=yes\","],
+			"replace": ["\t\t\"BatchMode=no\","],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUTE-EXACT-ARGV-ONCE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUTE-NO-RETRY",
+			"title": "the send runs the transport a second time, so an uncertain first attempt can enqueue the same message twice on the other host",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["\tconst result = await opts.transport.run("],
+			"replace": [
+				"\tawait opts.transport.run(remoteReceiveArgv(route), JSON.stringify(claim), 1);\n\tconst result = await opts.transport.run("
+			],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUTE-NO-RETRY]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-RECEIPT-EXIT-AND-KIND-AGREE",
+			"title": "an accepted-looking JSON line counts as accepted whatever the exit code says, so a refusal or a crash after printing reads as delivery",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": [
+				"\tif (r.exitCode === 0 && keys === \"isError,kind,text\" && o.kind === \"dispatched\" && o.isError === false) {"
+			],
+			"replace": ["\tif (keys === \"isError,kind,text\" && o.kind === \"dispatched\" && o.isError === false) {"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-RECEIPT-EXIT-AND-KIND-AGREE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUTE-DECL-NO-QUOTING-NEEDED",
+			"title": "the remote declaration path may carry spaces or shell metacharacters, which ssh joins into the remote shell string and the other host reinterprets",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["const REMOTE_PATH = /^\\/[A-Za-z0-9._/-]+$/;"],
+			"replace": ["const REMOTE_PATH = /^\\/.+$/;"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUTE-DECL-NO-QUOTING-NEEDED]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUTE-LOCAL-TRACE-ANY-STATE",
+			"title": "a socket at the gid's control path in a named socket dir is not counted as a local trace, so a live local citizen without a record is bypassed for the remote",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["\t\t\tif (inspection.kind !== \"absent\") return true;"],
+			"replace": ["\t\t\tif (false) return true;"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUTE-LOCAL-TRACE-ANY-STATE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUTE-RECEIPT-PATHS-OTHER-HOST",
+			"title": "the accepted receipt drops the note that its paths are on the other host, so the other host's messagePath reads as a file the sender could open",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["read/answer unknown until a reply arrives; paths below are on the other host)"],
+			"replace": ["read/answer unknown until a reply arrives)"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUTE-RECEIPT-PATHS-OTHER-HOST]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-PAIR-OPT-IN-ABSENT-IS-OFF",
+			"title": "an absent opt-in file throws instead of meaning off, so every local send on a host that never opted in fails",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["\t\tif ((err as NodeJS.ErrnoException).code === \"ENOENT\") return null;"],
+			"replace": ["\t\tif (false) return null;"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-OPT-IN-ABSENT-IS-OFF]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-PAIR-OPT-IN-BROKEN-REFUSED",
+			"title": "a symlinked or non-regular opt-in is followed, so the route the bridge walks is whatever the link points at today",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["\tif (!st.isFile()) {\n\t\tthrow new RemoteRouteDeclarationError(`remote pair opt-in"],
+			"replace": ["\tif (false) {\n\t\tthrow new RemoteRouteDeclarationError(`remote pair opt-in"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-OPT-IN-BROKEN-REFUSED]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-REPORTED-ERROR-NO-DELIVERY-INFERENCE",
+			"title": "an error the other host reports after a possible write is headed as a non-delivery, inviting a resend that would deliver twice",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": [
+				"\t\t\t\ttext: `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}`,"
+			],
+			"replace": [
+				"\t\t\t\ttext: `entwurf_v2 remote ${via} → the other host did not deliver (paths below are on the other host)\\n${o.text}`,"
+			],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-REPORTED-ERROR-NO-DELIVERY-INFERENCE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-send.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		}
+	]
+}

package/scripts/mutants/remote-pair-transport.json

@@ -0,0 +1,66 @@
+{
+	"schemaVersion": 1,
+	"lane": "remote-pair-transport",
+	"mutants": [
+		{
+			"claim": "REMOTE-TRANSPORT-NO-SHELL-SEPARATE-STREAMS",
+			"title": "the transport runs its argv through a shell, so a remote declaration word is expanded on the sending host before ssh ever sees it",
+			"subject": "pi-extensions/lib/remote-pair-transport.ts",
+			"find": ["{ shell: false, stdio: [\"pipe\", \"pipe\", \"pipe\"] }"],
+			"replace": ["{ shell: true, stdio: [\"pipe\", \"pipe\", \"pipe\"] }"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-TRANSPORT-NO-SHELL-SEPARATE-STREAMS]",
+			"signatureSource": "pi-extensions/lib/remote-pair-transport.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-TRANSPORT-TIMEOUT-REAPS-OWN-CHILD",
+			"title": "the bound only sends TERM, so an ssh child that ignores it outlives the send and the call never returns",
+			"subject": "pi-extensions/lib/remote-pair-transport.ts",
+			"find": ["\t\t\t\t\tchild.kill(\"SIGKILL\");"],
+			"replace": ["\t\t\t\t\tvoid 0;"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-TRANSPORT-TIMEOUT-REAPS-OWN-CHILD]",
+			"signatureSource": "pi-extensions/lib/remote-pair-transport.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-TRANSPORT-SPAWN-FAILURE-INDETERMINATE",
+			"title": "a child that never started reports exit 0, so a missing ssh binary reads as a clean exit instead of an unknown outcome",
+			"subject": "pi-extensions/lib/remote-pair-transport.ts",
+			"find": ["\t\t\t\t\texitCode: spawnError ? null : code,"],
+			"replace": ["\t\t\t\t\texitCode: spawnError ? 0 : code,"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-TRANSPORT-SPAWN-FAILURE-INDETERMINATE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-transport.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-TRANSPORT-HELD-PIPES-STILL-SETTLE",
+			"title": "the send waits for a close that a pipe-holding descendant never lets happen, so one stuck remote leaves entwurf_v2 hanging forever",
+			"subject": "pi-extensions/lib/remote-pair-transport.ts",
+			"find": ["\t\t\t\t\tfinalTimer = setTimeout(() => {"],
+			"replace": ["\t\t\t\t\tfinalTimer = setTimeout(() => {\n\t\t\t\t\t\treturn;"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-TRANSPORT-HELD-PIPES-STILL-SETTLE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-transport.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		}
+	]
+}

package/scripts/remote-pair-receive.ts

@@ -0,0 +1,73 @@
+#!/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.ts";
+import {
+	parseRemoteClaim,
+	type RemotePairDeclaration,
+	type RemoteReceiveReceipt,
+	receiveRemoteClaim,
+} from "../pi-extensions/lib/remote-pair-receive.ts";
+import { readRemotePairOptIn, remotePairOptInPath } from "../pi-extensions/lib/remote-pair-send.ts";
+
+function emit(receipt: RemoteReceiveReceipt | { kind: "invalid"; detail: string }, code: number): never {
+	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: RemotePairDeclaration;
+let claim: ReturnType<typeof parseRemoteClaim>;
+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);