@junghanacs/entwurf 0.18.1 → 0.19.0

package/pi-extensions/lib/mux-fresh-call.ts

@@ -1,6 +1,7 @@
 /**
- * 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.
+ * mux-fresh-call — open ONE visible sibling in the caller's own tmux server (its own session by
+ * default, or one named existing session on that server since #105), 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 ──
  *
@@ -43,6 +44,36 @@
  *   - 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.
+ *
+ * ── The optional project seat (issue #105) ──
+ *
+ * A fresh sibling opens in the caller's own tmux session — unless the caller names ONE session
+ * on the SAME server. That input exists because the operator's seats are per-project: a sibling
+ * opened for the `org` project belongs in the `org` session, and before this the only way to
+ * put it there was for the operator to move the window by hand. The rules are as narrow as the
+ * cwd input's, and for the same reason:
+ *
+ *   - `undefined` means the caller's own session, and the argv is byte-identical to the
+ *     pre-#105 shape. A named session is resolved to its native `$id` by the shared
+ *     `resolve-tmux-session.ts` leaf and ONLY that id ever reaches `-t`.
+ *   - a session that does not exist is `tmux-session-missing` and NOTHING is created — not the
+ *     window, not the session. There is no `ifMissing` axis and no `new-session` verb anywhere
+ *     in this product (GLG, 2026-09-07): the operator creates the seat and calls again. A name
+ *     outside the leaf's grammar is the separate `tmux-session-name-invalid` — a different
+ *     repair, because that name is a shape this rail does not address rather than a session
+ *     that is absent. The leaf owns which shapes and why; part of that set tmux genuinely
+ *     cannot resolve and part is a narrowing this rail chose, and it says which is which.
+ *   - `-d` is what makes this safe to do to a session someone is looking at. `[측정]` without
+ *     it, a `new-window` into another session changes THAT session's active window and steals
+ *     the operator's focus. It was already fixed in this argv; #105 is where it became
+ *     load-bearing.
+ *   - the seat is ORTHOGONAL to the cwd. `[측정 ×2]` with `-c` omitted, a window opened into
+ *     another session lands in the cwd of the process that ran `new-window` — not the target
+ *     session's `session_path` and not its active pane. Neither input is ever inferred from
+ *     the other.
+ *   - the receipt echoes the REQUESTED name and carries the OBSERVED target `$id`, which is
+ *     the session the window is actually in. It still reports no `pane_current_path`, and
+ *     there is no "session created" field because nothing here creates one.
  */
 
 import { randomBytes } from "node:crypto";
@@ -63,7 +94,6 @@ import {
 	assertSelector,
 	assertTmuxOk,
 	inspectPlacement,
-	type Placement,
 	type PlacementRejectReason,
 	parseWindowFields,
 	requireSameContext,
@@ -71,6 +101,7 @@ import {
 	type WindowHandle,
 } from "./mux-placement.ts";
 import { OMP_PREFLIGHT_HINT, type OmpPreflightRejectReason, ompFreshPreflight } from "./omp-fresh-preflight.ts";
+import { classifyTmuxSessionName, resolveTmuxSessionId, type TmuxSessionRejectReason } from "./resolve-tmux-session.ts";
 
 /** The backends this rail can open. Fixed set, not a profile — a further one is a decision,
  * not a config entry. `copilot` was added by #82 RAIL 9 under the step 9 admission contract, and
@@ -341,6 +372,7 @@ export type FreshCallRejectReason =
 	| PlacementRejectReason
 	| LaunchRejectReason
 	| TmuxCwdRejectReason
+	| TmuxSessionRejectReason
 	| CopilotPreflightRejectReason
 	| OmpPreflightRejectReason
 	| "caller-identity-unavailable"
@@ -349,6 +381,14 @@ export type FreshCallRejectReason =
 	| "task-empty"
 	| "task-too-long";
 
+/** The optional project seat: ONE existing session on the caller's own tmux server, named
+ * literally. An object rather than a bare string so the seat axis can never be confused with
+ * the cwd axis at a call site — and so a future seat fact, if one is ever measured to be
+ * needed, does not arrive as a second top-level parameter. */
+export interface FreshCallPlacement {
+	tmuxSession: string;
+}
+
 /** Coordinates plus what was handed to tmux. Read `runtimePath` as "what we asked to start".
  * There is deliberately NO field here for the callback, the nonce's arrival, or the sibling's
  * garden id — see the module header. */
@@ -359,6 +399,10 @@ export interface FreshCallReceipt extends WindowHandle {
 	 * of fact as `runtimePath`: what tmux was asked for, never an observation of where the pane
 	 * landed. */
 	cwd?: string;
+	/** The REQUESTED session name — present only when the caller named a seat. The RESOLVED
+	 * target is the inherited `sessionId`, which is the session the window is actually in; this
+	 * field is the request that produced it, exactly as `cwd` is. */
+	tmuxSession?: string;
 	runtimePath: string;
 	nonce: string;
 }
@@ -403,14 +447,21 @@ const SCRUBBED_INHERITED_ENV = ["PI_SESSION_ID=", "PI_AGENT_ID="] as const;
 
 /** Launch argv: the leaf's detached-append shape, the identity scrub, optionally `-c` at the
  * resume-symmetric token position (after `-t`, before `-P -F`), the runtime, then the backend's
- * dialect. An omitted cwd adds no `-c` carrier at all. */
+ * dialect. An omitted cwd adds no `-c` carrier at all.
+ *
+ * The first parameter is the TARGET session id, not the caller's placement. Since #105 those
+ * are not always the same session, and taking a `Placement` here would invite exactly the
+ * defect this signature prevents: copying the caller's own id into a cross-session launch. A
+ * name never reaches this function — the seat is resolved to a native `$id` before it is
+ * called, and `assertSelector` refuses anything that is not one. `-d` is not optional: without
+ * it a window opened into another session steals that session's focus (measured). */
 export function buildFreshCallArgs(
-	placement: Placement,
+	targetSessionId: string,
 	runtimePath: string,
 	backendArgs: readonly string[],
 	cwd?: string,
 ): string[] {
-	assertSelector("session", placement.sessionId);
+	assertSelector("session", targetSessionId);
 	assertLaunchTarget(runtimePath);
 	if (cwd !== undefined) {
 		const bad = classifyTmuxCwd(cwd);
@@ -422,7 +473,7 @@ export function buildFreshCallArgs(
 		"-a",
 		...SCRUBBED_INHERITED_ENV.flatMap((assignment) => ["-e", assignment]),
 		"-t",
-		`${placement.sessionId}:{end}`,
+		`${targetSessionId}:{end}`,
 		...(cwd === undefined ? [] : ["-c", cwd]),
 		"-P",
 		"-F",
@@ -443,7 +494,14 @@ export function buildFreshCallArgs(
  * against a store, or guesses it: an empty value is a named refusal, not a lookup.
  */
 export function freshCall(
-	params: { backend: FreshCallBackend; model: string; task: string; cwd?: string; callerGardenId: string | null },
+	params: {
+		backend: FreshCallBackend;
+		model: string;
+		task: string;
+		cwd?: string;
+		placement?: FreshCallPlacement;
+		callerGardenId: string | null;
+	},
 	env: NodeJS.ProcessEnv = process.env,
 	nonce: string = mintNonce(),
 ): FreshCallResult {
@@ -464,6 +522,16 @@ export function freshCall(
 		const badCwd = classifyTmuxCwd(cwd);
 		if (badCwd) return { ok: false, reason: badCwd };
 	}
+	// The seat's NAME is classified here, beside the cwd and for the same reason: it is decidable
+	// without tmux, so an unresolvable name is answered before anything else runs. Whether that
+	// session EXISTS is a tmux question and is asked below, after the caller's own context is
+	// proven — a name check that needed a live server would refuse for the wrong reason on a
+	// host with no tmux at all.
+	const seat = params.placement?.tmuxSession;
+	if (seat !== undefined) {
+		const badSeat = classifyTmuxSessionName(seat);
+		if (badSeat) return { ok: false, reason: badSeat };
+	}
 
 	let runtimePath: string;
 	try {
@@ -493,6 +561,17 @@ export function freshCall(
 	const placement = inspected.placement;
 	requireSameContext("freshCall", placement, env);
 
+	// The caller's own context is now proven, which is what makes the next lookup's exit code
+	// readable as "that session is not here" rather than "there is no server". Only the resolved
+	// native id continues; the name does not travel past this line. STILL PRE-MUTATION: an
+	// absent seat refuses with no window anywhere.
+	let targetSessionId = placement.sessionId;
+	if (seat !== undefined) {
+		const resolved = resolveTmuxSessionId(seat, (args) => runTmux(args, env));
+		if (!resolved.ok) return { ok: false, reason: resolved.reason };
+		targetSessionId = resolved.sessionId;
+	}
+
 	const composition: FreshCallComposition = {
 		prompt: buildFreshCallPrompt({
 			backend: params.backend,
@@ -503,7 +582,7 @@ export function freshCall(
 		bootstrapPayload: buildOmpBootstrapPayload({ callerGardenId: params.callerGardenId, nonce, task }),
 	};
 	const run = runTmux(
-		buildFreshCallArgs(placement, runtimePath, buildBackendArgs(params.backend, composition, model), cwd),
+		buildFreshCallArgs(targetSessionId, runtimePath, buildBackendArgs(params.backend, composition, model), cwd),
 		env,
 	);
 	assertTmuxOk("new-window", run);
@@ -516,7 +595,7 @@ export function freshCall(
 		// 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: ${
+				`be open in session ${targetSessionId} that this call cannot identify or close: ${
 					err instanceof Error ? err.message : String(err)
 				}`,
 		);
@@ -526,11 +605,12 @@ export function freshCall(
 		ok: true,
 		receipt: {
 			serverPid: placement.serverPid,
-			sessionId: placement.sessionId,
+			sessionId: targetSessionId,
 			...fields,
 			backend: params.backend,
 			model,
 			...(cwd === undefined ? {} : { cwd }),
+			...(seat === undefined ? {} : { tmuxSession: seat }),
 			runtimePath,
 			nonce,
 		},
@@ -557,6 +637,10 @@ const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	"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",
+	"tmux-session-name-invalid":
+		"the requested tmux session name is outside the shape this rail addresses (start with a letter or digit, then letters, digits, '_' or '-') — some other shapes tmux cannot resolve at all ('#' is expanded when the name is stored; '.' and ':' are its own pane/window separators inside a target; a name like '$0' loses to the session id '$0'), and the rest are declined to keep one narrow grammar, so rename the session or open one whose name fits",
+	"tmux-session-missing":
+		"no session with that exact name answers on this agent's tmux server (or that server stopped answering) — nothing was created, so open the session yourself and call again",
 	"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",
@@ -592,6 +676,9 @@ export function renderFreshCall(result: FreshCallResult): { text: string; isErro
 			`  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`) +
+			(r.tmuxSession === undefined
+				? ""
+				: `  seat:     ${r.tmuxSession} (requested tmux session, resolved to ${r.sessionId})\n`) +
 			`  window:   ${r.windowId} (index ${r.windowIndex}) in session ${r.sessionId}\n` +
 			`  pane:     ${r.paneId} pid ${r.panePid}\n` +
 			`  nonce:    ${r.nonce}\n` +

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

@@ -8,11 +8,17 @@
  * 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.
  *
+ * That sentence is still exactly true of THIS leaf, and #105 is where it started to be worth
+ * saying precisely. The fresh-call composition above may now be handed one session NAME by its
+ * caller, but it resolves that name to a native `$id` through its own leaf before anything
+ * reaches here — `appendWindow` still appends only to the caller's own session, and no function
+ * in this file has ever seen or will see a session name.
+ *
  * 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
+ *   closeWindow()        that window, by stable id, on the server it was opened on
  *
  * 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
@@ -51,8 +57,20 @@
  * 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.
+ *    before it runs.
+ *
+ *    The two mutations bind to DIFFERENT halves of that fact, because they are answering
+ *    different questions. `appendWindow` asks "is the target the caller gave me still the
+ *    caller's own seat?" and needs both halves — `isSameContext`. `closeWindow` asks "is this
+ *    handle still the window it was born as?" and needs only the SERVER half — a `@id` is
+ *    unique for the life of one server, so the session half adds nothing there. `[측정
+ *    2026-09-07, private server]` ids are handed out monotonically and are never recycled:
+ *    after `@2` was killed the next window was `@3`, and after a whole session holding `@4`
+ *    and `@5` was killed the next was `@6`. Requiring the handle's session to still exist
+ *    would also break the more informative answer below — a window whose session is gone is
+ *    `already-gone`, which is a fact the caller wants, not an error. Since #105 a launched
+ *    window may legitimately live in a session that is not the caller's, and that is exactly
+ *    when this distinction stops being academic.
  *
  * 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
@@ -124,10 +142,13 @@ export interface Placement {
 }
 
 /**
- * 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.
+ * A window this module opened, carrying the context it was born in. `serverPid` is what a later
+ * close binds to: a restarted tmux server hands out `@7` again, so without it a close could act
+ * on some other server's window. `sessionId` rides along as the RECEIPT of where the window was
+ * put — since #105 that may be a session other than the caller's — and it is deliberately not a
+ * close precondition, because `@id`s are unique for one server's whole life (measured: after
+ * `@2` was killed the next window was `@3`, and after a session holding `@4`/`@5` was killed the
+ * next was `@6`). Index is reported for the human, never used as a handle.
  */
 export interface WindowHandle {
 	serverPid: string;
@@ -358,6 +379,40 @@ export function requireSameContext(label: string, origin: PlacementContext, env:
 	}
 }
 
+/**
+ * Same server, whatever the session. The close-side half of boundary 4, kept as its own pure
+ * predicate for the same reason `isSameContext` is one: the decision is what a deterministic
+ * gate can pin, and the re-read around it is not.
+ */
+export function isSameServer(origin: PlacementContext, now: PlacementContext): boolean {
+	return origin.serverPid === now.serverPid;
+}
+
+/**
+ * Re-read the caller's placement and refuse unless the handle was born on the SAME SERVER. The
+ * close-side half of boundary 4, and deliberately NOT `requireSameContext`: since #105 a handle
+ * can name a window in a session that is not the caller's, and the session half would refuse a
+ * legitimate close. What it must still refuse is a handle from a DIFFERENT — or restarted —
+ * server, where `@7` names some other window entirely.
+ *
+ * The session half is not lost, it is covered better: `@id`s are unique for one server's whole
+ * life (measured — see boundary 4), so on a matching server the id alone identifies the window,
+ * and a window whose session has since been killed is proven absent by `closeWindow`'s own
+ * `list-windows -a` read and reported as `already-gone`.
+ */
+export function requireSameServer(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 (!isSameServer(origin, now.placement)) {
+		throw new Error(
+			`mux-placement: ${label} refused — server changed (handle was born on server ${origin.serverPid}, ` +
+				`this environment names server ${now.placement.serverPid})`,
+		);
+	}
+}
+
 /** 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);
@@ -367,11 +422,11 @@ export function appendWindow(placement: Placement, env: NodeJS.ProcessEnv = proc
 }
 
 /**
- * Close one window by stable id, in the context it was opened in. Reports whether it was
- * closed or had already gone.
+ * Close one window by stable id, on the server it was opened on. Reports whether it was closed
+ * or had already gone. The binding is the server, not the session — see `requireSameServer`.
  */
 export function closeWindow(handle: WindowHandle, env: NodeJS.ProcessEnv = process.env): CloseOutcome {
-	requireSameContext("closeWindow", handle, env);
+	requireSameServer("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

package/pi-extensions/lib/resolve-tmux-session.ts

@@ -0,0 +1,137 @@
+/**
+ * resolve-tmux-session — the ONE resolution of a caller-supplied tmux SESSION NAME into the
+ * native `$id` a placement may target. Narrow leaf of the fresh-call composition (#105); it
+ * owns the name grammar and the name→id lookup and NOTHING else — it never runs tmux (the
+ * runner is injected), never phrases a hint (each consumer owns its own wording), never
+ * creates a session, and has no fallback session.
+ *
+ * Same shape and same discipline as `classify-tmux-cwd.ts`: this file imports nothing at all,
+ * not even a node builtin, so it stays deletable on its own and cannot acquire an opinion
+ * about mux, entwurf, identity or delivery. The injected runner is matched STRUCTURALLY to
+ * `mux-placement.TmuxRun` rather than by a type import, for the same reason.
+ *
+ * Every rule below is a MEASURED tmux 3.6a behaviour (2026-09-07, private `-S` servers; the
+ * research lane's two independent reproductions are in issue #105's thread), and each one is a
+ * way a lookup would look successful while addressing the wrong thing:
+ *
+ *   1. `-t '=NAME'` performs NO format expansion — `=a}b`, `=a|b`, `=a b`, `=a,b` all resolve
+ *      exactly. The `-f '#{==:#{session_name},NAME}'` FILTER engine does the opposite: a `}`
+ *      inside the name closes the comparison early, the filter becomes a truthy string, and
+ *      EVERY session matches (6/6 measured). So the engine here is `-t '='`, never a filter.
+ *   2. absence is reported by EXIT CODE, not by output. `list-windows -t '=nosuch'` exits 1
+ *      with `can't find session: nosuch`, while `display-message -p -t '=NAME'` exits 0 with
+ *      EMPTY output for a name that exists AND for one that does not — it is unusable as a
+ *      probe. Only an rc=0 answer is ever parsed here.
+ *   3. some names cannot be addressed at all, for two different measured reasons. `#` is
+ *      FORMAT-EXPANDED when `new-session -s` stores it (`a#{x}` stored as `a`), so the
+ *      requested name never exists; and `.`/`:` are tmux's own PANE/WINDOW separators inside a
+ *      `-t` target, so the requested name is SPLIT before any session is matched. Measured
+ *      with this leaf's own engine: `list-windows -t '=my.project'` → rc=1
+ *      `can't find pane: project`, and `list-windows -t '=my:project'` → rc=1
+ *      `can't find session: my`. The exact wording is NOT contract — it moves with which
+ *      sessions happen to exist (`can't find window: project` once a session `my` is there) —
+ *      the fact is that the split happens at all. Both characters are ALSO normalised to `_`
+ *      when stored, so `a.b` and `a:b` are the same stored name `a_b` and whichever is created
+ *      second is a `duplicate session` error rather than a second seat. The lookup half is the
+ *      load-bearing one: whatever tmux stored, the REQUESTED name can never address it.
+ *      NOTE the difference from `classify-tmux-cwd.ts`: there `#(…)`
+ *      was observed EXECUTING inside a `-c` value; here it expands but does NOT execute (a
+ *      `q#(touch …)q` name stored as `qq` and wrote no file). Do not copy that leaf's
+ *      rationale into this one, or relaxing one will silently relax the other.
+ *   4. `=` protects a name against `%9`/`@1` id syntax but NOT against `$`: with a session
+ *      NAMED `$0` beside one whose ID is `$0`, `-t '=$0'` resolves the ID (measured — the
+ *      name-holder was `$1` and the lookup returned `$0`). And a session literally named
+ *      `=foo` needs `==foo`. An escaping layer here would be a second parser to keep true.
+ *
+ * The grammar is `^[A-Za-z0-9][A-Za-z0-9_-]*$`, and it is WIDER than what rules 3-4 force. Say
+ * that plainly rather than letting the reasons above cover the whole refusal set: `a}b`, `a|b`,
+ * `a b`, `a;b`, `a,b` and `_a` are all created verbatim AND resolved exactly by `-t '=NAME'`
+ * (measured 2026-09-07, one server, six sessions, six exact ids). They are refused anyway, and
+ * the reason is a DECISION, not a tmux limit — this is the grammar entwurf would need to CREATE
+ * a session safely, kept symmetric for lookup, with the remaining foreign-name width closed
+ * until an operator need for it is actually observed. That is why the refusal is
+ * `tmux-session-name-invalid` ("this rail does not address that shape") and not
+ * `tmux-session-missing` ("no such session here"): the caller's repair differs, and telling an
+ * operator their perfectly findable session "could never be found" would be a false cause.
+ *
+ * ONE BOUNDED IMPRECISION, STATED RATHER THAN LAUNDERED: rc≠0 also covers "no server running
+ * on <socket>" (measured). This leaf reads every rc≠0 as `tmux-session-missing`, so a server
+ * that died between the caller's context proof and this lookup is reported under the narrower
+ * word. That is safe — both readings are refusals that mutate nothing, and the consumer's hint
+ * names both — and it is preferred over matching tmux's own stderr text, which would pin this
+ * leaf to one vendor version's wording.
+ */
+
+/** Why a caller-named session could not become a target. Two stable literals — the consuming
+ * composition widens its own reject union with this type, so the strings are contract. */
+export type TmuxSessionRejectReason = "tmux-session-name-invalid" | "tmux-session-missing";
+
+/** What the injected runner returns. Structurally identical to `mux-placement.TmuxRun`; kept
+ * as its own declaration so this leaf imports nothing. */
+export interface TmuxSessionLookupRun {
+	status: number | null;
+	stdout: string;
+	stderr: string;
+}
+
+export type TmuxSessionLookupResult = { ok: true; sessionId: string } | { ok: false; reason: TmuxSessionRejectReason };
+
+const SESSION_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SESSION_ID = /^\$[0-9]+$/;
+
+/**
+ * Classify a candidate session NAME. Separate from the lookup because the operator's next move
+ * differs: an out-of-grammar name is a shape this rail does not address — some of those tmux
+ * genuinely cannot resolve (rules 3-4), others it resolves fine and this rail declines anyway —
+ * while a missing session is something the operator creates and retries.
+ */
+export function classifyTmuxSessionName(name: string): "tmux-session-name-invalid" | null {
+	return SESSION_NAME.test(name) ? null : "tmux-session-name-invalid";
+}
+
+/** The lookup argv. `-t '=NAME'` is the exact-name selector; `list-windows` is the engine that
+ * answers with an exit code for absence. The builder re-validates rather than trusting its
+ * caller, the same way the fresh-call argv builder re-checks a cwd. */
+export function buildTmuxSessionLookupArgs(name: string): string[] {
+	if (classifyTmuxSessionName(name)) {
+		throw new Error(`resolve-tmux-session: refusing to build a lookup for an unresolvable session name: ${name}`);
+	}
+	return ["list-windows", "-t", `=${name}`, "-F", "#{session_id}"];
+}
+
+/**
+ * Resolve a session name to its native `$id` on whatever server the runner's environment names.
+ * The id is the ONLY thing a caller-supplied name is allowed to become: everything downstream
+ * targets `$id`, never the name again.
+ *
+ * A session always holds at least one window, so an rc=0 answer prints one `$id` line per
+ * window and they are all the same id. An rc=0 that cannot be read that way is an operational
+ * anomaly, not an answer about the session, and is raised rather than turned into a refusal.
+ */
+export function resolveTmuxSessionId(
+	name: string,
+	run: (args: string[]) => TmuxSessionLookupRun,
+): TmuxSessionLookupResult {
+	const badName = classifyTmuxSessionName(name);
+	if (badName) return { ok: false, reason: badName };
+	const result = run(buildTmuxSessionLookupArgs(name));
+	// A signalled call is not tmux answering — it carries no information about the session at
+	// all, so it must never be read as absence.
+	if (result.status === null) {
+		throw new Error(
+			`resolve-tmux-session: the lookup for session "${name}" was killed by a signal: ${result.stderr.trim()}`,
+		);
+	}
+	if (result.status !== 0) return { ok: false, reason: "tmux-session-missing" };
+	const lines = result.stdout
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0);
+	const first = lines[0];
+	if (first === undefined || !SESSION_ID.test(first) || lines.some((line) => line !== first)) {
+		throw new Error(
+			`resolve-tmux-session: tmux answered rc=0 for session "${name}" with something that is not one native session id: ${JSON.stringify(result.stdout)}`,
+		);
+	}
+	return { ok: true, sessionId: first };
+}

package/scripts/check-fresh-cut-gate.sh

@@ -403,12 +403,44 @@ fi
 # #86 A5 credential tripwire: the retired sync_auth mutation (OAuth alias copy +
 # auth.json.bak) must never resurrect as an invocable surface in run.sh. Comments
 # documenting the removal are allowed; a function definition or call is not.
-if awk '!/^[[:space:]]*#/' "$REPO/run.sh" | grep -q 'sync_auth'; then
+# THE PREDICATE IS A FUNCTION so the self-test below can run the SAME code against a planted
+# fixture. A self-test that re-typed this pipeline would keep passing while the real one went
+# blind, which is precisely the failure this cell exists to prevent.
+#
+# `grep -c`, never `grep -q`. This file runs under pipefail, and a `-q` grep exits at the FIRST
+# match, closing the pipe while `awk` is still writing the remaining ~200KB of a 433KB run.sh.
+# `awk` dies of SIGPIPE (141), pipefail promotes that to the pipeline's status, and the `if`
+# takes the ELSE branch — so this tripwire went blind EXACTLY when a sync_auth surface existed
+# and reported "no credential surface remains". Unlike the omp doctor's load-dependent race this
+# one was deterministic, because the producer is far larger than the pipe buffer.
+sync_auth_surface_count() {
+  awk '!/^[[:space:]]*#/' "$1" | grep -c 'sync_auth' || true
+}
+sync_auth_hits="$(sync_auth_surface_count "$REPO/run.sh")"
+if [ "${sync_auth_hits:-0}" -gt 0 ]; then
   bad "D4b the retired sync_auth credential mutation reappeared as code in run.sh"
 else
   ok "D4b no sync_auth credential surface remains in run.sh (comments only)"
 fi
 
+# D4b-self. The cell above is green on a clean run.sh — which is exactly the state in which a
+# blind tripwire and a working one are indistinguishable. This plants the surface it exists to
+# catch and requires the SAME predicate to see it. The plant goes NEAR THE TOP of the real,
+# large run.sh on purpose: the defect only appears when the consumer can exit while the producer
+# still has bulk left to write, so a small synthetic fixture would pass even with `grep -q` and
+# would prove nothing. It is a copy under mktemp; run.sh is never written.
+fc_probe="$(mktemp -t fresh-cut-syncauth-probe.XXXXXX)"
+awk 'NR==2{print "sync_auth() { cp \"$HOME/.claude/.credentials.json\" \"$HOME/.claude/auth.json.bak\"; }"}1' \
+  "$REPO/run.sh" >"$fc_probe"
+fc_planted="$(sync_auth_surface_count "$fc_probe")"
+fc_clean="$(sync_auth_surface_count "$REPO/run.sh")"
+rm -f "$fc_probe"
+if [ "${fc_planted:-0}" -gt 0 ] && [ "${fc_clean:-0}" -eq 0 ]; then
+  ok "D4b-self the tripwire actually FIRES on a planted sync_auth surface (planted=$fc_planted clean=$fc_clean)"
+else
+  bad "[QK:FRESHCUT-SYNCAUTH-TRIPWIRE-FIRES] D4b's predicate did not see a planted sync_auth surface (planted=$fc_planted clean=$fc_clean) — the credential tripwire is blind and a green D4b means nothing"
+fi
+
 ilp_gate=$(awk '/^install_local_package\(\)/,/^}/{ if ($0 ~ /preflight_v3_store install/) { print NR; exit } }' "$REPO/run.sh")
 ilp_write=$(awk '/^install_local_package\(\)/,/^}/{ if ($0 ~ /register-pi-package.py|mkdir -p "\$project_dir/) { print NR; exit } }' "$REPO/run.sh")
 if [ -n "$ilp_gate" ] && [ -n "$ilp_write" ] && [ "$ilp_gate" -lt "$ilp_write" ]; then
@@ -425,12 +457,32 @@ else
   bad "D6 meta-bridge-install.sh's doctor call is missing or sits after the state snapshot (doctor=$mb_gate prepare=$mb_write)"
 fi
 
-if grep -n 'preflight_v3_store()' -A 40 "$REPO/run.sh" | grep -qE 'run_ts scripts/meta-bridge-fresh-cut\.ts'; then
+# Same hazard as D4b. This producer happens to emit less than one pipe buffer today, so
+# no SIGPIPE window exists — but that is a size coincidence, not a property, and it moves
+# the moment run.sh grows another match. Counted rather than short-circuited.
+preflight_cut_count() {
+  grep -n 'preflight_v3_store()' -A 40 "$1" | grep -cE 'run_ts scripts/meta-bridge-fresh-cut\.ts' || true
+}
+cut_in_preflight="$(preflight_cut_count "$REPO/run.sh")"
+if [ "${cut_in_preflight:-0}" -gt 0 ]; then
   bad "D7 the preflight invokes fresh-cut — an install must never cut a generation by itself"
 else
   ok "D7 the preflight only ever asks the doctor (never runs the cut)"
 fi
 
+# D7-self, same argument as D4b-self: a forbidding cell that is green on a clean tree proves
+# nothing until it is shown catching the thing it forbids. A synthetic fixture is enough here
+# because this producer has no SIGPIPE window to reproduce — what is being proven is detection.
+d7_probe="$(mktemp -t fresh-cut-preflight-probe.XXXXXX)"
+printf '%s\n' 'preflight_v3_store() {' '  run_ts scripts/meta-bridge-fresh-cut.ts' '}' >"$d7_probe"
+d7_planted="$(preflight_cut_count "$d7_probe")"
+rm -f "$d7_probe"
+if [ "${d7_planted:-0}" -gt 0 ] && [ "${cut_in_preflight:-0}" -eq 0 ]; then
+  ok "D7-self the cell actually FIRES on a preflight that does call fresh-cut (planted=$d7_planted real=$cut_in_preflight)"
+else
+  bad "[QK:FRESHCUT-PREFLIGHT-CUT-DETECTED] D7's predicate did not see a planted fresh-cut call in a preflight (planted=$d7_planted real=$cut_in_preflight)"
+fi
+
 if [ -e "$FRESH_CUT_GATE_CLAUDE_SENTINEL" ]; then
   bad "D8 an offline gate drive crossed the store refusal and invoked Claude" "$(cat "$FRESH_CUT_GATE_CLAUDE_SENTINEL")"
 else

package/scripts/check-gate-qualification.ts

@@ -834,24 +834,24 @@ let manifestCount: number;
 		"copilot-birth": 19,
 		"copilot-launch": 14,
 		"copilot-receive": 18,
-		"fresh-cut": 1,
+		"fresh-cut": 3,
 		"gate-qualification": 2,
 		"meta-facts": 4,
 		"meta-hook-session-switch": 17,
 		"meta-identity": 4,
 		"meta-retire": 3,
-		"mux-boundary": 14,
-		"mux-fresh-call": 37,
+		"mux-boundary": 16,
+		"mux-fresh-call": 44,
 		"mux-launcher-fence": 7,
 		"mux-parent-artifact": 3,
 		"pack-install": 2,
 		"pi-package-ownership": 6,
 		"mux-resume-call": 12,
-		"omp-birth": 11,
+		"omp-birth": 12,
 		"omp-fresh": 24,
 		"omp-receive": 11,
 		"probe-ordering": 1,
-		"release-gate": 14,
+		"release-gate": 18,
 		"resume-args": 6,
 		"resume-launch-identity": 6,
 		"self-address": 5,