@junghanacs/entwurf 0.13.1 → 0.14.1

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-fresh-call.js

@@ -0,0 +1,300 @@
+/**
+ * mux-fresh-call — open ONE visible sibling in the caller's own tmux session, hand it its first
+ * task in the launch argv, and let it name itself back to the caller.
+ *
+ * ── Why this is a third module and not a parameter on the leaf ──
+ *
+ * `mux-placement` owns place and only place; `mux-launch` owns "start the fixed official pi in
+ * a window I placed" and refuses a command carrier (docs §11). Both stay that way. The carrier
+ * lives HERE, one layer up, because the thing being carried is not a command in the shell sense
+ * — it is a TASK plus the instruction that makes the new citizen announce itself. Putting it on
+ * the leaf would make every future placement caller inherit a prompt argument it has no use for.
+ *
+ *   caller agent → fresh-call → fixed backend runtime + first-turn framing
+ *   fresh-call   → placement leaf (unchanged, carrier-free)
+ *   fresh-call  -X-> identity minting, delivery transport, task planning
+ *
+ * ── Invariants ──
+ *
+ *   1. The first turn does not MINT the garden id — record and socket exist from session start.
+ *      It exists to SAY that id to the caller, who is the one who cannot see it. (rail §6-a)
+ *   2. Correlation is what the DELIVERY layer stamps on the callback, never what the sibling
+ *      says about itself — asked directly, a fresh cell answers with a uuidv7. (rail §6-b)
+ *   3. The two receipts are separate objects and stay that way: `freshCall` returns tmux
+ *      coordinates synchronously and nothing else; the correlation receipt arrives later on the
+ *      caller's own inbound surface. Merging them would claim knowledge this module cannot have.
+ *   4. A launch with no callback is a REAL outcome, not an error to retry. No watcher, no poll,
+ *      no timeout supervisor. The window is visible; the operator can look.
+ *
+ * ── The optional REQUESTED cwd (issue #73) ──
+ *
+ * A fresh sibling starts wherever the caller happens to be — unless the caller names ONE
+ * literal start directory. That input exists so a cross-repo fresh consultation never has to
+ * ride `entwurf_resume_call` for a dormant record's recorded cwd: resume stays a continuity
+ * verb, and placement pressure stays here. The rules are deliberately narrow:
+ *
+ *   - `undefined` and the exact empty string mean OMIT: no `-c` reaches tmux and the argv is
+ *     byte-identical to the pre-#73 shape. Anything else is taken LITERALLY — no trim, no
+ *     realpath, no project-name resolution, no store/peers/record lookup. The caller is the
+ *     only cwd authority this module knows.
+ *   - the value is classified by the shared `classify-tmux-cwd.ts` leaf BEFORE any mutation
+ *     (same four stable reasons as resume; the measured tmux 3.6a facts live on that leaf).
+ *     This module's hints phrase them as the REQUESTED cwd; resume's say RECORDED.
+ *   - the receipt echoes what was REQUESTED, exactly as `runtimePath` does. It never reports
+ *     `pane_current_path`: proving where the pane actually landed belongs to acceptance, not
+ *     to the launch receipt.
+ */
+import { randomBytes } from "node:crypto";
+import { classifyTmuxCwd } from "./classify-tmux-cwd.js";
+import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, } from "./mux-launch.js";
+import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
+/** The two backends this rail can open. Fixed set, not a profile — a third one is a decision,
+ * not a config entry. */
+export const FRESH_CALL_BACKENDS = ["pi", "claude-code"];
+/** The fixed runtime each backend resolves on PATH. Same reason `mux-launch` uses PATH rather
+ * than a compiled-in location: the official binary is whatever the operator's environment gives
+ * when they type the name. */
+export const FRESH_CALL_RUNTIME = {
+    pi: "pi",
+    "claude-code": "claude",
+};
+/**
+ * The callback tool NAME differs per backend and that is not cosmetic: native pi exposes the
+ * capability directly (`entwurf_v2`), while a Claude Code session reaches it through the MCP
+ * bridge under its namespaced name. Naming the wrong one costs the whole first turn.
+ */
+export const FRESH_CALL_CALLBACK_TOOL = {
+    pi: "entwurf_v2",
+    "claude-code": "mcp__entwurf-bridge__entwurf_v2",
+};
+/** Mirrors the `entwurf_v2` message bound. This is an INTERFACE cap for symmetry with the
+ * delivery surface, not a claim that a task of this size was measured through tmux. An argv
+ * that the OS refuses is a launch failure and fails loud — it never reads as a delivered task. */
+export const TASK_MAX_CHARS = 16000;
+export const MODEL_MAX_CHARS = 200;
+const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/:\[\]-]*$/;
+/** A model is an explicit launch input, not ambient process state. The grammar admits canonical
+ * pi provider/model ids, Claude model ids/aliases, and bracketed context variants, while refusing
+ * whitespace and tmux control syntax. It is passed without a shell using each runtime's measured
+ * CLI dialect: Pi takes `--model`, value; Claude Code takes `--model=value`. */
+export function isSafeFreshCallModel(model) {
+    return model.length > 0 && model.length <= MODEL_MAX_CHARS && MODEL_PATTERN.test(model);
+}
+/**
+ * Backend argv AFTER the runtime path. Both orders are MEASURED, and both were measured by
+ * getting them wrong first (rail §6-a):
+ *
+ *   pi          — prompt BEFORE `--entwurf-control`, then `--model`, value as TWO tokens.
+ *                 Flag-first submitted no message; Pi rejects the equals form for `--model`.
+ *   claude-code — prompt, then `--allowedTools=` and `--model=` as ONE token each. The space form
+ *                 for allowedTools is variadic and eats the prompt as an option value.
+ *
+ * Both failures looked identical from outside: window open, record and socket minted, no turn.
+ *
+ * The equals form is NOT a permission guarantee — on the measured host the tool was already
+ * permitted, so the option's effect was unobservable. What was observed is that it does no harm
+ * to the argv. Permission stays a documented host precondition.
+ */
+export function buildBackendArgs(backend, prompt, model) {
+    switch (backend) {
+        case "pi":
+            return [prompt, "--entwurf-control", "--model", model];
+        case "claude-code":
+            return [prompt, `--allowedTools=${FRESH_CALL_CALLBACK_TOOL["claude-code"]}`, `--model=${model}`];
+    }
+}
+/**
+ * The first-turn framing. Order is the contract: the callback is the FIRST action and the task
+ * follows it, so a sibling that gets stuck in the task has already told the caller who it is.
+ *
+ * The three prohibitions are not politeness. Each names a detour that was measured to produce a
+ * confidently wrong answer or a wasted turn.
+ */
+export function buildFreshCallPrompt(params) {
+    const tool = FRESH_CALL_CALLBACK_TOOL[params.backend];
+    return [
+        "You are a fresh visible citizen that entwurf opened in the operator's tmux session.",
+        "",
+        `FIRST ACTION, before reading files or anything else: call ${tool} with ` +
+            `target=${params.callerGardenId}, intent=fire-and-forget, wants_reply=false, and ` +
+            `message set to exactly ${params.nonce} — that string alone, nothing added.`,
+        "That call is how the agent that opened you learns your address. Do not skip it, do not",
+        "defer it until the task is done, and do not reword the message.",
+        "",
+        "Do not inspect environment variables, do not call entwurf_self, and do not start an MCP",
+        "server yourself. Your own report of your identity is not the address anyone needs.",
+        "",
+        "After the tool receipt, carry out this task:",
+        "",
+        params.task,
+    ].join("\n");
+}
+/** Correlation tag only. Random, never derived from time, cwd or a peer listing — a nonce that
+ * encoded any of those would invite exactly the guessing this rail exists to refuse. */
+export function mintNonce(randomHex = defaultRandomHex) {
+    return `mux-fresh-call-${randomHex()}`;
+}
+function defaultRandomHex() {
+    return randomBytes(12).toString("hex");
+}
+/** Launch argv: the leaf's detached-append shape, optionally `-c` at the resume-symmetric token
+ * position (after `-t`, before `-P -F`), the runtime, then the backend's dialect. An omitted cwd
+ * yields the exact pre-#73 argv — no carrier at all. */
+export function buildFreshCallArgs(placement, runtimePath, backendArgs, cwd) {
+    assertSelector("session", placement.sessionId);
+    assertLaunchTarget(runtimePath);
+    if (cwd !== undefined) {
+        const bad = classifyTmuxCwd(cwd);
+        if (bad)
+            throw new Error(`mux-fresh-call: refusing to build argv with an unusable cwd (${bad}): ${cwd}`);
+    }
+    return [
+        "new-window",
+        "-d",
+        "-a",
+        "-t",
+        `${placement.sessionId}:{end}`,
+        ...(cwd === undefined ? [] : ["-c", cwd]),
+        "-P",
+        "-F",
+        APPEND_FORMAT,
+        "--",
+        runtimePath,
+        ...backendArgs,
+    ];
+}
+/**
+ * Open the sibling. Order is the safety argument, same as `launchPi`: validate the caller's
+ * identity and task, resolve and prove the runtime, re-read the caller's placement and refuse a
+ * changed context — and only then mutate. Nothing above can leave a window behind.
+ *
+ * `callerGardenId` is supplied by the SURFACE that registered this tool, from its own
+ * record-backed context. It is not a tool parameter and this module never derives, validates
+ * against a store, or guesses it: an empty value is a named refusal, not a lookup.
+ */
+export function freshCall(params, env = process.env, nonce = mintNonce()) {
+    if (typeof params.callerGardenId !== "string" || params.callerGardenId.length === 0) {
+        return { ok: false, reason: "caller-identity-unavailable" };
+    }
+    const model = params.model.trim();
+    if (model.length === 0)
+        return { ok: false, reason: "model-empty" };
+    if (!isSafeFreshCallModel(model))
+        return { ok: false, reason: "model-invalid" };
+    const task = params.task.trim();
+    if (task.length === 0)
+        return { ok: false, reason: "task-empty" };
+    if (task.length > TASK_MAX_CHARS)
+        return { ok: false, reason: "task-too-long" };
+    // ONLY `undefined` and the exact empty string mean "no cwd". Everything else is the literal
+    // value — deliberately untrimmed, so a whitespace-mangled path is refused loudly by the
+    // classification below instead of being silently repaired into a different directory.
+    const cwd = params.cwd === undefined || params.cwd === "" ? undefined : params.cwd;
+    if (cwd !== undefined) {
+        const badCwd = classifyTmuxCwd(cwd);
+        if (badCwd)
+            return { ok: false, reason: badCwd };
+    }
+    let runtimePath;
+    try {
+        runtimePath = resolveRuntimeOnPath(FRESH_CALL_RUNTIME[params.backend], env);
+    }
+    catch (err) {
+        if (err instanceof LaunchPreconditionError)
+            return { ok: false, reason: err.reason };
+        throw err;
+    }
+    const inspected = inspectPlacement(env);
+    if (!inspected.ok)
+        return { ok: false, reason: inspected.reason };
+    const placement = inspected.placement;
+    requireSameContext("freshCall", placement, env);
+    const prompt = buildFreshCallPrompt({
+        backend: params.backend,
+        task,
+        callerGardenId: params.callerGardenId,
+        nonce,
+    });
+    const run = runTmux(buildFreshCallArgs(placement, runtimePath, buildBackendArgs(params.backend, prompt, model), cwd), env);
+    assertTmuxOk("new-window", run);
+    let fields;
+    try {
+        fields = parseWindowFields(run.stdout);
+    }
+    catch (err) {
+        // The window exists and its id is precisely what could not be read. Diffing the inventory
+        // to find "the new one" is the guess this rail forbids everywhere else, so name the orphan.
+        throw new Error(`mux-fresh-call: 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 {
+        ok: true,
+        receipt: {
+            serverPid: placement.serverPid,
+            sessionId: placement.sessionId,
+            ...fields,
+            backend: params.backend,
+            model,
+            ...(cwd === undefined ? {} : { cwd }),
+            runtimePath,
+            nonce,
+        },
+    };
+}
+/** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
+ * they will guess about. */
+const REJECT_HINT = {
+    "no-tmux-context": "this agent is not running inside tmux, so there is no session to open a sibling beside",
+    "anchor-malformed": "TMUX_PANE is not a native pane id",
+    "anchor-unresolved": "tmux resolved no pane for this agent's anchor",
+    "anchor-mismatch": "tmux answered about a different pane than the one asked about",
+    "caller-identity-unavailable": "this surface has no record-backed garden id for the caller, so the sibling would have no address to call back to",
+    "cwd-not-absolute": "the requested cwd is not an absolute path (the value is taken literally — nothing trims or resolves it)",
+    "cwd-format-token": "the requested cwd contains '#', which tmux expands as a format inside -c — it would silently rewrite the path or run a command",
+    "cwd-missing": "the requested cwd does not exist; tmux would not report this, it would open the window in $HOME and look successful",
+    "cwd-not-directory": "the requested cwd exists but is not a directory",
+    "model-empty": "model is empty after trimming; fresh calls require an explicit model",
+    "model-invalid": `model must be one ${MODEL_MAX_CHARS}-character argv-safe id/alias without whitespace or tmux syntax`,
+    "task-empty": "task is empty after trimming",
+    "task-too-long": `task exceeds ${TASK_MAX_CHARS} characters`,
+    "runtime-unresolved": "the backend's runtime is not installed on PATH",
+    "runtime-not-absolute": "the resolved runtime path is not absolute",
+    "runtime-path-whitespace": "the resolved runtime path contains whitespace, which tmux would re-split",
+    "runtime-missing": "nothing exists at the resolved runtime path",
+    "runtime-not-regular-file": "the resolved runtime path is not a regular file",
+    "runtime-not-executable": "the resolved runtime path is not executable",
+};
+/**
+ * ONE renderer for both surfaces. Not a convenience: the two registrations are separate literals
+ * (that is this repo's shape), so a shared renderer is what keeps the operator-visible answer
+ * from drifting apart between native pi and the MCP bridge.
+ *
+ * The success text states the boundary out loud. A caller that reads "launched" and assumes
+ * "delivered" is the exact confusion the two-receipt split exists to prevent, so the text refuses
+ * to imply it.
+ */
+export function renderFreshCall(result) {
+    if (!result.ok) {
+        return {
+            text: `entwurf_fresh_call rejected: ${result.reason} — ${REJECT_HINT[result.reason]}. No window was opened.`,
+            isError: true,
+        };
+    }
+    const r = result.receipt;
+    return {
+        text: `[entwurf fresh call →]\n` +
+            `  backend:  ${r.backend} (${r.runtimePath})\n` +
+            `  model:    ${r.model} (requested on the runtime CLI)\n` +
+            (r.cwd === undefined ? "" : `  cwd:      ${r.cwd} (requested start directory — not an observation)\n`) +
+            `  window:   ${r.windowId} (index ${r.windowIndex}) in session ${r.sessionId}\n` +
+            `  pane:     ${r.paneId} pid ${r.panePid}\n` +
+            `  nonce:    ${r.nonce}\n` +
+            `\n` +
+            `This is a LAUNCH receipt: tmux created that window and was asked to start the runtime with the model above. It does ` +
+            `NOT mean the sibling is running, that its first turn ran, or that the task was delivered.\n` +
+            `The sibling's garden id arrives separately — it calls entwurf_v2 back with the nonce above as its ` +
+            `first action, and the sender envelope of THAT message is the address. Nothing is polling for it; ` +
+            `if it never comes, the window is visible and can be read directly.`,
+        isError: false,
+    };
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-launch.js

@@ -0,0 +1,202 @@
+/**
+ * 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, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
+/** 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";
+/** A named precondition failure. Callers surface `reason`; they never soften it into a
+ * fallback launch of something else. */
+export class LaunchPreconditionError extends Error {
+    reason;
+    constructor(reason, message) {
+        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) {
+    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;
+    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, env = process.env) {
+    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 = process.env) {
+    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, runtimePath) {
+    assertSelector("session", sessionId);
+    assertLaunchTarget(runtimePath);
+    return ["new-window", "-d", "-a", "-t", `${sessionId}:{end}`, "-P", "-F", APPEND_FORMAT, "--", runtimePath];
+}
+/**
+ * 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, env = process.env) {
+    const runtimePath = resolvePiRuntime(env);
+    requireSameContext("launchPi", placement, env);
+    const run = runTmux(buildLaunchArgs(placement.sessionId, runtimePath), env);
+    assertTmuxOk("new-window", run);
+    let fields;
+    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 };
+}