@junghanacs/entwurf 0.13.0 → 0.14.0

package/pi-extensions/lib/mux-launch.ts

@@ -0,0 +1,267 @@
+/**
+ * mux-launch — T1-a: open ONE visible window in the caller's own tmux session and start the
+ * fixed official `pi` in it. Nothing after that.
+ *
+ * This is deliberately a SECOND module rather than a fourth verb on `mux-placement`. The
+ * placement leaf owns place and only place (`docs/mux-launch-rail.md` §11): a command
+ * parameter there would be the carrier that leaf refuses to have, and the deterministic gate
+ * pins `appendWindow`'s argv as exactly the no-carrier shape. So the composition lives here,
+ * on top of the leaf's grammar, binding and failure discipline, and the leaf stays deletable.
+ *
+ * The import lines this module must never cross (docs §11, asserted by check-mux-launch):
+ *
+ *   entwurf-v2 contract/decider/runner/production  -X-> mux-launch
+ *   mux-launch                                     -X-> entwurf core
+ *
+ * T1-a is launch, NOT delegation. This module does not wait for a garden identity, does not
+ * read the meta-record store, does not send a task, and has no idea what `entwurf_v2` is.
+ * The separate fresh-call composition reuses its precondition helpers but owns first-turn
+ * framing and callback correlation itself — see `docs/mux-launch-rail.md` §6-a and §11.
+ *
+ * ── What the receipt means, and what it deliberately does NOT ──
+ *
+ * A `PiLaunch` states two things: the ids tmux reported when it created the window, and the
+ * absolute runtime path we handed it. It does NOT claim pi is running.
+ *
+ * That restraint is measured, not modest. `new-window … -- /nonexistent/bin/nope` exits 0,
+ * prints a perfectly well-formed handle, and the window is STILL LISTED on an immediate
+ * re-read — 10/10 trials on tmux 3.6a, indistinguishable from a good launch at that instant.
+ * The window dies milliseconds later, through the same `remain-on-exit off` path
+ * `CloseOutcome.already-gone` already describes. So a post-launch presence check would prove
+ * nothing while making the receipt LOOK verified, which is worse than not checking: it is the
+ * rc=0 trap of T0-a wearing a different hat. This module refuses to perform one.
+ *
+ * What can honestly be done is to delete the failure class BEFORE a window exists, and that
+ * is what `assertLaunchTarget` does — the same precondition discipline
+ * `scripts/lib/probe-cli-target.ts` applies to the ACP CLI target: absolute, present, regular
+ * file, executable. A refusal is a NAMED reason on an unopened window, never a fallback.
+ *
+ * ── Cleanup, and why the contract is thin by construction ──
+ *
+ * There is exactly ONE mutation in this module: a single `new-window`. Everything after it is
+ * pure parsing. That is the cleanup design — not a compensating transaction, but a shape with
+ * almost nothing to compensate. The one residue: if tmux reports a handle this module cannot
+ * parse, the window exists and its id is precisely the thing we failed to read, so there is no
+ * honest target to close. That case fails loud and NAMES the orphan rather than killing a
+ * window picked by inventory diffing, which is the guess this rail forbids everywhere else.
+ *
+ * ── The whitespace precondition is not hygiene ──
+ *
+ * Measured on tmux 3.6a: a single argv element containing a space is RE-SPLIT by tmux, so a
+ * runtime at `/tmp/x y/pi` is launched as `/tmp/x` with the argument `y/pi` and the window
+ * dies instantly. `--` stops tmux from running the target through a shell (verified: an
+ * argument of `x; touch <file>` created no file), but it does not stop that re-split. So the
+ * path is checked for whitespace before it is handed over.
+ */
+
+import { accessSync, constants as fsConstants, statSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+import {
+	APPEND_FORMAT,
+	assertSelector,
+	assertTmuxOk,
+	type Placement,
+	parseWindowFields,
+	requireSameContext,
+	runTmux,
+	type WindowHandle,
+} from "./mux-placement.ts";
+
+/** The official runtime this rail opens. FIXED: there is no command carrier, and adding one
+ * is a separate ownership decision (docs §11), not a parameter. */
+export const PI_RUNTIME_COMMAND = "pi";
+
+/**
+ * Why a launch was refused BEFORE any window was opened. Each is a named refusal, never a
+ * fallback — a caller that cannot start the official runtime must not be handed a window.
+ *
+ *   `runtime-unresolved`        no `PI_RUNTIME_COMMAND` on PATH (or no usable PATH)
+ *   `runtime-not-absolute`      a relative target would resolve against the pane's cwd
+ *   `runtime-path-whitespace`   tmux re-splits a spaced argv element (measured)
+ *   `runtime-missing`           nothing at that path
+ *   `runtime-not-regular-file`  a directory/special file cannot be the runtime
+ *   `runtime-not-executable`    exec would fail after the window already existed
+ */
+export type LaunchRejectReason =
+	| "runtime-unresolved"
+	| "runtime-not-absolute"
+	| "runtime-path-whitespace"
+	| "runtime-missing"
+	| "runtime-not-regular-file"
+	| "runtime-not-executable";
+
+/** A named precondition failure. Callers surface `reason`; they never soften it into a
+ * fallback launch of something else. */
+export class LaunchPreconditionError extends Error {
+	readonly reason: LaunchRejectReason;
+	constructor(reason: LaunchRejectReason, message: string) {
+		super(message);
+		this.name = "LaunchPreconditionError";
+		this.reason = reason;
+	}
+}
+
+/** Any ASCII or Unicode whitespace — the tmux re-split hazard is about the space character,
+ * but a tab or newline in an argv element is no more launchable and no less a surprise. */
+const WHITESPACE = /\s/;
+
+/**
+ * The five preconditions, in the order a failure would otherwise bite. Absolute first
+ * (everything after it is meaningless for a relative path), whitespace before the filesystem
+ * questions (a re-split path's stat is about the wrong file), then present → regular →
+ * executable, exactly as `probe-cli-target.ts` orders them.
+ */
+export function assertLaunchTarget(runtimePath: string): void {
+	if (!isAbsolute(runtimePath)) {
+		throw new LaunchPreconditionError(
+			"runtime-not-absolute",
+			`mux-launch: runtime target ${JSON.stringify(runtimePath)} is not absolute — tmux would resolve it against ` +
+				"the new pane's cwd, so which binary started would depend on where the window happened to open",
+		);
+	}
+	if (WHITESPACE.test(runtimePath)) {
+		throw new LaunchPreconditionError(
+			"runtime-path-whitespace",
+			`mux-launch: runtime target ${JSON.stringify(runtimePath)} contains whitespace — tmux RE-SPLITS a single ` +
+				"argv element on spaces (measured, 3.6a), so this would launch a truncated path with the remainder as " +
+				"an argument and the window would die instantly",
+		);
+	}
+	let stat: ReturnType<typeof statSync>;
+	try {
+		stat = statSync(runtimePath);
+	} catch {
+		throw new LaunchPreconditionError(
+			"runtime-missing",
+			`mux-launch: runtime target ${runtimePath} does not exist — refusing before a window is opened onto a ` +
+				"runtime that cannot start",
+		);
+	}
+	if (!stat.isFile()) {
+		throw new LaunchPreconditionError(
+			"runtime-not-regular-file",
+			`mux-launch: runtime target ${runtimePath} is not a regular file — a directory or special file cannot be ` +
+				"the official runtime",
+		);
+	}
+	try {
+		accessSync(runtimePath, fsConstants.X_OK);
+	} catch {
+		throw new LaunchPreconditionError(
+			"runtime-not-executable",
+			`mux-launch: runtime target ${runtimePath} is not executable (X_OK) — exec would fail after the window ` +
+				"already existed, which is exactly the state this precondition exists to prevent",
+		);
+	}
+}
+
+/**
+ * Find the official runtime on the caller's PATH and prove it launchable.
+ *
+ * PATH rather than a compiled-in location because the official `pi` is whatever the operator's
+ * environment resolves — pinning a path here would silently launch a different install than
+ * the one the operator gets by typing `pi`. Resolving it to an ABSOLUTE path (rather than
+ * handing tmux the bare word) is what makes the preconditions mean anything: a bare `pi`
+ * would be re-resolved inside the pane, after the window exists, against an environment this
+ * module never checked.
+ *
+ * Empty PATH entries are skipped rather than treated as cwd — the historical POSIX reading of
+ * `::` is a cwd search, and a launch that depends on where the caller stood is the drift this
+ * rail refuses.
+ */
+export function resolveRuntimeOnPath(command: string, env: NodeJS.ProcessEnv = process.env): string {
+	const raw = env.PATH;
+	const entries = typeof raw === "string" ? raw.split(delimiter).filter((p) => p.length > 0) : [];
+	for (const dir of entries) {
+		if (!isAbsolute(dir)) continue;
+		const candidate = join(dir, command);
+		try {
+			if (!statSync(candidate).isFile()) continue;
+			accessSync(candidate, fsConstants.X_OK);
+		} catch {
+			continue;
+		}
+		assertLaunchTarget(candidate);
+		return candidate;
+	}
+	throw new LaunchPreconditionError(
+		"runtime-unresolved",
+		`mux-launch: no executable ${JSON.stringify(command)} on PATH — refusing to open a window for a ` +
+			"runtime that is not installed",
+	);
+}
+
+/**
+ * T1-a's own resolution: the fixed official `pi`. Kept as a named function rather than a call
+ * site with a constant because the launch contract is "this rail opens `pi`", and a caller that
+ * could pass a command would be the carrier this module refuses to have (docs §11). The
+ * generic form above exists only so a SEPARATE composition can apply the SAME preconditions to
+ * its own fixed runtime — not so this one becomes parameterised.
+ */
+export function resolvePiRuntime(env: NodeJS.ProcessEnv = process.env): string {
+	return resolveRuntimeOnPath(PI_RUNTIME_COMMAND, env);
+}
+
+/**
+ * The launch argv. Identical to the leaf's append shape — detached, appended at `{end}`,
+ * addressed by session id, printing the same handle format — with exactly one addition: the
+ * fixed runtime after `--`.
+ *
+ * `-d` is kept. "Visible" in T1-a means the window is a real window in the operator's own
+ * session rather than a headless child; it does not mean stealing the caller's focus. Moving
+ * focus is a different verb with a different owner, and the leaf's acceptance already pins
+ * "focus unchanged" as a property worth having.
+ *
+ * `--` is what stops tmux from handing the target to a shell (measured: an argument of
+ * `x; touch <file>` created no file). The selector and the runtime are both validated before
+ * this returns, so nothing unvalidated ever reaches tmux's parser.
+ */
+export function buildLaunchArgs(sessionId: string, runtimePath: string): string[] {
+	assertSelector("session", sessionId);
+	assertLaunchTarget(runtimePath);
+	return ["new-window", "-d", "-a", "-t", `${sessionId}:{end}`, "-P", "-F", APPEND_FORMAT, "--", runtimePath];
+}
+
+/**
+ * What T1-a returns: the window handle tmux reported, plus the runtime path that was handed
+ * to it. `panePid` is the launched process itself — measured: with `--`, tmux execs the target
+ * directly and no shell wrapper survives in the pane.
+ *
+ * Read `runtimePath` as "what we asked tmux to start", not "what is running". See the module
+ * header: no synchronous check can tell those apart, so this type does not pretend to.
+ */
+export interface PiLaunch extends WindowHandle {
+	runtimePath: string;
+}
+
+/**
+ * Open one window in the caller's own session and start the fixed official `pi` in it.
+ *
+ * Order matters and is the whole safety argument: resolve and prove the runtime FIRST, then
+ * re-read the caller's placement and refuse a changed context (the leaf's binding), and only
+ * then mutate. A precondition failure therefore never leaves a window behind, because no
+ * window has been opened yet.
+ *
+ * Responsibility ends at the returned ids. No identity, no delivery, no supervision.
+ */
+export function launchPi(placement: Placement, env: NodeJS.ProcessEnv = process.env): PiLaunch {
+	const runtimePath = resolvePiRuntime(env);
+	requireSameContext("launchPi", placement, env);
+	const run = runTmux(buildLaunchArgs(placement.sessionId, runtimePath), env);
+	assertTmuxOk("new-window", run);
+	let fields: ReturnType<typeof parseWindowFields>;
+	try {
+		fields = parseWindowFields(run.stdout);
+	} catch (err) {
+		// The window exists and its id is exactly what we failed to read. Diffing the inventory
+		// to find "the new one" is the guess this rail forbids, so name the orphan instead of
+		// killing a window chosen by inference.
+		throw new Error(
+			`mux-launch: launched ${runtimePath} but could not read the window handle tmux printed — a window may be ` +
+				`open in session ${placement.sessionId} that this call cannot identify or close: ${
+					err instanceof Error ? err.message : String(err)
+				}`,
+		);
+	}
+	return { serverPid: placement.serverPid, sessionId: placement.sessionId, ...fields, runtimePath };
+}

package/pi-extensions/lib/mux-placement.ts

@@ -0,0 +1,387 @@
+/**
+ * mux-placement — where a new sibling runtime is OPENED, and nothing else.
+ *
+ * The operating contract (2026-08-04, GLG): a caller that asks entwurf to open a new
+ * runtime is ALWAYS inside tmux. Outside tmux there is no fallback session, no
+ * `new-session`, no guess — the request is refused. The window is appended to exactly the
+ * server/session the caller's own inherited `TMUX`/`TMUX_PANE` names, because that is the
+ * session the operator is looking at. Inheriting the environment IS the addressing: this
+ * module never takes a socket path or a session name from a caller.
+ *
+ * Three actions, deliberately not four:
+ *
+ *   inspectPlacement()   the caller's own $session/@window/%pane, or a named refusal
+ *   appendWindow()       one default-shell window at the end of that same session
+ *   closeWindow()        that window, by stable id, in the context it was opened in
+ *
+ * What this module is NOT: a delivery transport, an address, a liveness fact, a launcher.
+ * It opens a place. `entwurf_v2` still owns delivery (`V2-DELIVERY-EXCLUDES-MUX`), and
+ * nothing here mints a garden id.
+ *
+ * Beside those three actions, `runTmux` and `requireSameContext` are exported as a NARROW
+ * INTERNAL SEAM for the T1-a launch composition to build on — not a fourth action and not a
+ * public operator surface. Say the risk plainly: `runTmux` takes argv this module did not
+ * author, so boundary 2 below does not protect it. The grammar is enforced by the `build*Args`
+ * builders, and anything reaching for `runTmux` owes its own argv the same validation. Its two
+ * production consumers are the launch and fresh-call compositions (`docs/mux-launch-rail.md`
+ * §11); the shipped delivery path calls neither.
+ *
+ * ── Four boundaries, each of which was a real way to touch the wrong thing ──
+ *
+ * 1. CONTEXT. Both `TMUX` and `TMUX_PANE` must be present and non-empty before anything
+ *    runs. `TMUX_PANE` alone is not enough: tmux invoked without `TMUX` in the environment
+ *    resolves to the DEFAULT server, so a caller carrying a stale pane id from a dead
+ *    server would have mutated the operator's live one. `TMUX` is checked for presence
+ *    only — never parsed. The socket and session inside that string are tmux's to report,
+ *    not ours to extract.
+ *
+ * 2. GRAMMAR. Every selector handed to `-t` is a native id and is validated against its
+ *    grammar BEFORE tmux is invoked. T0-a measured that tmux's own parser reinterprets
+ *    values (a trailing `;` can split a command; `#{…}`/`#(…)` expand), so "we used argv,
+ *    not a shell" is not by itself a safety argument. `%12`, `$3`, `@7` and decimal
+ *    pids/indices are the entire accepted vocabulary; anything else is refused unrun.
+ *
+ * 3. FAILURE. `display-message` returning rc=0 is not proof that a pane exists — it answers
+ *    rc=0 for a nonexistent target (filling only the SERVER fields) and rc=0 for an EMPTY
+ *    target while silently describing the current pane. That is why the echo-back exists.
+ *    But the converse does not follow: a NONZERO exit (no server, EACCES, a usage error) is
+ *    an operational failure and is raised, never laundered into "the anchor did not
+ *    resolve". Only an rc=0 row is ever parsed.
+ *
+ * 4. BINDING. A `Placement` is a fact about one server and one session, and the environment
+ *    passed to a later call could name a different — or restarted — server where the same
+ *    `$3`/`@7` mean something else entirely. Every mutation re-reads the caller's placement
+ *    and refuses unless the server pid and session id still match the ones the handle was
+ *    born in.
+ *
+ * The machine-readable rows carry ONLY native ids and decimal numbers, joined by `|`. The
+ * free-form fields tmux could also report (`socket_path`, `session_name`) are deliberately
+ * absent: a session legitimately named `a|b` would otherwise split the row. A display name
+ * is a later, separate concern, and nothing here needs one.
+ *
+ * ── Two more facts measured in T0-a (private tmux 3.6a) ──
+ *
+ * `renumber-windows on` (GLG's shipped setting) renumbers surviving windows when one in the
+ * middle disappears, so the human index is a keybinding affordance and never a handle.
+ * `remain-on-exit off` (the default) destroys a window when its pane process ends, so a
+ * window can vanish through a path this module never called; see `CloseOutcome`.
+ */
+
+import { spawnSync } from "node:child_process";
+
+// ── Native id grammar (boundary 2) ─────────────────────────────────────────
+
+const PANE_ID = /^%[0-9]+$/;
+const SESSION_ID = /^\$[0-9]+$/;
+const WINDOW_ID = /^@[0-9]+$/;
+const DECIMAL = /^[0-9]+$/;
+
+/** True only for tmux's own native pane id. */
+export function isPaneId(value: string): boolean {
+	return PANE_ID.test(value);
+}
+
+/** True only for tmux's own native session id. */
+export function isSessionId(value: string): boolean {
+	return SESSION_ID.test(value);
+}
+
+/** True only for tmux's own native window id. */
+export function isWindowId(value: string): boolean {
+	return WINDOW_ID.test(value);
+}
+
+/** True only for a bare decimal (pids, window indices). */
+export function isDecimal(value: string): boolean {
+	return DECIMAL.test(value);
+}
+
+/**
+ * Refuse a selector before it reaches tmux. The throw is deliberate and unconditional: a
+ * selector that is not a native id is either a bug or an injection attempt, and neither is
+ * something to route into tmux's parser to find out.
+ */
+export function assertSelector(kind: "pane" | "session" | "window", value: string): void {
+	const okShape = kind === "pane" ? isPaneId(value) : kind === "session" ? isSessionId(value) : isWindowId(value);
+	if (!okShape) {
+		throw new Error(`mux-placement: refusing a non-native ${kind} selector ${JSON.stringify(value)}`);
+	}
+}
+
+// ── Facts ──────────────────────────────────────────────────────────────────
+
+/**
+ * The caller's own coordinates. Native ids and decimals only — see the delimiter note in the
+ * module header for why `socket_path`/`session_name` are not here.
+ */
+export interface Placement {
+	serverPid: string;
+	sessionId: string;
+	windowId: string;
+	windowIndex: string;
+	paneId: string;
+	panePid: string;
+}
+
+/**
+ * A window this module opened, carrying the context it was born in. `serverPid`/`sessionId`
+ * are what let a later close prove it is acting on the same server and session rather than a
+ * restarted one that happens to reuse the id. Index is reported for the human, never used as
+ * a handle.
+ */
+export interface WindowHandle {
+	serverPid: string;
+	sessionId: string;
+	windowId: string;
+	windowIndex: string;
+	paneId: string;
+	panePid: string;
+}
+
+/**
+ * Why a placement could not be established. Each one is a refusal, never a fallback:
+ *   - `no-tmux-context`   `TMUX` and/or `TMUX_PANE` missing or empty — not inside tmux
+ *   - `anchor-malformed`  `TMUX_PANE` is present but is not a native `%N` pane id
+ *   - `anchor-unresolved` tmux resolved no pane for that anchor
+ *   - `anchor-mismatch`   tmux answered about a DIFFERENT pane than the one asked about
+ */
+export type PlacementRejectReason = "no-tmux-context" | "anchor-malformed" | "anchor-unresolved" | "anchor-mismatch";
+
+export type InspectResult = { ok: true; placement: Placement } | { ok: false; reason: PlacementRejectReason };
+
+/**
+ * What a close actually did.
+ *
+ * `already-gone` is NOT a blanket "any error is fine". It is issued only when the window is
+ * verifiably absent from a fresh `list-windows` — positive proof of absence, the same
+ * discipline socket-probe.ts applies to liveness. Any other failure throws, because the
+ * failure we must never swallow is "the window is still there and we did not close it".
+ *
+ * Why report it at all instead of returning void: `remain-on-exit off` makes disappearance a
+ * normal race, not an error, so failing loud on it would be wrong; but a caller that asked to
+ * close a window and got silence cannot tell whether its runtime exited on its own. Both
+ * readings matter later (T1 will want to know whether a launched runtime died before we tore
+ * it down), so the outcome is evidence, not a swallowed exception.
+ */
+export type CloseOutcome = "closed" | "already-gone";
+
+// ── Pure argv / parsing (the half a deterministic gate can pin) ─────────────
+
+/** Field order of `INSPECT_FORMAT`. Parsing and formatting share this list. */
+export const PLACEMENT_FIELDS = ["pid", "session_id", "window_id", "window_index", "pane_id", "pane_pid"] as const;
+
+const SEP = "|";
+
+/** tmux format string for a placement query — tmux's own facts, never string surgery on `$TMUX`. */
+export const INSPECT_FORMAT = PLACEMENT_FIELDS.map((f) => `#{${f}}`).join(SEP);
+
+/** Field order of `APPEND_FORMAT` — what `new-window -P -F` prints for the window it created. */
+export const WINDOW_FIELDS = ["window_id", "window_index", "pane_id", "pane_pid"] as const;
+
+export const APPEND_FORMAT = WINDOW_FIELDS.map((f) => `#{${f}}`).join(SEP);
+
+/**
+ * Read the caller's anchor. BOTH `TMUX` and `TMUX_PANE` must be present and non-empty:
+ * `TMUX_PANE` names which pane, `TMUX` is what makes a bare `tmux` resolve to the caller's
+ * server instead of the default one. `TMUX` is checked for presence only — parsing the
+ * socket/session out of it is the guess this rail forbids.
+ */
+export function readAnchor(
+	env: NodeJS.ProcessEnv,
+): { ok: true; anchor: string } | { ok: false; reason: "no-tmux-context" | "anchor-malformed" } {
+	const server = env.TMUX;
+	const anchor = env.TMUX_PANE;
+	if (typeof server !== "string" || server.length === 0) return { ok: false, reason: "no-tmux-context" };
+	if (typeof anchor !== "string" || anchor.length === 0) return { ok: false, reason: "no-tmux-context" };
+	if (!isPaneId(anchor)) return { ok: false, reason: "anchor-malformed" };
+	return { ok: true, anchor };
+}
+
+export function buildInspectArgs(anchor: string): string[] {
+	assertSelector("pane", anchor);
+	return ["display-message", "-p", "-t", anchor, INSPECT_FORMAT];
+}
+
+/**
+ * Append at the END of the caller's own session. `{end}` is the append semantics we want
+ * literally; the lowest-free-index behaviour of a bare `new-window` is a different verb and
+ * is not this contract. Targeting by `session_id` (`$0`) rather than name keeps a renamed or
+ * duplicate-named session from redirecting the append.
+ *
+ * `-d` keeps the caller's focus. No `-n`, no `-c`, no shell-command: default shell only.
+ */
+export function buildAppendArgs(sessionId: string): string[] {
+	assertSelector("session", sessionId);
+	return ["new-window", "-d", "-a", "-t", `${sessionId}:{end}`, "-P", "-F", APPEND_FORMAT];
+}
+
+export function buildCloseArgs(windowId: string): string[] {
+	assertSelector("window", windowId);
+	return ["kill-window", "-t", windowId];
+}
+
+/** Every window on the server, for the positive absence proof an `already-gone` needs. */
+export function buildListWindowIdsArgs(): string[] {
+	return ["list-windows", "-a", "-F", "#{window_id}"];
+}
+
+/**
+ * Turn an rc=0 placement row into facts — with the echo-back check that tmux's exit status
+ * cannot provide, and a grammar check on every field. A nonexistent target still fills the
+ * server fields and leaves the rest empty, so "the row was non-empty" proves nothing; an
+ * empty pane id means no pane resolved at all, which is unresolved rather than an answer
+ * about some other pane.
+ */
+export function parsePlacement(anchor: string, stdout: string): InspectResult {
+	const line = stdout.split("\n", 1)[0]?.trim() ?? "";
+	if (line.length === 0) return { ok: false, reason: "anchor-unresolved" };
+	const parts = line.split(SEP);
+	if (parts.length !== PLACEMENT_FIELDS.length) return { ok: false, reason: "anchor-unresolved" };
+	const [serverPid, sessionId, windowId, windowIndex, paneId, panePid] = parts as string[];
+	if (paneId.length === 0) return { ok: false, reason: "anchor-unresolved" };
+	if (paneId !== anchor) return { ok: false, reason: "anchor-mismatch" };
+	const wellFormed =
+		isDecimal(serverPid) &&
+		isSessionId(sessionId) &&
+		isWindowId(windowId) &&
+		isDecimal(windowIndex) &&
+		isPaneId(paneId) &&
+		isDecimal(panePid);
+	if (!wellFormed) return { ok: false, reason: "anchor-unresolved" };
+	return { ok: true, placement: { serverPid, sessionId, windowId, windowIndex, paneId, panePid } };
+}
+
+export function parseWindowFields(stdout: string): {
+	windowId: string;
+	windowIndex: string;
+	paneId: string;
+	panePid: string;
+} {
+	const line = stdout.split("\n", 1)[0]?.trim() ?? "";
+	const parts = line.split(SEP);
+	if (line.length === 0 || parts.length !== WINDOW_FIELDS.length) {
+		throw new Error(`mux-placement: new-window did not report a window handle (got ${JSON.stringify(line)})`);
+	}
+	const [windowId, windowIndex, paneId, panePid] = parts as string[];
+	if (!isWindowId(windowId) || !isDecimal(windowIndex) || !isPaneId(paneId) || !isDecimal(panePid)) {
+		throw new Error(`mux-placement: new-window reported a non-native handle (got ${JSON.stringify(line)})`);
+	}
+	return { windowId, windowIndex, paneId, panePid };
+}
+
+/**
+ * Classify a FAILED `kill-window` against a fresh window inventory. Absent → `already-gone`
+ * (positive proof). Present → `null`, and the caller must fail loud: the window is still
+ * there and we did not close it.
+ */
+export function classifyCloseFailure(windowId: string, listStdout: string): CloseOutcome | null {
+	const ids = listStdout
+		.split("\n")
+		.map((l) => l.trim())
+		.filter((l) => l.length > 0);
+	return ids.includes(windowId) ? null : "already-gone";
+}
+
+// ── The three actions ──────────────────────────────────────────────────────
+
+export interface TmuxRun {
+	status: number | null;
+	stdout: string;
+	stderr: string;
+}
+
+/**
+ * An rc=0 run is the ONLY kind whose stdout may be parsed. A nonzero status (no server,
+ * EACCES, a usage error) or a null status (killed by a signal) is an operational failure of
+ * the tmux call itself — laundering it into "the anchor did not resolve" would report a
+ * missing pane when the truth is that tmux never answered.
+ */
+export function assertTmuxOk(label: string, run: TmuxRun): void {
+	if (run.status === 0) return;
+	const how = run.status === null ? "terminated by signal" : `exit ${run.status}`;
+	throw new Error(`mux-placement: tmux ${label} failed (${how})${run.stderr.trim() ? `: ${run.stderr.trim()}` : ""}`);
+}
+
+/**
+ * Run tmux with the caller's environment INHERITED. No `-S`, no `-L`: the server is whichever
+ * one `TMUX` already names, which is the only server this module is allowed to touch — and
+ * `readAnchor` has already refused an environment where `TMUX` is absent, which is what would
+ * otherwise silently resolve to the default server.
+ */
+export function runTmux(args: readonly string[], env: NodeJS.ProcessEnv): TmuxRun {
+	const res = spawnSync("tmux", args as string[], { env, encoding: "utf8" });
+	if (res.error) throw res.error;
+	return { status: res.status, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+/** The caller's own placement, or a named refusal. Never guesses, never creates a session. */
+export function inspectPlacement(env: NodeJS.ProcessEnv = process.env): InspectResult {
+	const anchor = readAnchor(env);
+	if (!anchor.ok) return anchor;
+	const run = runTmux(buildInspectArgs(anchor.anchor), env);
+	assertTmuxOk("display-message", run);
+	return parsePlacement(anchor.anchor, run.stdout);
+}
+
+/** The context a handle or placement belongs to. BOTH halves identify it. */
+export interface PlacementContext {
+	serverPid: string;
+	sessionId: string;
+}
+
+/**
+ * Same server AND same session. Either half alone is insufficient: a restarted tmux server
+ * hands out `$0` again, and one server holds many sessions — so matching only the session id
+ * would accept a different server, and matching only the server pid would accept a different
+ * session on the right one.
+ */
+export function isSameContext(origin: PlacementContext, now: PlacementContext): boolean {
+	return origin.serverPid === now.serverPid && origin.sessionId === now.sessionId;
+}
+
+/**
+ * Re-read the caller's placement and refuse unless it is still the server and session the
+ * handle/placement was born in. Called before every mutation: `$3` on a restarted server is
+ * a different session, and an env naming another server would otherwise redirect the whole
+ * operation somewhere the caller never looked.
+ */
+export function requireSameContext(label: string, origin: PlacementContext, env: NodeJS.ProcessEnv): void {
+	const now = inspectPlacement(env);
+	if (!now.ok) {
+		throw new Error(`mux-placement: ${label} refused — the caller's placement is not resolvable (${now.reason})`);
+	}
+	if (!isSameContext(origin, now.placement)) {
+		throw new Error(
+			`mux-placement: ${label} refused — context changed (expected server ${origin.serverPid} session ${origin.sessionId}, ` +
+				`now server ${now.placement.serverPid} session ${now.placement.sessionId})`,
+		);
+	}
+}
+
+/** One detached default-shell window at the end of the caller's own session. */
+export function appendWindow(placement: Placement, env: NodeJS.ProcessEnv = process.env): WindowHandle {
+	requireSameContext("appendWindow", placement, env);
+	const run = runTmux(buildAppendArgs(placement.sessionId), env);
+	assertTmuxOk("new-window", run);
+	return { serverPid: placement.serverPid, sessionId: placement.sessionId, ...parseWindowFields(run.stdout) };
+}
+
+/**
+ * Close one window by stable id, in the context it was opened in. Reports whether it was
+ * closed or had already gone.
+ */
+export function closeWindow(handle: WindowHandle, env: NodeJS.ProcessEnv = process.env): CloseOutcome {
+	requireSameContext("closeWindow", handle, env);
+	const run = runTmux(buildCloseArgs(handle.windowId), env);
+	if (run.status === 0) return "closed";
+	// A signal kill is not a "tmux said no" — it is the call failing, and it carries no
+	// information about the window at all.
+	if (run.status === null) assertTmuxOk("kill-window", run);
+	const list = runTmux(buildListWindowIdsArgs(), env);
+	assertTmuxOk("list-windows", list);
+	const verdict = classifyCloseFailure(handle.windowId, list.stdout);
+	if (verdict) return verdict;
+	throw new Error(
+		`mux-placement: kill-window ${handle.windowId} failed (exit ${run.status}) and the window is still listed: ${run.stderr.trim()}`,
+	);
+}