@junghanacs/entwurf 0.13.0 → 0.14.0

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

@@ -0,0 +1,322 @@
+/**
+ * check-mux-placement-tmux — REAL tmux acceptance for the T0-b placement primitives.
+ *
+ * This is the half that judges topology. `check-mux-placement` pins argv and parsing; here
+ * the production functions in `pi-extensions/lib/mux-placement.ts` run against an actual
+ * tmux server and the assertions read the server's own `list-sessions`/`list-windows`/
+ * `list-panes` output. No fake tmux exists in this repo — a fake would have authored the
+ * contract before it was measured, which is how the 2026-08-02 attempt shipped the wrong
+ * unit (a separate session instead of a window).
+ *
+ * Isolation, non-negotiable: the fixture builds its OWN server on a unique `-S` socket under
+ * $XDG_RUNTIME_DIR and never touches the operator's server. (`-L` would place the socket in
+ * the same directory as the default server; `-S` with an explicit path keeps them apart. The
+ * path lives in the runtime dir rather than a deep scratch dir because a unix socket path is
+ * capped near 104 bytes.) The operator's server is snapshotted read-only before and after and
+ * the two snapshots must be identical.
+ *
+ * Honesty of the anchor: the production code must receive `TMUX`/`TMUX_PANE` the way a real
+ * caller does — INHERITED by a process living inside a pane. The fixture therefore reads
+ * those values out of the fixture pane's own process environment (`/proc/<pane_pid>/environ`)
+ * instead of assembling them. That is Linux-only, and the check skips elsewhere rather than
+ * inventing the values it is supposed to be proving.
+ *
+ * Proven here:
+ *   - one session throughout; 1,2 → 1,2,3 → 1,2,3,4 → 1,2
+ *   - original windows, their pane pids, and the caller's focus all survive
+ *   - handles are stable @window/%pane
+ *   - the rc=0 trap is real, and inspectPlacement refuses it instead of guessing
+ *   - close reports `closed` for a live window and `already-gone` after a natural exit
+ */
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { appendWindow, closeWindow, inspectPlacement } from "../pi-extensions/lib/mux-placement.ts";
+import { skipLive } from "./lib/live-skip.ts";
+
+const LABEL = "check-mux-placement-tmux";
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+// ── fixture server (never the operator's) ──────────────────────────────────
+
+const SOCKET = path.join(process.env.XDG_RUNTIME_DIR ?? "/run/user/1000", `entwurf-mux-t0b-${process.pid}.sock`);
+const SESSION = `muxt0b${process.pid}`;
+
+/** Fixture tmux: always explicit `-S`, always with the ambient TMUX stripped so an ambient
+ * server can never be resolved by accident. */
+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;
+}
+
+/**
+ * Read-only snapshot of the CALLER'S OWN server — the one this gate must prove it never
+ * touched. The ambient `TMUX` is kept deliberately: scrubbing it would snapshot the DEFAULT
+ * server instead, which is not necessarily the operator's, and the isolation claim would be
+ * about the wrong machine. (Only the FIXTURE calls scrub the environment.)
+ */
+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 main(): void {
+	if (spawnSync("tmux", ["-V"], { encoding: "utf8" }).status !== 0) {
+		skipLive(LABEL, "tmux is not installed — install tmux to run the placement acceptance");
+	}
+	if (!fs.existsSync("/proc")) {
+		skipLive(LABEL, "/proc is unavailable — the inherited-anchor read is Linux-only");
+	}
+	// The isolation proof is about the caller's OWN server, so this gate must be run from
+	// inside tmux. Without that it would be snapshotting something else and calling it proof.
+	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();
+
+	try {
+		// ── fixture: a session whose windows are 1 and 2, like the operator's ───────────
+		// `-f /dev/null` keeps the operator's tmux.conf out of the FIXTURE (this is a
+		// controlled substrate, not a display), and base-index is then set explicitly rather
+		// than inherited or assumed. base-index does not apply retroactively, so window 0 is
+		// moved. No `-n`: this module authors no window names anywhere.
+		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");
+		// renumber-windows on mirrors the operator's shipped setting — the acceptance must run
+		// under the same index churn the production code has to survive.
+		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 && w0[0].includes("|1|") && w0[1].includes("|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);
+		}
+		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));
+
+		// ── the rc=0 trap is real, and production refuses it ───────────────────────────
+		const bogus = spawnSync("tmux", ["display-message", "-p", "-t", "%999999", "#{pane_id}"], {
+			env: inherited,
+			encoding: "utf8",
+		});
+		ok(
+			"trap: display-message on a nonexistent pane exits 0 with empty output (rc is not evidence)",
+			bogus.status === 0 && (bogus.stdout ?? "").trim() === "",
+		);
+		const empty = spawnSync("tmux", ["display-message", "-p", "-t", "", "#{pane_id}"], {
+			env: inherited,
+			encoding: "utf8",
+		});
+		ok(
+			"trap: an EMPTY target exits 0 and answers about some other pane",
+			empty.status === 0 && (empty.stdout ?? "").trim().startsWith("%"),
+		);
+
+		{
+			const outside = { ...inherited };
+			delete outside.TMUX;
+			delete outside.TMUX_PANE;
+			const r = inspectPlacement(outside);
+			ok(
+				"reject: outside tmux → no-tmux-context (no fallback session)",
+				r.ok === false && r.reason === "no-tmux-context",
+			);
+		}
+		{
+			const r = inspectPlacement({ ...inherited, TMUX_PANE: "" });
+			ok(
+				"reject: empty TMUX_PANE → no-tmux-context (never the rc=0 fallback pane)",
+				r.ok === false && r.reason === "no-tmux-context",
+			);
+		}
+		{
+			// The dangerous one: a pane id with NO TMUX would make a bare tmux resolve to the
+			// DEFAULT server — i.e. mutate the operator's live server with a foreign id.
+			const noServer = { ...inherited };
+			delete noServer.TMUX;
+			const r = inspectPlacement(noServer);
+			ok(
+				"reject: TMUX_PANE without TMUX → no-tmux-context (never falls through to the default server)",
+				r.ok === false && r.reason === "no-tmux-context",
+			);
+		}
+		{
+			const r = inspectPlacement({ ...inherited, TMUX_PANE: "%1; kill-server" });
+			ok(
+				"reject: a non-native TMUX_PANE → anchor-malformed, refused before tmux is invoked",
+				r.ok === false && r.reason === "anchor-malformed",
+			);
+		}
+		{
+			const r = inspectPlacement({ ...inherited, TMUX_PANE: "%999999" });
+			ok(
+				"reject: a stale pane id → anchor-unresolved despite rc=0",
+				r.ok === false && r.reason === "anchor-unresolved",
+			);
+		}
+
+		// ── inspectPlacement: the caller's own coordinates ─────────────────────────────
+		const fixtureServerPid = fxLines("display-message", "-p", "#{pid}")[0];
+		const fixtureSessionId = fxLines("display-message", "-p", "-t", `${SESSION}:1`, "#{session_id}")[0];
+		const got = inspectPlacement(inherited);
+		assert.ok(got.ok, "inspectPlacement must resolve inside the fixture");
+		const placement = got.placement;
+		ok("inspect: server pid is the FIXTURE server, not the operator's", placement.serverPid === fixtureServerPid);
+		ok("inspect: session id matches the fixture session", placement.sessionId === fixtureSessionId);
+		ok("inspect: pane id echoes the inherited anchor", placement.paneId === inherited.TMUX_PANE);
+		ok("inspect: pane pid matches tmux's own view", placement.panePid === callerPanePid);
+		ok(
+			"inspect: window index is the human 1, id is @-stable",
+			placement.windowIndex === "1" && placement.windowId.startsWith("@"),
+		);
+
+		const originalPanes = panes();
+		const activeBefore = windows().find((w) => w.endsWith("|1"));
+
+		// ── appendWindow ×2 ───────────────────────────────────────────────────────────
+		const w3 = appendWindow(placement, inherited);
+		ok(`append#1: 1,2,3 (${windows().join(" ")})`, windows().length === 3);
+		ok("append#1: stable handles", w3.windowId.startsWith("@") && w3.paneId.startsWith("%"));
+		ok("append#1: landed at the END (index 3)", w3.windowIndex === "3");
+		ok("append#1: still exactly one session", sessionCount() === 1);
+		ok("append#1: focus unchanged", windows().find((w) => w.endsWith("|1")) === activeBefore);
+
+		const w4 = appendWindow(placement, inherited);
+		ok(`append#2: 1,2,3,4 (${windows().join(" ")})`, windows().length === 4);
+		ok("append#2: landed at the END (index 4)", w4.windowIndex === "4");
+		ok("append#2: a distinct window", w4.windowId !== w3.windowId && w4.paneId !== w3.paneId);
+		ok("append#2: still exactly one session", sessionCount() === 1);
+		ok("append#2: focus unchanged", windows().find((w) => w.endsWith("|1")) === activeBefore);
+		ok(
+			"append: original windows and their pane pids untouched",
+			originalPanes.every((p) => panes().includes(p)),
+		);
+
+		// ── the handle is bound to the context it was born in ─────────────────────────
+		// A `$N`/`@N` on a DIFFERENT (or restarted) server names something else entirely, so
+		// both mutations re-read the caller's placement and refuse on a mismatch — before
+		// touching anything.
+		assert.throws(
+			() => appendWindow({ ...placement, serverPid: "999999" }, inherited),
+			/context changed/,
+			"appendWindow must refuse a placement from another server",
+		);
+		assert.throws(
+			() => appendWindow({ ...placement, sessionId: "$999" }, inherited),
+			/context changed/,
+			"appendWindow must refuse a placement from another session",
+		);
+		assert.throws(
+			() => closeWindow({ ...w4, serverPid: "999999" }, inherited),
+			/context changed/,
+			"closeWindow must refuse a handle from another server",
+		);
+		ok("binding: append/close refuse a foreign server or session before mutating", windows().length === 4);
+		ok(
+			"binding: the handle carries the server pid and session id it was born in",
+			w4.serverPid === fixtureServerPid && w4.sessionId === fixtureSessionId,
+		);
+
+		// ── closeWindow on a LIVE window → closed ─────────────────────────────────────
+		ok("close: a live window reports closed", closeWindow(w4, inherited) === "closed");
+		ok(`close: back to 1,2,3 (${windows().join(" ")})`, windows().length === 3);
+		ok(
+			"close: the closed window id is gone",
+			!windows().some((w) => w.startsWith(`${w3.windowId === w4.windowId ? "" : w4.windowId}|`)),
+		);
+
+		// ── natural exit → the window vanishes on its own → already-gone ──────────────
+		// remain-on-exit is off, so ending the pane process removes the window through a path
+		// this module never called. An interactive shell ignores SIGTERM; SIGHUP is what ends
+		// it (measured in T0-a), so the fixture uses HUP rather than pretending TERM worked.
+		process.kill(Number(w3.panePid), "SIGHUP");
+		const deadline = Date.now() + 5000;
+		while (windows().some((w) => w.startsWith(`${w3.windowId}|`)) && Date.now() < deadline) {
+			spawnSync("sleep", ["0.1"]);
+		}
+		ok(
+			"natural exit: the window disappeared without closeWindow",
+			!windows().some((w) => w.startsWith(`${w3.windowId}|`)),
+		);
+		ok(
+			"close: an already-vanished window reports already-gone, not a silent success",
+			closeWindow(w3, inherited) === "already-gone",
+		);
+
+		// ── restored ─────────────────────────────────────────────────────────────────
+		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 });
+	}
+
+	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-placement.ts

@@ -0,0 +1,323 @@
+/**
+ * check-mux-placement — deterministic gate for the T0-b placement primitives
+ * (`pi-extensions/lib/mux-placement.ts`).
+ *
+ * Scope discipline: this gate pins ONLY what is decidable without tmux — the context
+ * precondition, the selector grammar, the argv shapes, the parse, the run-status
+ * classification, and the close classification. It does not simulate tmux. There is no fake
+ * tmux anywhere in this repo, on purpose: a fake would have written the contract before the
+ * real thing was measured, which is exactly how the first mux attempt (2026-08-02) shipped
+ * the wrong unit. The topology facts — one session throughout, 1,2 → 1,2,3 → 1,2,3,4 → 1,2,
+ * surviving pids, unchanged focus, and the context-binding refusals — are judged by
+ * `./run.sh check-mux-placement-tmux`, which drives THIS production code against a real
+ * private tmux server.
+ *
+ * Each claim carries its QK token on exactly ONE assertion (the mutant signature must be
+ * unique in this file), and that assertion states the whole invariant. The assertions around
+ * it explain the invariant without re-emitting the token.
+ *
+ *   MUX-ANCHOR-REQUIRED      both TMUX and TMUX_PANE are required before anything runs
+ *   MUX-SELECTOR-NATIVE-ID   every -t selector is a native id, validated before tmux runs
+ *   MUX-ANCHOR-ECHO-BACK     tmux's rc=0 is not evidence; the pane id must echo back
+ *   MUX-TMUX-FAILURE-LOUD    a nonzero/signalled tmux run is raised, never read as a fact
+ *   MUX-APPEND-END-DETACHED  append is `-d -a -t <session_id>:{end}`, no carrier
+ *   MUX-CONTEXT-BOUND-MUTATION a mutation matches the server pid AND the session id
+ *   MUX-CLOSE-BY-WINDOW-ID   close targets `@window`, and absence needs positive proof
+ */
+
+import assert from "node:assert/strict";
+import {
+	APPEND_FORMAT,
+	assertTmuxOk,
+	buildAppendArgs,
+	buildCloseArgs,
+	buildInspectArgs,
+	buildListWindowIdsArgs,
+	classifyCloseFailure,
+	INSPECT_FORMAT,
+	isDecimal,
+	isPaneId,
+	isSameContext,
+	isSessionId,
+	isWindowId,
+	parsePlacement,
+	parseWindowFields,
+	readAnchor,
+} 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++;
+}
+
+const SERVER = "/tmp/tmux-1000/default,8150,11";
+const ANCHOR = "%14";
+const ROW = ["8150", "$11", "@14", "2", "%14", "74235"].join("|");
+
+/**
+ * Every environment that is NOT a usable tmux context. `TMUX_PANE` alone is the dangerous
+ * one: a bare `tmux` with no `TMUX` in the environment resolves to the DEFAULT server, so a
+ * stale pane id would have been applied to the operator's live server.
+ */
+const NOT_A_CONTEXT: NodeJS.ProcessEnv[] = [
+	{},
+	{ TMUX_PANE: ANCHOR },
+	{ TMUX_PANE: ANCHOR, TMUX: "" },
+	{ TMUX: SERVER },
+	{ TMUX: SERVER, TMUX_PANE: "" },
+];
+
+/** Selectors that must never reach tmux's parser. */
+const HOSTILE_SELECTORS = ["%1; kill-server", "@1 ; kill-server", "$1;", "#{pane_id}", "#(id)", "1", "%", "", "%1\n"];
+
+function main(): void {
+	// ── the caller must be inside tmux, with BOTH variables ──────────────────────────
+	ok(
+		"[QK:MUX-ANCHOR-REQUIRED] a usable anchor needs BOTH a non-empty TMUX and a non-empty TMUX_PANE — TMUX_PANE alone would let a bare tmux resolve to the DEFAULT server",
+		NOT_A_CONTEXT.every((env) => {
+			const r = readAnchor(env);
+			return r.ok === false && r.reason === "no-tmux-context";
+		}),
+	);
+	ok(
+		"anchor: with both present, TMUX_PANE is the anchor verbatim and TMUX is never parsed",
+		(() => {
+			const r = readAnchor({ TMUX: SERVER, TMUX_PANE: ANCHOR });
+			return r.ok === true && r.anchor === ANCHOR;
+		})(),
+	);
+	ok(
+		"anchor: a present-but-malformed TMUX_PANE is anchor-malformed, not a context problem",
+		(() => {
+			const r = readAnchor({ TMUX: SERVER, TMUX_PANE: "%1; kill-server" });
+			return r.ok === false && r.reason === "anchor-malformed";
+		})(),
+	);
+
+	// ── selectors are native ids, checked BEFORE tmux runs ───────────────────────────
+	// T0-a measured that tmux reinterprets values it is handed (a trailing `;` can split a
+	// command, `#{…}`/`#(…)` expand), so "we passed argv, not a shell string" is not on its
+	// own a safety argument. The grammar is the argument.
+	ok(
+		"[QK:MUX-SELECTOR-NATIVE-ID] every builder refuses a non-native selector BEFORE invoking tmux — no `;`, no `#{}`/`#()`, no bare index, no newline",
+		HOSTILE_SELECTORS.every((s) => {
+			let refusedInspect = false;
+			let refusedAppend = false;
+			let refusedClose = false;
+			try {
+				buildInspectArgs(s);
+			} catch {
+				refusedInspect = true;
+			}
+			try {
+				buildAppendArgs(s);
+			} catch {
+				refusedAppend = true;
+			}
+			try {
+				buildCloseArgs(s);
+			} catch {
+				refusedClose = true;
+			}
+			return refusedInspect && refusedAppend && refusedClose;
+		}),
+	);
+	ok(
+		"grammar: %N / $N / @N / decimal are the entire accepted vocabulary",
+		isPaneId("%14") &&
+			!isPaneId("@14") &&
+			isSessionId("$11") &&
+			!isSessionId("11") &&
+			isWindowId("@14") &&
+			!isWindowId("%14") &&
+			isDecimal("74235") &&
+			!isDecimal("7 4"),
+	);
+	ok(
+		"grammar: each builder accepts only its OWN id kind",
+		(() => {
+			const wrongKind = [() => buildInspectArgs("$11"), () => buildAppendArgs("@14"), () => buildCloseArgs("%14")];
+			return wrongKind.every((f) => {
+				try {
+					f();
+					return false;
+				} catch {
+					return true;
+				}
+			});
+		})(),
+	);
+
+	// ── rc=0 is not evidence ─────────────────────────────────────────────────────────
+	// Measured against real tmux 3.6a: `display-message` on a nonexistent pane exits 0, and
+	// an EMPTY target exits 0 while answering about the CURRENT pane. Worse, a nonexistent
+	// target still fills the SERVER field and leaves the rest empty — so the row is non-empty
+	// and would pass a naive "did we get output?" test.
+	ok(
+		"[QK:MUX-ANCHOR-ECHO-BACK] a row whose pane_id is not the anchor is never accepted: empty, server-only, short, malformed-field and other-pane rows all refuse",
+		(() => {
+			const cases: Array<[string, string]> = [
+				[ANCHOR, ""],
+				[ANCHOR, "8150|||||"],
+				[ANCHOR, "8150|$11|@14"],
+				[ANCHOR, `8150|nope|@14|2|${ANCHOR}|74235`],
+				["%13", ROW],
+			];
+			return cases.every(([anchor, stdout]) => parsePlacement(anchor, stdout).ok === false);
+		})(),
+	);
+	ok(
+		"echo-back: an unresolvable row is `anchor-unresolved`, a foreign row is `anchor-mismatch`",
+		(() => {
+			const unresolved = parsePlacement(ANCHOR, "8150|||||");
+			const mismatch = parsePlacement("%13", ROW);
+			return (
+				unresolved.ok === false &&
+				unresolved.reason === "anchor-unresolved" &&
+				mismatch.ok === false &&
+				mismatch.reason === "anchor-mismatch"
+			);
+		})(),
+	);
+	ok(
+		"echo-back: an exact match yields the native facts",
+		(() => {
+			const r = parsePlacement(ANCHOR, `${ROW}\n`);
+			return (
+				r.ok === true &&
+				r.placement.serverPid === "8150" &&
+				r.placement.sessionId === "$11" &&
+				r.placement.windowId === "@14" &&
+				r.placement.paneId === ANCHOR &&
+				r.placement.panePid === "74235"
+			);
+		})(),
+	);
+	ok(
+		"echo-back: the machine row carries native ids only — no free-form name or path that a `|` could split",
+		!INSPECT_FORMAT.includes("session_name") &&
+			!INSPECT_FORMAT.includes("socket_path") &&
+			INSPECT_FORMAT.includes("#{pane_id}") &&
+			INSPECT_FORMAT.includes("#{session_id}"),
+	);
+	ok(
+		"echo-back: the query is anchored on the caller's pane",
+		buildInspectArgs(ANCHOR).join(" ") === `display-message -p -t ${ANCHOR} ${INSPECT_FORMAT}`,
+	);
+
+	// ── a failed tmux call is a failure, not a fact ───────────────────────────────────
+	// rc=0 not being proof of existence does NOT make a nonzero exit ignorable. "no server
+	// running", EACCES and a usage error must surface as themselves — reading them as
+	// "the anchor did not resolve" would report a missing pane when tmux never answered.
+	ok(
+		"[QK:MUX-TMUX-FAILURE-LOUD] a nonzero exit and a signal kill both raise, carrying status and stderr; only rc=0 is allowed through to be parsed",
+		(() => {
+			let nonzero = false;
+			let signalled = false;
+			try {
+				assertTmuxOk("display-message", { status: 1, stdout: "", stderr: "no server running on /tmp/x" });
+			} catch (err) {
+				nonzero = err instanceof Error && err.message.includes("exit 1") && err.message.includes("no server running");
+			}
+			try {
+				assertTmuxOk("kill-window", { status: null, stdout: "", stderr: "" });
+			} catch (err) {
+				signalled = err instanceof Error && err.message.includes("terminated by signal");
+			}
+			let passedThrough = true;
+			try {
+				assertTmuxOk("display-message", { status: 0, stdout: ROW, stderr: "" });
+			} catch {
+				passedThrough = false;
+			}
+			return nonzero && signalled && passedThrough;
+		})(),
+	);
+
+	// ── a handle belongs to one server AND one session ───────────────────────────────
+	// A restarted tmux server hands out `$0` again, and one server holds many sessions. So a
+	// mutation must match BOTH halves before it runs; either half alone would let an env
+	// naming a different (or restarted) server redirect the operation to a same-named id the
+	// caller never looked at. The wiring — re-reading the placement before every mutation —
+	// is proven against real tmux by check-mux-placement-tmux.
+	ok(
+		"[QK:MUX-CONTEXT-BOUND-MUTATION] a context matches only when the server pid AND the session id both match — either half alone accepts a foreign server or a foreign session",
+		(() => {
+			const origin = { serverPid: "8150", sessionId: "$11" };
+			return (
+				isSameContext(origin, { serverPid: "8150", sessionId: "$11" }) &&
+				!isSameContext(origin, { serverPid: "9999", sessionId: "$11" }) &&
+				!isSameContext(origin, { serverPid: "8150", sessionId: "$12" }) &&
+				!isSameContext(origin, { serverPid: "9999", sessionId: "$12" })
+			);
+		})(),
+	);
+	ok(
+		"binding: a window handle carries the context it was born in",
+		(() => {
+			const h = { serverPid: "8150", sessionId: "$11", windowId: "@2", windowIndex: "3", paneId: "%2", panePid: "1" };
+			return isSameContext(h, { serverPid: h.serverPid, sessionId: h.sessionId });
+		})(),
+	);
+
+	// ── append shape ─────────────────────────────────────────────────────────────────
+	// `-a … :{end}` is append; a bare `new-window` takes the lowest FREE index, which is a
+	// different verb and not this contract. The carrier stays shut: a caller-supplied
+	// command, cwd, window name, or label would hand tmux's own parser a value we did not
+	// author.
+	const appendArgs = buildAppendArgs("$11");
+	ok(
+		"[QK:MUX-APPEND-END-DETACHED] append is exactly `new-window -d -a -t <session_id>:{end} -P -F <handle format>` — detached, at the end, by session id, with no carrier",
+		appendArgs.join(" ") === `new-window -d -a -t $11:{end} -P -F ${APPEND_FORMAT}`,
+	);
+	ok(
+		"append: no -n/-c/-e/-b carrier and no shell-command positional (default shell only)",
+		!["-n", "-c", "-e", "-b"].some((f) => appendArgs.includes(f)) &&
+			appendArgs.length === 8 &&
+			appendArgs[appendArgs.length - 1] === APPEND_FORMAT,
+	);
+	ok(
+		"append: the printed handle is @window/%pane, not an index alone",
+		APPEND_FORMAT.includes("#{window_id}") && APPEND_FORMAT.includes("#{pane_id}"),
+	);
+	ok(
+		"append: the reported handle parses to stable ids",
+		(() => {
+			const h = parseWindowFields("@2|3|%2|76957\n");
+			return h.windowId === "@2" && h.paneId === "%2" && h.windowIndex === "3" && h.panePid === "76957";
+		})(),
+	);
+	assert.throws(() => parseWindowFields(""), /did not report a window handle/, "a silent new-window must fail loud");
+	assert.throws(
+		() => parseWindowFields("w2|3|%2|76957"),
+		/non-native handle/,
+		"a non-native handle must fail loud rather than be carried",
+	);
+	ok("append: a handle-less or non-native new-window report fails loud", true);
+
+	// ── close shape + absence needs proof ────────────────────────────────────────────
+	// remain-on-exit off (measured in T0-a): a runtime's own exit can remove the window
+	// first. That is a race, not an error — but `already-gone` is only honest when the
+	// window is provably NOT in the inventory.
+	ok(
+		"[QK:MUX-CLOSE-BY-WINDOW-ID] close targets the stable @window and `already-gone` requires positive absence — a still-listed window yields no outcome at all",
+		buildCloseArgs("@3").join(" ") === "kill-window -t @3" &&
+			classifyCloseFailure("@3", "@0\n@1\n") === "already-gone" &&
+			classifyCloseFailure("@3", "@0\n@1\n@3\n") === null,
+	);
+	ok(
+		"close: the absence proof lists window ids server-wide",
+		buildListWindowIdsArgs().join(" ") === "list-windows -a -F #{window_id}",
+	);
+	ok("close: an empty inventory is still positive absence", classifyCloseFailure("@3", "") === "already-gone");
+	ok(
+		"close: a prefix is not the handle — @30 present does not prove @3 absent, and does prove @30 present",
+		classifyCloseFailure("@3", "@30\n") === "already-gone" && classifyCloseFailure("@30", "@30\n") === null,
+	);
+
+	console.log(`\ncheck-mux-placement: ${passed} checks passed`);
+}
+
+main();