@junghanacs/entwurf 0.39.0 → 0.40.0

package/scripts/check-gate-qualification.ts

@@ -3497,6 +3497,12 @@ let manifestCount: number;
 		"omp-receive": 11,
 		"probe-ordering": 1,
 		"release-gate": 21,
+		"remote-pair-display": 3,
+		"remote-pair-installed-audit": 2,
+		"remote-pair-receive": 8,
+		"remote-pair-roundtrip": 5,
+		"remote-pair-send": 12,
+		"remote-pair-transport": 4,
 		"retired-sent-surface": 2,
 		"resume-args": 6,
 		"resume-launch-identity": 7,

package/scripts/check-remote-pair-installed.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * check-remote-pair-installed — #107 rail 3: the remote pair on an INSTALLED package.
+ *
+ * `./run.sh check-remote-pair-installed --tgz <absolute candidate tarball>`
+ *
+ * Why this is a scripts/ gate and not a source-adjacent vitest test: its subject is an ARTIFACT.
+ * It installs a caller-supplied tarball into a fresh consumer prefix with npm and then drives
+ * that install's own processes (its bridge `start.sh` → compiled dist, its `run.sh` → run_ts →
+ * compiled entry). A test beside the source can only reach the source.
+ *
+ * What it does, once, with every writable root (HOME, npm cache/userconfig, XDG, PI agent dir)
+ * inside one temp sandbox:
+ *   1. copies the given tarball into the sandbox and installs THAT copy (never repacks; the copy's
+ *      sha256 is printed). npm reads the package's declared dependencies from the registry into the
+ *      sandbox cache — a network read, but no model, no operator config and no ssh;
+ *   2. checks the installed package carries the receive entry's compiled twin and the remote libs;
+ *   3. runs the installed `entwurf remote-pair-receive` with wrong argv: usage on stderr, exit 2 —
+ *      the compiled twin was reached through run_ts, not a TS crossing;
+ *   4. runs the existing T2 scene (pi-extensions/lib/remote-pair-roundtrip.test.ts) with its subject
+ *      switched to this install: real installed bridge, stand-in ssh → installed run.sh → installed
+ *      entry → production dispatch, with the same mailbox/provenance/receipt/reverse-dispatch oracles;
+ *   5. audits checkout invisibility: a preload resolve hook records every module each SUBJECT
+ *      process resolves; every file must sit (by real path) inside the consumer prefix. The
+ *      orchestrator (vitest + its fixture writer) is this checkout and is not audited;
+ *   6. control: the same hook on this checkout's own `run.sh remote-pair-receive` must report a
+ *      checkout path, so the audit can see the thing it refuses.
+ *
+ * The subject switch (ENTWURF_REMOTE_PAIR_INSTALLED_PKG and the resolve-hook variables) is set
+ * here and only here: it changes what the T2 cells measure, so it must not be set ambiently.
+ *
+ * Mutation proof covers only the audit's acceptance primitive (scripts/lib/remote-pair-installed-audit.ts);
+ * the install, compiled-surface, twin and roundtrip cells are actual-runtime evidence with the
+ * checkout control, not mutation-qualified.
+ *
+ * Not claimed: the published npm artifact (this is whatever tarball the caller passes), real sshd,
+ * a real remote host, a durable host reading or replying, or the check-pack/check-pack-install floor.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { filesOutsideRoot as outside } from "./lib/remote-pair-installed-audit.ts";
+
+const LABEL = "check-remote-pair-installed";
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const args = process.argv.slice(2);
+if (args.length !== 2 || args[0] !== "--tgz" || !path.isAbsolute(args[1])) {
+	console.error(`usage: ./run.sh ${LABEL} --tgz <absolute candidate tarball>`);
+	process.exit(2);
+}
+const tgz = args[1];
+if (!fs.lstatSync(tgz).isFile()) {
+	console.error(`${LABEL}: --tgz must be a regular file (${tgz})`);
+	process.exit(2);
+}
+
+let passed = 0;
+let failed = 0;
+function ok(label: string, cond: boolean, detail = ""): void {
+	if (cond) {
+		passed++;
+		console.log(`  ok    ${label}`);
+	} else {
+		failed++;
+		console.log(`  FAIL  ${label}${detail ? `\n        ${detail}` : ""}`);
+	}
+}
+
+const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), "entwurf-remote-pair-installed-"));
+const consumer = path.join(sandbox, "consumer");
+const npmHome = path.join(sandbox, "npm-home");
+const logs = path.join(sandbox, "resolve-logs");
+const hook = path.join(sandbox, "resolve-hook.mjs");
+for (const d of [consumer, npmHome, logs]) fs.mkdirSync(d, { recursive: true });
+
+function sandboxEnv(home: string): NodeJS.ProcessEnv {
+	return {
+		PATH: process.env.PATH ?? "",
+		HOME: home,
+		XDG_CONFIG_HOME: path.join(home, ".config"),
+		XDG_DATA_HOME: path.join(home, ".local", "share"),
+		XDG_STATE_HOME: path.join(home, ".local", "state"),
+		XDG_CACHE_HOME: path.join(home, ".cache"),
+		PI_CODING_AGENT_DIR: path.join(home, ".pi", "agent"),
+	};
+}
+
+fs.writeFileSync(
+	hook,
+	[
+		'import { appendFileSync } from "node:fs";',
+		'import { registerHooks } from "node:module";',
+		"const log = process.env.ENTWURF_REMOTE_PAIR_RESOLVE_LOG;",
+		"if (log) {",
+		"\tregisterHooks({",
+		"\t\tresolve(specifier, context, next) {",
+		"\t\t\tconst r = next(specifier, context);",
+		'\t\t\tappendFileSync(log, r.url + "\\n");',
+		"\t\t\treturn r;",
+		"\t\t},",
+		"\t});",
+		"}",
+		"",
+	].join("\n"),
+);
+
+function hookEnv(label: string): NodeJS.ProcessEnv {
+	return { NODE_OPTIONS: `--import=${hook}`, ENTWURF_REMOTE_PAIR_RESOLVE_LOG: path.join(logs, `${label}.log`) };
+}
+
+// The artifact is a snapshot: copy the caller's file into the sandbox once, then hash and install
+// THAT copy, so what is measured is exactly what is installed. Never repacked.
+const snapshot = path.join(sandbox, "artifact", path.basename(tgz));
+fs.mkdirSync(path.dirname(snapshot), { recursive: true });
+fs.copyFileSync(tgz, snapshot);
+const sha = createHash("sha256").update(fs.readFileSync(snapshot)).digest("hex");
+console.log(
+	`[${LABEL}] caller tarball ${tgz}\n[${LABEL}] snapshot ${snapshot}\n[${LABEL}] snapshot sha256 ${sha}\n[${LABEL}] sandbox ${sandbox}`,
+);
+
+try {
+	// 1. Install as-is.
+	fs.writeFileSync(
+		path.join(consumer, "package.json"),
+		JSON.stringify({ name: "remote-pair-consumer", private: true }),
+	);
+	const npm = spawnSync("npm", ["install", snapshot, "--no-audit", "--no-fund"], {
+		cwd: consumer,
+		encoding: "utf8",
+		env: {
+			...sandboxEnv(npmHome),
+			npm_config_cache: path.join(sandbox, "npm-cache"),
+			npm_config_userconfig: path.join(npmHome, ".npmrc"),
+		},
+	});
+	ok(
+		"[QK:RPI-INSTALLED] npm installs the given tarball into a fresh consumer prefix",
+		npm.status === 0,
+		npm.stderr.slice(-800),
+	);
+	const pkg = path.join(consumer, "node_modules", "@junghanacs", "entwurf");
+	const pkgStat = fs.existsSync(pkg) ? fs.lstatSync(pkg) : null;
+	ok(
+		"[QK:RPI-INSTALLED] the package is a real directory inside the consumer (not a link to a checkout)",
+		pkgStat !== null && pkgStat.isDirectory() && !pkgStat.isSymbolicLink(),
+	);
+	if (failed) throw new Error("install failed; later cells would not measure the artifact");
+
+	// 2. The compiled surface is in the package.
+	for (const rel of [
+		"mcp/entwurf-bridge/dist/scripts/remote-pair-receive.js",
+		"mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-receive.js",
+		"mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-send.js",
+		"mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-transport.js",
+	]) {
+		ok(`[QK:RPI-COMPILED-SURFACE] the installed package carries ${rel}`, fs.existsSync(path.join(pkg, rel)));
+	}
+
+	// 3. The installed bin reaches the compiled twin.
+	const home = path.join(sandbox, "usage-home");
+	const usage = spawnSync(path.join(pkg, "run.sh"), ["remote-pair-receive"], {
+		encoding: "utf8",
+		env: { ...sandboxEnv(home), ...hookEnv("installed-usage") },
+	});
+	ok(
+		"[QK:RPI-INSTALLED-ENTRY-TWIN] the installed `entwurf remote-pair-receive` answers wrong argv with usage on stderr, exit 2, no receipt",
+		usage.status === 2 && /usage: entwurf remote-pair-receive/.test(usage.stderr) && usage.stdout === "",
+		`status=${usage.status} stdout=${usage.stdout.slice(0, 200)} stderr=${usage.stderr.slice(0, 300)}`,
+	);
+
+	// 4. The T2 scene against the install.
+	const vitest = spawnSync(
+		path.join(REPO, "node_modules", ".bin", "vitest"),
+		["run", "pi-extensions/lib/remote-pair-roundtrip.test.ts"],
+		{
+			cwd: REPO,
+			encoding: "utf8",
+			env: {
+				...process.env,
+				ENTWURF_REMOTE_PAIR_INSTALLED_PKG: pkg,
+				ENTWURF_REMOTE_PAIR_RESOLVE_HOOK: hook,
+				ENTWURF_REMOTE_PAIR_RESOLVE_LOG_DIR: logs,
+			},
+		},
+	);
+	const summary = (vitest.stdout.match(/Tests\s+.*$/m) ?? [""])[0].trim();
+	ok(
+		"[QK:RPI-ROUNDTRIP-ON-INSTALL] the T2 cells (A→B, reverse dispatch, opt-in absent off, other host refuses, both socket dirs) pass against the installed bridge and entry",
+		vitest.status === 0 && /^Tests\s+5 passed\b/.test(summary),
+		`${summary}\n${vitest.stdout
+			.split("\n")
+			.filter((l) => /×|FAIL|Error/.test(l))
+			.slice(0, 10)
+			.join("\n")}`,
+	);
+
+	// 5. Checkout invisibility of the subject processes.
+	const all = fs.readdirSync(logs).map((n) => path.join(logs, n));
+	const bridgeLogs = all.filter((f) => path.basename(f).startsWith("bridge-"));
+	const entryLogs = all.filter((f) => path.basename(f).startsWith("entry-"));
+	const subjectLogs = [...bridgeLogs, ...entryLogs, ...all.filter((f) => path.basename(f) === "installed-usage.log")];
+	ok(
+		"[QK:RPI-AUDIT-SAW-SUBJECTS] the resolve hook recorded the installed bridge processes and the installed entry processes",
+		bridgeLogs.some((f) => fs.statSync(f).size > 0) && entryLogs.some((f) => fs.statSync(f).size > 0),
+		`bridge logs=${bridgeLogs.length} entry logs=${entryLogs.length}`,
+	);
+	const audit = outside(subjectLogs, consumer);
+	ok(
+		`[QK:RPI-CHECKOUT-INVISIBLE] every module the installed subject processes resolved (${audit.total}) sits inside the consumer prefix`,
+		audit.total > 0 && audit.outside.length === 0,
+		audit.outside.slice(0, 10).join("\n        "),
+	);
+
+	// 6. Control: the audit sees a checkout when there is one.
+	const control = spawnSync(path.join(REPO, "run.sh"), ["remote-pair-receive"], {
+		encoding: "utf8",
+		env: { ...sandboxEnv(path.join(sandbox, "control-home")), ...hookEnv("control-checkout") },
+	});
+	const controlAudit = outside([path.join(logs, "control-checkout.log")], consumer);
+	const realRepo = fs.realpathSync(REPO);
+	ok(
+		"[QK:RPI-AUDIT-CONTROL] the same audit on this checkout's own entry reports checkout paths (the detector is live)",
+		control.status === 2 && controlAudit.outside.some((p) => p.startsWith(`${realRepo}${path.sep}`)),
+		`status=${control.status} outside=${controlAudit.outside.length}`,
+	);
+} catch (err) {
+	ok(`[${LABEL}] gate ran to completion`, false, err instanceof Error ? err.message : String(err));
+} finally {
+	// Synthetic fixture data only. Kept on failure so the resolve logs and npm output can be read.
+	if (failed === 0) fs.rmSync(sandbox, { recursive: true, force: true });
+	else console.log(`[${LABEL}] kept the sandbox for diagnosis: ${sandbox}`);
+}
+
+console.log(
+	`\n${LABEL}: ${passed} passed, ${failed} failed — installed artifact ${sha.slice(0, 12)}; no real ssh, no model`,
+);
+process.exit(failed === 0 ? 0 : 1);

package/scripts/lib/remote-pair-installed-audit.ts

@@ -0,0 +1,25 @@
+/**
+ * The acceptance primitive of `check-remote-pair-installed`'s checkout-invisibility cell (#107 rail 3),
+ * as a pure function over resolve-hook logs so it can be proven on tiny synthetic files
+ * (test/remote-pair-installed-audit.test.ts). Each log line is one URL a subject process resolved.
+ * A `file:` URL counts and is judged by its REAL path; anything else (node: builtins) is ignored.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Every file the logs name that is NOT inside `root` (both compared by real path), and how many file URLs were read. */
+export function filesOutsideRoot(logFiles: readonly string[], root: string): { total: number; outside: string[] } {
+	const realRoot = fs.realpathSync(root);
+	const out = new Set<string>();
+	let total = 0;
+	for (const f of logFiles) {
+		for (const url of fs.readFileSync(f, "utf8").split("\n").filter(Boolean)) {
+			if (!url.startsWith("file:")) continue;
+			total++;
+			const real = fs.realpathSync(fileURLToPath(url));
+			if (real !== realRoot && !real.startsWith(`${realRoot}${path.sep}`)) out.add(real);
+		}
+	}
+	return { total, outside: [...out].sort() };
+}

package/scripts/mutants/control-send-receipt.json

@@ -166,10 +166,10 @@
 			"title": "the pi queue oracle's public coordinate is dropped from `check:vitest`, so the file that proves every claim the receipt makes about a receiver's queues is green only when somebody runs `pnpm test` by hand — the discovery door deliberately does not select `test/**`, so nothing else would notice",
 			"subject": "package.json",
 			"find": [
-				"\"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\""
 			],
 			"replace": [
-				"\"check:vitest\": \"./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-tests-beside-behavior\""
+				"\"check:vitest\": \"./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-tests-beside-behavior && ./run.sh check-remote-pair-installed-audit\""
 			],
 			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
 			"timeoutSeconds": 600,

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

@@ -0,0 +1,53 @@
+{
+	"schemaVersion": 1,
+	"lane": "remote-pair-display",
+	"mutants": [
+		{
+			"claim": "REMOTE-DISPLAY-LOCAL-UNCHANGED",
+			"title": "the remote branch is taken for every non-replyable sender, so an ordinary external or meta-session header turns into a remote line naming a route that does not exist",
+			"subject": "pi-extensions/lib/meta-mailbox-body.ts",
+			"find": ["\tconst remote = !replyable ? sender.remote : undefined;"],
+			"replace": [
+				"\tconst remote = !replyable ? (sender.remote ?? { via: \"?\", replyRoute: \"none\" as const }) : undefined;"
+			],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-DISPLAY-LOCAL-UNCHANGED]",
+			"signatureSource": "pi-extensions/lib/meta-mailbox-body.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-DISPLAY-SESSIONLINE",
+			"title": "a remote sender with a declared route back is told to reply via entwurf_v2 as if that route had been probed",
+			"subject": "pi-extensions/lib/meta-mailbox-body.ts",
+			"find": ["\"reply route declared, not probed\""],
+			"replace": ["\"reply via entwurf_v2 to this sessionId\""],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-DISPLAY-SESSIONLINE]",
+			"signatureSource": "pi-extensions/lib/meta-mailbox-body.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-DISPLAY-SENDER-HOST-CWD",
+			"title": "a remote sender's cwd is abbreviated against this host's HOME, so a path on the other machine reads as a local one",
+			"subject": "pi-extensions/lib/meta-mailbox-body.ts",
+			"find": ["\tconst where = remote ? `${sender.cwd} (sender-host path)` : abbreviateHome(sender.cwd);"],
+			"replace": ["\tconst where = abbreviateHome(sender.cwd);"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-DISPLAY-SENDER-HOST-CWD]",
+			"signatureSource": "pi-extensions/lib/meta-mailbox-body.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		}
+	]
+}

package/scripts/mutants/remote-pair-installed-audit.json

@@ -0,0 +1,28 @@
+{
+	"schemaVersion": 1,
+	"lane": "remote-pair-installed-audit",
+	"mutants": [
+		{
+			"claim": "RPI-AUDIT-REAL-PATH",
+			"title": "the installed-closure audit judges a resolved file by its link path, so an installed file that is a symlink into a checkout passes as inside the consumer",
+			"subject": "scripts/lib/remote-pair-installed-audit.ts",
+			"find": ["\t\t\tconst real = fs.realpathSync(fileURLToPath(url));"],
+			"replace": ["\t\t\tconst real = fileURLToPath(url);"],
+			"gate": ["bash", "run.sh", "check-remote-pair-installed-audit"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:RPI-AUDIT-REAL-PATH]",
+			"signatureSource": "test/remote-pair-installed-audit.test.ts"
+		},
+		{
+			"claim": "RPI-AUDIT-ROOT-BOUNDARY",
+			"title": "the installed-closure audit treats any path that merely starts with the consumer prefix as inside it, so a sibling directory such as <prefix>-x passes",
+			"subject": "scripts/lib/remote-pair-installed-audit.ts",
+			"find": ["\t\t\tif (real !== realRoot && !real.startsWith(`${realRoot}${path.sep}`)) out.add(real);"],
+			"replace": ["\t\t\tif (real !== realRoot && !real.startsWith(realRoot)) out.add(real);"],
+			"gate": ["bash", "run.sh", "check-remote-pair-installed-audit"],
+			"timeoutSeconds": 120,
+			"signature": "[QK:RPI-AUDIT-ROOT-BOUNDARY]",
+			"signatureSource": "test/remote-pair-installed-audit.test.ts"
+		}
+	]
+}

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

@@ -0,0 +1,126 @@
+{
+	"schemaVersion": 1,
+	"lane": "remote-pair-receive",
+	"mutants": [
+		{
+			"claim": "REMOTE-PAIR-FROM-OUTSIDE-NO-MUTATION",
+			"title": "the receiving entry stops checking the claimed sender against the declared pair, so any gid the SSH account writes is dispatched into the declared target's mailbox",
+			"subject": "pi-extensions/lib/remote-pair-receive.ts",
+			"find": ["\tif (claim.from !== decl.remoteGardenId) {"],
+			"replace": ["\tif (false) {"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-FROM-OUTSIDE-NO-MUTATION]",
+			"signatureSource": "pi-extensions/lib/remote-pair-receive.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-PAIR-TARGET-OUTSIDE-NO-MUTATION",
+			"title": "the receiving entry stops checking the claimed target against the declared pair, so a declared remote can reach every deliverable citizen on this host",
+			"subject": "pi-extensions/lib/remote-pair-receive.ts",
+			"find": ["\tif (claim.target !== decl.localGardenId) {"],
+			"replace": ["\tif (false) {"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-TARGET-OUTSIDE-NO-MUTATION]",
+			"signatureSource": "pi-extensions/lib/remote-pair-receive.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-PAIR-IGNORES-AMBIENT-SENDER",
+			"title": "the receiving entry lets an ambient PI_SESSION_ID in the SSH environment stand in for the sender, so the header names whoever's carrier leaked instead of the claim",
+			"subject": "pi-extensions/lib/remote-pair-receive.ts",
+			"find": ["\t\tsessionId: claim.from,"],
+			"replace": ["\t\tsessionId: process.env.PI_SESSION_ID ?? claim.from,"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-IGNORES-AMBIENT-SENDER]",
+			"signatureSource": "pi-extensions/lib/remote-pair-receive.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-PAIR-MATCH-DISPATCHES-ONCE",
+			"title": "the receiving entry marks a remote sender replyable, so the body tells the receiver to reply via entwurf_v2 as if a live local reply route had been probed — none was",
+			"subject": "pi-extensions/lib/remote-pair-receive.ts",
+			"find": ["\t\treplyable: false,"],
+			"replace": ["\t\treplyable: true,"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-MATCH-DISPATCHES-ONCE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-receive.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-PAIR-CLAIM-EXACT-SHAPE",
+			"title": "the claim parser accepts extra or missing fields, so a sender-side field the receiver never reads can ride in and a partial claim is dispatched",
+			"subject": "pi-extensions/lib/remote-pair-receive.ts",
+			"find": ["\tif (got.length !== want.length || got.some((k, i) => k !== want[i])) {"],
+			"replace": ["\tif (false) {"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-CLAIM-EXACT-SHAPE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-receive.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-PAIR-ENTRY-REFUSES-OUTSIDE",
+			"title": "the entry reports a pair refusal as exit 0, so the sending host cannot tell a refused claim from a dispatched one without parsing prose",
+			"subject": "scripts/remote-pair-receive.ts",
+			"find": ["emit(receipt, receipt.kind === \"rejected\" ? 3 : receipt.isError ? 4 : 0);"],
+			"replace": ["emit(receipt, receipt.kind === \"rejected\" ? 0 : receipt.isError ? 4 : 0);"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-ENTRY-REFUSES-OUTSIDE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-receive.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-PAIR-ENTRY-USAGE",
+			"title": "the entry accepts any --pair it is given, so the sender picks which declaration scopes the claim on the receiving host",
+			"subject": "scripts/remote-pair-receive.ts",
+			"find": ["\tif (!path.isAbsolute(pairFile) || path.normalize(pairFile) !== own) {"],
+			"replace": ["\tif (false) {"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-ENTRY-USAGE]",
+			"signatureSource": "pi-extensions/lib/remote-pair-receive.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-PAIR-ENTRY-REPLY-ROUTE-DECLARED",
+			"title": "the entry reports no route back for a claim its own opt-in pairs with, so the receiver is told it cannot answer a sender it has declared",
+			"subject": "scripts/remote-pair-receive.ts",
+			"find": ["\treplyRoute: \"declared\","],
+			"replace": ["\treplyRoute: \"none\","],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-PAIR-ENTRY-REPLY-ROUTE-DECLARED]",
+			"signatureSource": "pi-extensions/lib/remote-pair-receive.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		}
+	]
+}

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

@@ -0,0 +1,83 @@
+{
+	"schemaVersion": 1,
+	"lane": "remote-pair-roundtrip",
+	"mutants": [
+		{
+			"claim": "REMOTE-ROUNDTRIP-A-TO-B",
+			"title": "the bridge never reads the opt-in, so a declared remote target falls through to the local decider as bad-target",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": ["\t\t\t\t\troute: readRemotePairOptIn(remotePairOptInPath()),"],
+			"replace": ["\t\t\t\t\troute: null,"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUNDTRIP-A-TO-B]",
+			"signatureSource": "pi-extensions/lib/remote-pair-roundtrip.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUNDTRIP-REVERSE-DISPATCH",
+			"title": "the bridge's transport never reaches the other host and always answers exit 1, so every declared remote send in either direction becomes indeterminate",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": ["\t\t\t\t\ttransport: processTransport,"],
+			"replace": [
+				"\t\t\t\t\ttransport: { run: async () => ({ exitCode: 1, signal: null, timedOut: false, stdout: \"\", stderr: \"\" }) },"
+			],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUNDTRIP-REVERSE-DISPATCH]",
+			"signatureSource": "pi-extensions/lib/remote-pair-roundtrip.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUNDTRIP-OPT-IN-ABSENT-OFF",
+			"title": "the bridge replaces the local surface on the remote path's behalf, so a host with no opt-in stops running the existing local decider",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": ["\t\t\t\t\trunLocal: (params, opts) => runAndRenderEntwurfV2FromSurface(params, opts),"],
+			"replace": ["\t\t\t\t\trunLocal: async () => ({ isError: false, text: \"local skipped\" }),"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUNDTRIP-OPT-IN-ABSENT-OFF]",
+			"signatureSource": "pi-extensions/lib/remote-pair-roundtrip.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUNDTRIP-OTHER-HOST-REFUSES",
+			"title": "the sender renders the other host's pair refusal without naming it, so A cannot tell B refused the pair from any other failure",
+			"subject": "pi-extensions/lib/remote-pair-send.ts",
+			"find": ["refused by the other host's pair: ${o.reason} (${o.detail})"],
+			"replace": ["failed"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUNDTRIP-OTHER-HOST-REFUSES]",
+			"signatureSource": "pi-extensions/lib/remote-pair-roundtrip.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		},
+		{
+			"claim": "REMOTE-ROUNDTRIP-LOCAL-TRACE-BOTH-SOCKET-DIRS",
+			"title": "the bridge checks only its own ENTWURF_DIR, so a live local socket in the decider's canonical dir is bypassed and the gid is sent away",
+			"subject": "mcp/entwurf-bridge/src/index.ts",
+			"find": ["\t\t\t\t\t\tcontrolSocketDirs: [CONTROL_SOCKET_DIR, ENTWURF_DIR],"],
+			"replace": ["\t\t\t\t\t\tcontrolSocketDirs: [ENTWURF_DIR],"],
+			"gate": ["bash", "run.sh", "check-tests-beside-behavior"],
+			"timeoutSeconds": 600,
+			"signature": "[QK:REMOTE-ROUNDTRIP-LOCAL-TRACE-BOTH-SOCKET-DIRS]",
+			"signatureSource": "pi-extensions/lib/remote-pair-roundtrip.test.ts",
+			"build": {
+				"argv": ["bash", "scripts/build-bridge.sh"],
+				"output": "mcp/entwurf-bridge/dist"
+			}
+		}
+	]
+}