@junghanacs/entwurf 0.13.0 → 0.14.0

package/scripts/check-mux-launch-tmux.ts

@@ -0,0 +1,316 @@
+/**
+ * check-mux-launch-tmux — REAL tmux acceptance for the T1-a visible launch.
+ *
+ * `check-mux-launch` pins preconditions, argv and the import boundary; here the production
+ * `launchPi` runs against an actual tmux server and the assertions read the server's own
+ * `list-windows`/`list-panes`. Same isolation contract as the T0-b acceptance: a private `-S`
+ * socket under $XDG_RUNTIME_DIR, the operator's server snapshotted read-only before and after
+ * and required to be byte-identical, and `TMUX`/`TMUX_PANE` INHERITED from a fixture pane's
+ * own `/proc/<pid>/environ` rather than assembled.
+ *
+ * The runtime under test is a FIXTURE script, not the operator's real `pi`. T1-a's claim is
+ * "the window opens in the right place and the named runtime is what starts in it" — a claim a
+ * long-lived stand-in proves exactly, without an interactive agent, a model call, or a session
+ * record. `resolvePiRuntime` (which finds the official `pi` on PATH) is proven by the
+ * deterministic gate; here PATH is pointed at the fixture so this gate judges topology.
+ *
+ * Proven here:
+ *   - the window lands at {end} of the caller's OWN session; one session throughout
+ *   - the launched process is the runtime itself — no shell wrapper survives in the pane
+ *   - pane_pid is that process, and it is alive
+ *   - focus never moves, and the original windows and their pane pids survive
+ *   - the handle is bound to the context it was born in
+ *   - THE TRAP: a failed exec still exits 0, still prints a well-formed handle, and its window
+ *     is still listed on an immediate re-read — which is why no post-launch presence check is
+ *     performed and why the precondition runs before the window exists
+ *   - a precondition refusal opens NO window at all
+ */
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { buildLaunchArgs, LaunchPreconditionError, launchPi } from "../pi-extensions/lib/mux-launch.ts";
+import { inspectPlacement } from "../pi-extensions/lib/mux-placement.ts";
+import { skipLive } from "./lib/live-skip.ts";
+
+const LABEL = "check-mux-launch-tmux";
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const SOCKET = path.join(process.env.XDG_RUNTIME_DIR ?? "/run/user/1000", `entwurf-mux-t1a-${process.pid}.sock`);
+const SESSION = `muxt1a${process.pid}`;
+
+function fx(...args: string[]): { status: number | null; stdout: string; stderr: string } {
+	const env = { ...process.env };
+	delete env.TMUX;
+	delete env.TMUX_PANE;
+	const r = spawnSync("tmux", ["-S", SOCKET, ...args], { env, encoding: "utf8" });
+	if (r.error) throw r.error;
+	return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+function fxLines(...args: string[]): string[] {
+	const r = fx(...args);
+	assert.equal(r.status, 0, `fixture tmux ${args.join(" ")} failed: ${r.stderr}`);
+	return r.stdout
+		.split("\n")
+		.map((l) => l.trim())
+		.filter((l) => l.length > 0);
+}
+
+function windows(): string[] {
+	return fxLines("list-windows", "-a", "-F", "#{window_id}|#{window_index}|#{window_active}");
+}
+
+function panes(): string[] {
+	return fxLines("list-panes", "-a", "-F", "#{window_id}|#{pane_id}|#{pane_pid}");
+}
+
+function sessionCount(): number {
+	return fxLines("list-sessions", "-F", "#{session_id}").length;
+}
+
+function windowPresent(windowId: string): boolean {
+	return fxLines("list-windows", "-a", "-F", "#{window_id}").includes(windowId);
+}
+
+/** Read-only snapshot of the CALLER'S OWN server — the ambient TMUX is kept deliberately. */
+function operatorSnapshot(): string | null {
+	const r = spawnSync("tmux", ["list-panes", "-a", "-F", "#{session_id}|#{window_id}|#{pane_id}|#{pane_pid}"], {
+		env: process.env,
+		encoding: "utf8",
+	});
+	return r.status === 0 ? (r.stdout ?? "") : null;
+}
+
+function alive(pid: string): boolean {
+	try {
+		process.kill(Number(pid), 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function main(): void {
+	if (spawnSync("tmux", ["-V"], { encoding: "utf8" }).status !== 0) {
+		skipLive(LABEL, "tmux is not installed — install tmux to run the launch acceptance");
+	}
+	if (!fs.existsSync("/proc")) {
+		skipLive(LABEL, "/proc is unavailable — the inherited-anchor read is Linux-only");
+	}
+	if (!process.env.TMUX || !process.env.TMUX_PANE) {
+		skipLive(LABEL, "run this acceptance from INSIDE tmux — the isolation proof snapshots the caller's own server");
+	}
+	if (fs.existsSync(SOCKET)) {
+		throw new Error(`${LABEL}: fixture socket ${SOCKET} already exists — refusing to reuse a foreign server`);
+	}
+
+	const before = operatorSnapshot();
+	const runtimeDir = fs.mkdtempSync(path.join(process.env.XDG_RUNTIME_DIR ?? "/tmp", "entwurf-mux-rt-"));
+	// A long-lived stand-in for the official runtime. `exec` so no shell survives: the pane's
+	// process must be the runtime itself for the pane_pid claim to mean anything.
+	const runtime = path.join(runtimeDir, "pi");
+	fs.writeFileSync(runtime, "#!/bin/sh\nexec sleep 900\n", { mode: 0o755 });
+
+	try {
+		assert.equal(fx("-f", "/dev/null", "new-session", "-d", "-s", SESSION).status, 0, "fixture new-session");
+		fx("set-option", "-g", "base-index", "1");
+		fx("set-option", "-gw", "pane-base-index", "1");
+		fx("set-option", "-g", "renumber-windows", "on");
+		assert.equal(fx("move-window", "-s", `${SESSION}:0`, "-t", `${SESSION}:1`).status, 0, "fixture move-window");
+		assert.equal(fx("new-window", "-d", "-a", "-t", `${SESSION}:{end}`).status, 0, "fixture second window");
+
+		const w0 = windows();
+		ok("fixture: exactly one session", sessionCount() === 1);
+		ok(`fixture: windows are 1,2 (${w0.join(" ")})`, w0.length === 2);
+
+		// ── the anchor is INHERITED, not assembled ─────────────────────────────────────
+		const callerPanePid = fxLines("display-message", "-p", "-t", `${SESSION}:1`, "#{pane_pid}")[0];
+		const environ = fs.readFileSync(`/proc/${callerPanePid}/environ`, "utf8").split("\0");
+		const inherited: NodeJS.ProcessEnv = { ...process.env };
+		delete inherited.TMUX;
+		delete inherited.TMUX_PANE;
+		for (const entry of environ) {
+			const eq = entry.indexOf("=");
+			if (eq < 0) continue;
+			const key = entry.slice(0, eq);
+			if (key === "TMUX" || key === "TMUX_PANE") inherited[key] = entry.slice(eq + 1);
+		}
+		// The fixture runtime dir is PREPENDED, never substituted: the same env spawns tmux
+		// itself, so replacing PATH outright would take tmux away from the production code and
+		// this gate would be measuring a broken harness instead of a launch. Prepending also
+		// makes the stand-in win over any real `pi` further down the operator's PATH.
+		inherited.PATH = `${runtimeDir}${path.delimiter}${process.env.PATH ?? ""}`;
+		ok("anchor: the fixture pane really inherited TMUX/TMUX_PANE", Boolean(inherited.TMUX && inherited.TMUX_PANE));
+		ok("anchor: TMUX names the fixture socket, not the operator's", String(inherited.TMUX).startsWith(SOCKET));
+
+		const got = inspectPlacement(inherited);
+		assert.ok(got.ok, "inspectPlacement must resolve inside the fixture");
+		const placement = got.placement;
+		const fixtureServerPid = fxLines("display-message", "-p", "#{pid}")[0];
+		const originalPanes = panes();
+		const activeBefore = windows().find((w) => w.endsWith("|1"));
+
+		// ── a precondition refusal opens NO window ─────────────────────────────────────
+		// The whole reason preconditions run first: a caller who cannot start the runtime must
+		// not be left with a window to clean up.
+		{
+			// A PATH that still finds tmux but has no `pi` anywhere: drop every entry holding an
+			// executable `pi` rather than emptying PATH, so the refusal under test is the
+			// runtime's absence and not a broken harness.
+			const noPiEntries = (process.env.PATH ?? "")
+				.split(path.delimiter)
+				.filter((d) => d.length > 0 && path.isAbsolute(d))
+				.filter((d) => {
+					try {
+						fs.accessSync(path.join(d, "pi"), fs.constants.X_OK);
+						return false;
+					} catch {
+						return true;
+					}
+				});
+			const noRuntime = { ...inherited, PATH: noPiEntries.join(path.delimiter) };
+			assert.equal(
+				spawnSync("tmux", ["-V"], { env: noRuntime, encoding: "utf8" }).status,
+				0,
+				"the no-pi PATH must still find tmux, or this would test the harness",
+			);
+			let reason: string | null = null;
+			try {
+				launchPi(placement, noRuntime);
+			} catch (err) {
+				reason = err instanceof LaunchPreconditionError ? err.reason : null;
+			}
+			ok("refusal: an unresolvable runtime refuses as runtime-unresolved", reason === "runtime-unresolved");
+			ok("refusal: and NO window was opened by the refused launch", windows().length === 2);
+		}
+
+		// ── the launch ────────────────────────────────────────────────────────────────
+		const launch = launchPi(placement, inherited);
+		ok(`launch: 1,2,3 (${windows().join(" ")})`, windows().length === 3);
+		ok("launch: landed at the END (index 3)", launch.windowIndex === "3");
+		ok("launch: still exactly one session — a window, never a new session", sessionCount() === 1);
+		ok("launch: stable handles", launch.windowId.startsWith("@") && launch.paneId.startsWith("%"));
+		ok(
+			"launch: focus unchanged — visible means a real window, not stolen focus",
+			windows().find((w) => w.endsWith("|1")) === activeBefore,
+		);
+		ok(
+			"launch: original windows and their pane pids untouched",
+			originalPanes.every((p) => panes().includes(p)),
+		);
+		ok("launch: the receipt names the runtime it handed tmux", launch.runtimePath === runtime);
+		ok(
+			"launch: the handle carries the context it was born in",
+			launch.serverPid === fixtureServerPid && launch.sessionId === placement.sessionId,
+		);
+
+		// ── the launched process IS the runtime — no shell wrapper ─────────────────────
+		// Measured with `--`: tmux execs the target directly. If a shell survived in the pane,
+		// pane_pid would be the wrapper and every later fact about "the runtime" would be about
+		// the wrong process.
+		const deadline = Date.now() + 5000;
+		let cmdline = "";
+		while (Date.now() < deadline) {
+			try {
+				cmdline = fs.readFileSync(`/proc/${launch.panePid}/cmdline`, "utf8").split("\0").filter(Boolean).join(" ");
+			} catch {
+				cmdline = "";
+			}
+			if (cmdline.includes("sleep")) break;
+			spawnSync("sleep", ["0.05"]);
+		}
+		ok(`launch: pane_pid is the runtime's own process, no shell wrapper (${cmdline})`, cmdline.includes("sleep 900"));
+		ok("launch: that process is alive", alive(launch.panePid));
+		ok(
+			"launch: tmux agrees the pane belongs to the launched window",
+			panes().some((p) => p.startsWith(`${launch.windowId}|${launch.paneId}|${launch.panePid}`)),
+		);
+
+		// ── THE TRAP: a failed exec is indistinguishable at launch time ────────────────
+		// This is the measured reason `launchPi` performs no post-launch presence check. The
+		// gate asserts the trap directly so the honesty of the receipt is a pinned fact rather
+		// than a claim in a comment.
+		{
+			const bogus = path.join(runtimeDir, "nope-not-here");
+			const args = [
+				"new-window",
+				"-d",
+				"-a",
+				"-t",
+				`${placement.sessionId}:{end}`,
+				"-P",
+				"-F",
+				"#{window_id}",
+				"--",
+				bogus,
+			];
+			const r = spawnSync("tmux", args, { env: inherited, encoding: "utf8" });
+			const printed = (r.stdout ?? "").trim();
+			ok(
+				"trap: a failed exec still exits 0 and still prints a well-formed handle",
+				r.status === 0 && /^@[0-9]+$/.test(printed),
+			);
+			ok(
+				"trap: and that window is STILL LISTED on an immediate re-read — no synchronous check can tell it from a good launch",
+				windowPresent(printed),
+			);
+			const gone = Date.now() + 5000;
+			while (windowPresent(printed) && Date.now() < gone) spawnSync("sleep", ["0.05"]);
+			ok("trap: it disappears milliseconds later, through the same remain-on-exit path", !windowPresent(printed));
+		}
+
+		// ── binding: a foreign context is refused before mutating ─────────────────────
+		assert.throws(
+			() => launchPi({ ...placement, serverPid: "999999" }, inherited),
+			/context changed/,
+			"launchPi must refuse a placement from another server",
+		);
+		assert.throws(
+			() => launchPi({ ...placement, sessionId: "$999" }, inherited),
+			/context changed/,
+			"launchPi must refuse a placement from another session",
+		);
+		ok("binding: launch refuses a foreign server or session before opening anything", windows().length === 3);
+
+		// ── the argv the production builder emits is what actually ran ────────────────
+		ok(
+			"argv: the builder's shape is the one this acceptance exercised",
+			buildLaunchArgs(placement.sessionId, runtime).slice(-2).join(" ") === `-- ${runtime}`,
+		);
+
+		// ── cleanup by the operator's own hand ────────────────────────────────────────
+		process.kill(Number(launch.panePid), "SIGKILL");
+		const end = Date.now() + 5000;
+		while (windowPresent(launch.windowId) && Date.now() < end) spawnSync("sleep", ["0.05"]);
+		ok("teardown: killing the runtime removes its window (remain-on-exit off)", !windowPresent(launch.windowId));
+		const w5 = windows();
+		ok(`restored: windows are 1,2 (${w5.join(" ")})`, w5.length === 2);
+		ok("restored: exactly one session", sessionCount() === 1);
+		ok(
+			"restored: the original pane pids are the SAME processes",
+			originalPanes.every((p) => panes().includes(p)),
+		);
+		ok("restored: focus never moved", windows().find((w) => w.endsWith("|1")) === activeBefore);
+	} finally {
+		fx("kill-server");
+		if (fs.existsSync(SOCKET)) fs.rmSync(SOCKET, { force: true });
+		fs.rmSync(runtimeDir, { recursive: true, force: true });
+	}
+
+	ok("cleanup: the fixture socket is gone", !fs.existsSync(SOCKET));
+	ok("cleanup: the fixture server is unreachable", fx("list-sessions").status !== 0);
+
+	const after = operatorSnapshot();
+	ok("isolation: the operator's server is byte-identical before and after", before === after);
+
+	console.log(`\n${LABEL}: ${passed} checks passed`);
+}
+
+main();

package/scripts/check-mux-launch.ts

@@ -0,0 +1,288 @@
+/**
+ * check-mux-launch — deterministic gate for the T1-a visible launch
+ * (`pi-extensions/lib/mux-launch.ts`).
+ *
+ * Same scope discipline as `check-mux-placement`: this gate pins only what is decidable
+ * without tmux — the preconditions, the resolution rule, the argv shape, and the import
+ * boundary. The topology and the "a failed exec still prints a handle" trap are judged
+ * against a real private tmux server by `./run.sh check-mux-launch-tmux`, which drives THIS
+ * production code. There is still no fake tmux in this repo.
+ *
+ * The precondition assertions use a real temporary directory rather than a stubbed `fs`: the
+ * claim is about the filesystem answers (missing / directory / non-executable), and a stub
+ * would be asserting against a second implementation of `statSync` instead of the one the
+ * production path calls.
+ *
+ *   MUX-LAUNCH-PRECONDITION-FIRST  the runtime is proven launchable BEFORE any window opens
+ *   MUX-LAUNCH-PATH-NO-SPLIT       a whitespace-bearing runtime path is refused (tmux re-splits it)
+ *   MUX-LAUNCH-PATH-HIT-NOT-SKIPPED  that refusal is NOT a PATH skip — a later entry never takes over
+ *   MUX-LAUNCH-NO-SHELL-ARGV       the fixed runtime is passed after `--`, never as a string
+ *   MUX-LAUNCH-NO-CARRIER          argv is the append shape plus the runtime, nothing else
+ *   MUX-LAUNCH-CORE-IMPORT-FREE    the launch module and entwurf delivery never import each other
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+	assertLaunchTarget,
+	buildLaunchArgs,
+	LaunchPreconditionError,
+	type LaunchRejectReason,
+	PI_RUNTIME_COMMAND,
+	resolvePiRuntime,
+} from "../pi-extensions/lib/mux-launch.ts";
+import { APPEND_FORMAT } from "../pi-extensions/lib/mux-placement.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+/** Run `f` and report the LaunchRejectReason it refused with, or null if it did not refuse. */
+function refusalOf(f: () => unknown): LaunchRejectReason | null {
+	try {
+		f();
+		return null;
+	} catch (err) {
+		return err instanceof LaunchPreconditionError ? err.reason : null;
+	}
+}
+
+const SESSION = "$11";
+
+function main(): void {
+	const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "entwurf-mux-launch-"));
+	try {
+		const good = path.join(tmp, "pi");
+		fs.writeFileSync(good, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+		const notExec = path.join(tmp, "pi-noexec");
+		fs.writeFileSync(notExec, "#!/bin/sh\nexit 0\n", { mode: 0o644 });
+		const dir = path.join(tmp, "pi-dir");
+		fs.mkdirSync(dir);
+		const spaced = path.join(tmp, "a b");
+		fs.mkdirSync(spaced);
+		const spacedPi = path.join(spaced, "pi");
+		fs.writeFileSync(spacedPi, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+
+		// ── the runtime is proven BEFORE a window can exist ──────────────────────────────
+		// Measured on tmux 3.6a: `new-window -- /nonexistent/bin/nope` exits 0, prints a
+		// well-formed handle, and the window is still listed on an immediate re-read (10/10).
+		// So there is no post-launch check that can tell a failed exec from a good one — the
+		// only honest place to catch it is before the window exists.
+		ok(
+			"[QK:MUX-LAUNCH-PRECONDITION-FIRST] every unlaunchable runtime is refused with a NAMED reason before tmux is invoked — relative, missing, directory, and non-executable each refuse as themselves",
+			refusalOf(() => assertLaunchTarget("pi")) === "runtime-not-absolute" &&
+				refusalOf(() => assertLaunchTarget("./bin/pi")) === "runtime-not-absolute" &&
+				refusalOf(() => assertLaunchTarget(path.join(tmp, "nope"))) === "runtime-missing" &&
+				refusalOf(() => assertLaunchTarget(dir)) === "runtime-not-regular-file" &&
+				refusalOf(() => assertLaunchTarget(notExec)) === "runtime-not-executable",
+		);
+		ok("precondition: a real absolute executable passes", refusalOf(() => assertLaunchTarget(good)) === null);
+
+		// tmux re-splits a single argv element on whitespace (measured, 3.6a): a runtime at
+		// `/tmp/a b/pi` is launched as `/tmp/a` with `b/pi` as an argument. `--` prevents the
+		// shell, not the re-split, so this is its own invariant and not a tidier spelling of
+		// the checks above.
+		ok(
+			"[QK:MUX-LAUNCH-PATH-NO-SPLIT] a runtime path containing ANY whitespace is refused — tmux would re-split it into a truncated binary plus an argument — and the refusal precedes the filesystem questions, whose answers would be about the wrong file",
+			refusalOf(() => assertLaunchTarget(spacedPi)) === "runtime-path-whitespace" &&
+				refusalOf(() => assertLaunchTarget(path.join(tmp, "no such dir", "pi"))) === "runtime-path-whitespace" &&
+				refusalOf(() => assertLaunchTarget(`${tmp}/p\ti`)) === "runtime-path-whitespace" &&
+				refusalOf(() => assertLaunchTarget(`${tmp}/p\ni`)) === "runtime-path-whitespace",
+		);
+		ok(
+			"precondition: the refusal is a typed LaunchPreconditionError carrying the reason, not a bare Error",
+			(() => {
+				try {
+					assertLaunchTarget("pi");
+					return false;
+				} catch (err) {
+					return err instanceof LaunchPreconditionError && err.name === "LaunchPreconditionError";
+				}
+			})(),
+		);
+
+		// ── resolution: PATH, absolute, and never the cwd ────────────────────────────────
+		ok(
+			"resolve: the official runtime is found on PATH and returned as an absolute path",
+			resolvePiRuntime({ PATH: tmp }) === good,
+		);
+		ok(
+			"resolve: an empty PATH entry is skipped, never searched as cwd",
+			resolvePiRuntime({ PATH: `${path.delimiter}${tmp}` }) === good,
+		);
+		ok(
+			"resolve: a relative PATH entry is skipped — where the caller stood must not decide which binary launches",
+			resolvePiRuntime({ PATH: `.${path.delimiter}${tmp}` }) === good,
+		);
+		ok(
+			"resolve: a non-executable candidate does not shadow a later executable one",
+			(() => {
+				const shadow = fs.mkdtempSync(path.join(os.tmpdir(), "entwurf-mux-shadow-"));
+				try {
+					fs.writeFileSync(path.join(shadow, PI_RUNTIME_COMMAND), "x", { mode: 0o644 });
+					return resolvePiRuntime({ PATH: `${shadow}${path.delimiter}${tmp}` }) === good;
+				} finally {
+					fs.rmSync(shadow, { recursive: true, force: true });
+				}
+			})(),
+		);
+		// The refuse/skip split is a contract, not an accident of where the assertion sits. A
+		// candidate the shell ITSELF would skip (present but not executable) is skipped; a
+		// candidate the shell WOULD have picked (executable, but its path holds whitespace) is
+		// REFUSED. Falling through to a later PATH entry there would silently start a DIFFERENT
+		// install than the one the operator gets by typing `pi` — the drift this rail refuses —
+		// so which of the two a failure gets is pinned on its own claim. Moving
+		// `assertLaunchTarget` inside the loop's catch is exactly the refactor that flips it.
+		ok(
+			"[QK:MUX-LAUNCH-PATH-HIT-NOT-SKIPPED] a whitespace-bearing FIRST executable hit is REFUSED, never skipped to a later entry — the shell would have picked that one, so falling through would launch a different install than `pi` does",
+			refusalOf(() => resolvePiRuntime({ PATH: `${spaced}${path.delimiter}${tmp}` })) === "runtime-path-whitespace",
+		);
+		ok(
+			"resolve: no runtime anywhere on PATH refuses as runtime-unresolved, and a missing PATH is the same refusal",
+			refusalOf(() => resolvePiRuntime({ PATH: path.join(tmp, "empty") })) === "runtime-unresolved" &&
+				refusalOf(() => resolvePiRuntime({})) === "runtime-unresolved",
+		);
+		ok("resolve: the runtime name is the fixed official one", PI_RUNTIME_COMMAND === "pi");
+
+		// ── argv shape: the append shape plus the runtime, after `--` ────────────────────
+		// `--` is what keeps tmux from handing the target to a shell (measured: an argument of
+		// `x; touch <file>` created no file). It does NOT stop tmux re-splitting a spaced
+		// element, which is why the whitespace precondition above is separate and not cosmetic.
+		const args = buildLaunchArgs(SESSION, good);
+		ok(
+			"[QK:MUX-LAUNCH-NO-SHELL-ARGV] the fixed runtime is the LAST argv element and is preceded by `--`, so tmux execs it directly instead of running it through a shell",
+			args[args.length - 2] === "--" && args[args.length - 1] === good,
+		);
+		ok(
+			"[QK:MUX-LAUNCH-NO-CARRIER] launch argv is exactly the detached append shape plus the runtime — no -n/-c/-e/-b, no caller command, cwd, env or window name",
+			args.join(" ") === `new-window -d -a -t ${SESSION}:{end} -P -F ${APPEND_FORMAT} -- ${good}` &&
+				!["-n", "-c", "-e", "-b"].some((f) => args.includes(f)) &&
+				args.length === 10,
+		);
+		ok(
+			"argv: `-d` is kept — visible means a real window in the operator's session, not stolen focus",
+			args.includes("-d"),
+		);
+		ok(
+			"argv: the window is appended at {end} of the caller's own session, addressed by session id",
+			args.includes("-a") && args.includes(`${SESSION}:{end}`),
+		);
+		ok(
+			"argv: the printed handle format is the same stable @window/%pane row the leaf uses",
+			args.includes("-P") && args.includes(APPEND_FORMAT),
+		);
+		ok(
+			"argv: a non-native session selector is refused before tmux runs, exactly as the leaf refuses it",
+			["$1; kill-server", "#{session_id}", "11", "@1", ""].every((s) => {
+				try {
+					buildLaunchArgs(s, good);
+					return false;
+				} catch {
+					return true;
+				}
+			}),
+		);
+		ok(
+			"argv: an unlaunchable runtime is refused by the builder too — the argv path cannot skip the precondition",
+			refusalOf(() => buildLaunchArgs(SESSION, dir)) === "runtime-not-regular-file" &&
+				refusalOf(() => buildLaunchArgs(SESSION, spacedPi)) === "runtime-path-whitespace",
+		);
+
+		// ── the import boundary (docs/mux-launch-rail.md §11) ───────────────────────────
+		// A new module is exactly when a forbidden line drifts, so it is asserted on source
+		// rather than trusted. Launch composition must not be reachable from the delivery
+		// core, and the launch module must not reach back into it.
+		//
+		// The docs' claim is NOT "these four files do not import it" — it is that NO production
+		// source imports it at all. An enumerated list proves the narrower thing and goes stale
+		// the moment a fifth delivery module is written, so the shipped source is WALKED. The
+		// corpus is asserted below to be the real one, because a scan is only as strong as what
+		// it covers: narrowing it later is how a generalized oracle turns into a false green.
+		const LAUNCH_MODULE = "pi-extensions/lib/mux-launch.ts";
+		const LAUNCH_SRC = fs.readFileSync(LAUNCH_MODULE, "utf8");
+
+		/** Module specifiers only — static `from "x"` and dynamic `import("x")`. A comment or a
+		 * doc reference that merely NAMES a module is not an import, and the leaf's header now
+		 * names the launch composition on purpose (see its export-seam note). */
+		function importsOf(src: string): string[] {
+			return [...src.matchAll(/(?:\bfrom|\bimport)\s*\(?\s*"([^"]+)"/g)].map((m) => m[1]);
+		}
+		const importsLaunch = (file: string): boolean =>
+			importsOf(fs.readFileSync(file, "utf8")).some((spec) => spec.includes("mux-launch"));
+
+		/** Every `.ts` under a shipped source root. `dist/` is a compiled copy of `src/` (a build
+		 * artifact, not authored source — scanning it would double-count and drift), and
+		 * `node_modules` is not ours. */
+		function walkTs(root: string): string[] {
+			const out: string[] = [];
+			for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+				const child = `${root}/${entry.name}`;
+				if (entry.isDirectory()) {
+					if (entry.name === "node_modules" || entry.name === "dist") continue;
+					out.push(...walkTs(child));
+				} else if (entry.isFile() && child.endsWith(".ts")) {
+					out.push(child);
+				}
+			}
+			return out;
+		}
+		const DELIVERY_MODULES = [
+			"pi-extensions/lib/entwurf-v2-contract.ts",
+			"pi-extensions/lib/entwurf-v2-decider.ts",
+			"pi-extensions/lib/entwurf-v2-runner.ts",
+			"pi-extensions/lib/entwurf-v2-production.ts",
+		];
+		const PRODUCTION_SOURCES = [...walkTs("pi-extensions"), ...walkTs("mcp")].filter((f) => f !== LAUNCH_MODULE);
+		/** The allowed importers. T1-a shipped with none at all; the fresh-call composition was the
+		 * first, and S1's resume-call composition is the second. Both are allowed BECAUSE they are
+		 * the layer above — they reuse the launch preconditions rather than copying them, while
+		 * delivery stays as far away as it ever was. The set is exact, not a prefix rule: "any
+		 * mux-* file may import launch" would let a future module in without a decision. */
+		const FRESH_CALL_MODULE = "pi-extensions/lib/mux-fresh-call.ts";
+		const RESUME_CALL_MODULE = "pi-extensions/lib/mux-resume-call.ts";
+		const ALLOWED_LAUNCH_IMPORTERS = [FRESH_CALL_MODULE, RESUME_CALL_MODULE];
+		ok(
+			"corpus: the scanned corpus IS the shipped source — both roots, every delivery module and the bridge entrypoint present by name, no build artifacts, and the launch module itself the only exclusion",
+			PRODUCTION_SOURCES.length >= 40 &&
+				DELIVERY_MODULES.every((m) => PRODUCTION_SOURCES.includes(m)) &&
+				PRODUCTION_SOURCES.includes("pi-extensions/lib/mux-placement.ts") &&
+				PRODUCTION_SOURCES.includes("pi-extensions/entwurf-control.ts") &&
+				PRODUCTION_SOURCES.includes("mcp/entwurf-bridge/src/index.ts") &&
+				!PRODUCTION_SOURCES.includes(LAUNCH_MODULE) &&
+				PRODUCTION_SOURCES.every((f) => !f.includes("node_modules") && !f.includes("/dist/")),
+		);
+		ok(
+			"[QK:MUX-LAUNCH-CORE-IMPORT-FREE] launch is not a delivery or core dependency: the ONLY shipped files that may import mux-launch are the two compositions above it — fresh-call and resume-call — not the four delivery modules, not anything else, and mux-launch still imports no entwurf core",
+			PRODUCTION_SOURCES.filter((m) => !ALLOWED_LAUNCH_IMPORTERS.includes(m)).every((m) => !importsLaunch(m)) &&
+				ALLOWED_LAUNCH_IMPORTERS.every((m) => importsLaunch(m)) &&
+				!/from\s+"\.\/(entwurf|meta)-[^"]*"/.test(LAUNCH_SRC),
+		);
+		ok(
+			"boundary: mux-launch imports only node builtins and the placement leaf",
+			importsOf(LAUNCH_SRC).every((spec) => spec.startsWith("node:") || spec === "./mux-placement.ts"),
+		);
+		ok(
+			"boundary: the placement leaf does not import the launch module — the leaf stays deletable on its own",
+			!importsLaunch("pi-extensions/lib/mux-placement.ts"),
+		);
+		// Prose is not behaviour: the module header names identity vocabulary precisely to say
+		// it owns none of it, so this assertion reads CODE with the comments stripped. A check
+		// that failed on its own documentation would push the boundary out of the docs.
+		const LAUNCH_CODE = LAUNCH_SRC.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+		ok(
+			"boundary: the launch leaf stays identity-free — no code here reads a record store, a garden id, or a session-id carrier",
+			!/gardenId|nativeSessionId|session-id|meta-session|entwurf_v2/.test(LAUNCH_CODE),
+		);
+
+		console.log(`\ncheck-mux-launch: ${passed} checks passed`);
+	} finally {
+		fs.rmSync(tmp, { recursive: true, force: true });
+	}
+}
+
+main();