@junghanacs/entwurf 0.14.0 → 0.14.2

package/pi-extensions/lib/acp/backend.ts

@@ -161,6 +161,35 @@ interface AcpBridgeEvent {
 	decision?: "approved" | "cancelled";
 }
 
+/**
+ * A one-shot latch for "the child has ended", created at spawn and settled by
+ * `onChildGone`. `settled` answers the question with no waiting at all; the
+ * promise is only for the bounded post-mortem window (settleChildEnd).
+ */
+interface ChildEndLatch {
+	settled: boolean;
+	promise: Promise<void>;
+	/** Called exactly once by onChildGone; cleared so a second end is a no-op. */
+	settle?: () => void;
+}
+
+function makeChildEndLatch(): ChildEndLatch {
+	let settle!: () => void;
+	const promise = new Promise<void>((resolve) => {
+		settle = resolve;
+	});
+	const latch: ChildEndLatch = {
+		settled: false,
+		promise,
+		settle: () => {
+			latch.settled = true;
+			latch.settle = undefined;
+			settle();
+		},
+	};
+	return latch;
+}
+
 interface BridgeSession {
 	key: string;
 	cwd: string;
@@ -183,8 +212,36 @@ interface BridgeSession {
 	stderrTail: string[];
 	/** How the child ended, once it has — folded into the prompt-phase error. */
 	exit?: { code: number | null; signal: NodeJS.Signals | null };
+	/**
+	 * LATCH for the child's end, readable at ANY time — deliberately not a
+	 * callback.
+	 *
+	 * `notifyChildGone` lives only between the two lines of
+	 * `awaitAcpPromptTurn`'s try/finally, so it can carry the exit status only
+	 * when the child's `exit` event wins the race against the transport — and on
+	 * the shape this backend actually runs, it does not. With piped stdio on
+	 * Linux the child's stdout EOF was measured landing about a millisecond BEFORE
+	 * node emits `exit`, for a clean exit and for SIGKILL alike (issue #72). The
+	 * SDK's generic "ACP connection closed" therefore settles the race first,
+	 * `finally` clears the callback, and the exit status arriving one tick later
+	 * has nowhere to go — which is how #72's field sample reached the operator
+	 * naming neither exit code nor signal. The opposite order stays possible and
+	 * is still handled (notifyChildGone), so both are covered by the gate.
+	 *
+	 * The latch outlives the race: `settled` is the durable fact and `promise`
+	 * lets a failing turn wait a BOUNDED moment for a late end (settleChildEnd).
+	 */
+	childEnd: ChildEndLatch;
 	/** Set while a prompt is in flight so a child death can close it (awaitAcpPromptTurn). */
 	notifyChildGone?: (err: Error) => void;
+	/**
+	 * This TURN owns reporting the child's end, so the next turn must not also
+	 * announce it. Raised at the top of a failure path — BEFORE the bounded
+	 * settle and before any teardown — so an end observed during that window is
+	 * still a natural one (we have not signalled anything yet) but is reported
+	 * exactly once, by the turn that failed on it.
+	 */
+	reporting?: boolean;
 	/**
 	 * We are tearing this child down ON PURPOSE (turn-scoped teardown, config
 	 * drift, error/abort cleanup). Its exit is then expected, not news: without
@@ -229,10 +286,13 @@ function onChildGone(session: BridgeSession, exit?: { code: number | null; signa
 	if (exit) session.exit = exit;
 	if (bridgeSessions.get(session.key) === session) bridgeSessions.delete(session.key);
 	retainedChildren.delete(session.child);
+	// Close the latch FIRST and unconditionally: it is the durable fact, and a
+	// failing turn may already be waiting on it inside its bounded settle window.
+	session.childEnd.settle?.();
 	if (session.notifyChildGone) {
 		// A turn was waiting on this child — it reports the death itself.
 		session.notifyChildGone(childEndedError(session));
-	} else if (!session.retiring) {
+	} else if (!session.retiring && !session.reporting) {
 		// Died BETWEEN turns with no turn to fail and nobody tearing it down, so
 		// nobody has seen it. Without this the next turn would silently open a
 		// fresh child and read as an ordinary cold start, hiding that the backend
@@ -281,6 +341,139 @@ function childEndedError(session: BridgeSession): Error {
 	);
 }
 
+/**
+ * The BOUNDED post-mortem window a turn that ALREADY failed may wait for the
+ * child's exit status.
+ *
+ * This is NOT a prompt deadline and must never become one: nothing here can end
+ * a running turn. It opens only after the prompt has already settled as a
+ * transport closure, and it closes on the child's own `exit` — which follows the
+ * stdout EOF by about a millisecond, so this is headroom, not a felt wait.
+ */
+const CHILD_END_SETTLE_MS = 500;
+
+/**
+ * The SDK's exact words for "the transport ended under a pending request"
+ * (`@agentclientprotocol/sdk` jsonrpc.js / acp.js:
+ * `closeSignal.reason ?? new Error("ACP connection closed")`).
+ *
+ * Matched EXACTLY, not by substring: this text appears only when the close
+ * carried NO reason — a clean stdout EOF rather than an errored stream — which
+ * is the one failure shape that arrives with no lifecycle facts of its own. A
+ * close that DID carry a reason already explains itself and must not be given a
+ * settle delay, and our own `childEndedError` already names the exit status.
+ * Widening this to a substring test would put that delay on errors that do not
+ * need it.
+ */
+const ACP_CONNECTION_CLOSED_TEXT = "ACP connection closed";
+
+function isAcpConnectionClosure(err: unknown): boolean {
+	const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+	return message.trim() === ACP_CONNECTION_CLOSED_TEXT;
+}
+
+/**
+ * Wait a BOUNDED moment for a child end that the transport already implied.
+ *
+ * Resolves immediately when the latch is already closed (the common case once
+ * the ~1ms gap has passed) and never rejects. The timer is deliberately NOT
+ * unref'd: it is the only thing that ends this wait, so letting the loop drain
+ * past it would leave a failing turn unsealed — the opposite of the honesty this
+ * exists for. It is cleared on both exits, so it holds nothing open.
+ */
+async function settleChildEnd(latch: ChildEndLatch, ms: number): Promise<void> {
+	if (latch.settled) return;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		await Promise.race([
+			latch.promise,
+			new Promise<void>((resolve) => {
+				timer = setTimeout(resolve, ms);
+			}),
+		]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+/**
+ * The lifecycle line appended to a transport-closure failure, so the operator
+ * reads WHICH phase died and HOW the child ended.
+ *
+ * Wording is load-bearing for the same reason `childEndedError`'s is: pi
+ * classifies a failed assistant message against `RETRYABLE_PROVIDER_ERROR_PATTERN`
+ * (@earendil-works/pi-ai `utils/retry`), whose terms include "timed out",
+ * "timeout", "terminated", "connection lost" and "ended without". None of those
+ * may appear here, or a dead child would put a full cold prompt replay back on
+ * the table — with the tool side effects this turn already produced.
+ *
+ * That pattern is a bare substring alternation (`new RegExp(terms.join("|"), "i")`
+ * — NO word boundaries) and its terms enumerate the HTTP statuses "429", "500",
+ * "502", "503", "504" and "524". So the settle bound is deliberately NOT interpolated: rendering
+ * CHILD_END_SETTLE_MS made this line say "within 500ms", which pi read as an
+ * HTTP 500 and classified as transient. Naming the window in prose keeps a later
+ * change of that constant from silently re-arming the replay — do not "improve"
+ * this by putting the number back; the bound belongs in the code and the gate.
+ *
+ * The three endings are kept DISTINCT on purpose (issue #72 Done-when): an
+ * exit code, a signal, and "we waited and it never said" are three different
+ * facts, and collapsing them is what made the original sample unreadable.
+ */
+function childEndLifecycleLine(opts: {
+	/** "pre-prompt" covers a new turn's bootstrap AND a reuse turn's pre-send steps. */
+	phase: "pre-prompt" | "prompt";
+	exit?: { code: number | null; signal: NodeJS.Signals | null };
+	ended: boolean;
+}): string {
+	const where =
+		opts.phase === "prompt"
+			? "the ACP backend connection closed while the prompt was still in flight"
+			: "the ACP backend connection closed before this turn's prompt was sent";
+	const how = opts.ended
+		? `the child ended (${describeChildEnd(opts.exit)})`
+		: "the child reported no exit status within the bounded post-mortem window";
+	return `[acp] lifecycle: ${where} — ${how}; this turn has no answer`;
+}
+
+/**
+ * The failure path's post-mortem: enrich ONLY the transport-closure shape, and
+ * only after waiting a bounded moment for the exit status the close implies.
+ *
+ * Returns `undefined` for every other failure — an abort, a bootstrap throw, or
+ * a child death our own `notifyChildGone` already diagnosed — so no other error
+ * pays a delay and none is double-reported.
+ *
+ * Callers MUST run this BEFORE tearing the child down: our teardown SIGTERMs the
+ * process group, so an exit read after it would be OUR signal recorded as the
+ * child's cause of death.
+ *
+ * The stderr claim is deliberately NARROW. Running before teardown means the tail
+ * already collected is not cut short by our own cleanup, and stderr arriving
+ * during this window still lands in it. It does NOT promise the child's last
+ * words: node's `exit` can precede the stdio drain, and nothing here waits for
+ * the stderr pipe to close. Draining it is a separate lever, not this one.
+ */
+async function diagnoseTransportClosure(opts: {
+	err: unknown;
+	session: BridgeSession | undefined;
+	phase: "pre-prompt" | "prompt";
+	aborted: boolean;
+}): Promise<string | undefined> {
+	if (opts.aborted || !opts.session) return undefined;
+	if (!isAcpConnectionClosure(opts.err)) return undefined;
+	const session = opts.session;
+	// This turn owns the announcement from here on, so the next turn must not
+	// repeat it. Raised BEFORE the wait and before any signal of ours, so an end
+	// observed inside the window is still a natural one.
+	session.reporting = true;
+	await settleChildEnd(session.childEnd, CHILD_END_SETTLE_MS);
+	return childEndLifecycleLine({
+		phase: opts.phase,
+		exit: session.exit,
+		ended: session.childEnd.settled,
+	});
+}
+
 // ---------------------------------------------------------------------------
 // timeout / launch / permission / stopReason / teardown helpers
 // ---------------------------------------------------------------------------
@@ -728,12 +921,16 @@ export function streamAcpTurn(
 		stream.end();
 	}
 
-	function finishError(err: unknown, aborted: boolean, stderrTail?: string[]): void {
+	function finishError(err: unknown, aborted: boolean, stderrTail?: string[], lifecycle?: string): void {
 		finalizeAcpStreamState(state);
 		state.output.stopReason = aborted ? "aborted" : "error";
 		const base = err instanceof Error ? err.message : String(err);
+		// The FIRST failure stays first and verbatim (it is what the backend
+		// actually said); the lifecycle line is added, never substituted, so a
+		// reader can still match the transport's own text.
+		const diagnosed = lifecycle ? `${base}\n${lifecycle}` : base;
 		const tail = (stderrTail ?? []).join("").trim().slice(-1_000);
-		const full = tail ? `${base}\n--- backend stderr (tail) ---\n${tail}` : base;
+		const full = tail ? `${diagnosed}\n--- backend stderr (tail) ---\n${tail}` : diagnosed;
 		// A-c: a real failure (not an abort) that looks like a context-window
 		// overflow gets an actionable hint appended, so "API Error" stops hiding
 		// the turn-scoped full-transcript-replay cause.
@@ -924,6 +1121,8 @@ export function streamAcpTurn(
 		let child: AcpChildLike | undefined;
 		let session: BridgeSession | undefined;
 		let onAbort: (() => void) | undefined;
+		/** Which phase a failure belongs to — flipped once the prompt is on the wire. */
+		let phase: "pre-prompt" | "prompt" = "pre-prompt";
 		const stderrTail: string[] = [];
 		const sessionKey = resolveSessionKey(opts, cwd);
 		try {
@@ -1012,6 +1211,9 @@ export function streamAcpTurn(
 				// this turn with the session, so a later reuse turn can still report
 				// the child's dying words.
 				stderrTail,
+				// Armed at spawn, before ANY turn can fail on this child — the latch
+				// must already exist when the `exit` listener below can fire.
+				childEnd: makeChildEndLatch(),
 			};
 			const sess = session;
 			spawned.once("exit", (...args: unknown[]) =>
@@ -1102,6 +1304,9 @@ export function streamAcpTurn(
 				signal.removeEventListener("abort", onAbort);
 				onAbort = undefined;
 			}
+			// From here the prompt is on the wire: a transport closure now is a
+			// PROMPT-phase failure, and the catch says so.
+			phase = "prompt";
 			const promptResult = await awaitAcpPromptTurn(session, wireParams, {
 				signal,
 				graceMs: deps.abortGraceMs ?? ABORT_CANCEL_GRACE_MS,
@@ -1134,6 +1339,13 @@ export function streamAcpTurn(
 				session.busy = false;
 				if (bridgeSessions.get(sessionKey) === session) bridgeSessions.delete(sessionKey);
 			}
+			// ORDER IS THE CONTRACT (#72): natural settle → seal → teardown.
+			// The bounded wait for the child's own exit status runs BEFORE we signal
+			// anything, so what we report is how the child actually ended and not our
+			// own SIGTERM; the tail collected by then is sealed before our cleanup
+			// touches the stderr pipe.
+			const lifecycle = await diagnoseTransportClosure({ err, session, phase, aborted });
+			finishError(err, aborted, session?.stderrTail ?? stderrTail, lifecycle);
 			// error/abort → drop the (uncertain) session and close its child; an
 			// uncertain connection must never be reused (GPT ④).
 			if (child) {
@@ -1142,7 +1354,6 @@ export function streamAcpTurn(
 				session?.connection.close?.(err);
 				teardownChild(child);
 			}
-			finishError(err, aborted, session?.stderrTail ?? stderrTail);
 		} finally {
 			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
 		}
@@ -1150,6 +1361,8 @@ export function streamAcpTurn(
 
 	// --- reuse: send only the latest user delta to the live ACP session
 	async function runReuseTurn(session: BridgeSession, ctxSigs: string[]): Promise<void> {
+		/** Same phase discipline as a new turn — reuse just has no bootstrap to lose. */
+		let phase: "pre-prompt" | "prompt" = "pre-prompt";
 		try {
 			if (signal?.aborted) throw new Error("aborted before prompt");
 
@@ -1171,6 +1384,7 @@ export function streamAcpTurn(
 			// ahead of the wire write; the prompt driver then owns the abort surface.
 			const wireParams = await applyProviderPayloadHook(options, { sessionId: session.acpSessionId, prompt }, model);
 			if (signal?.aborted) throw new Error("aborted during payload hook");
+			phase = "prompt";
 			const promptResult = await awaitAcpPromptTurn(session, wireParams, {
 				signal,
 				graceMs: deps.abortGraceMs ?? ABORT_CANCEL_GRACE_MS,
@@ -1188,16 +1402,22 @@ export function streamAcpTurn(
 			const aborted = Boolean(signal?.aborted);
 			session.activePromptHandler = undefined;
 			session.busy = false;
-			// error/abort on a reused session → drop it and close the child (GPT ④).
 			if (bridgeSessions.get(session.key) === session) bridgeSessions.delete(session.key);
+			// The SAME diagnostics a new turn reports, in the SAME order (#72):
+			// natural settle → seal → teardown. This is the path the field sample
+			// took — a retained child that died after its tool phase — so the
+			// ordering matters most here: teardown first would have overwritten the
+			// child's own exit status with our SIGTERM.
+			const lifecycle = await diagnoseTransportClosure({ err, session, phase, aborted });
+			// Without the session-scoped tail a mid-turn child death on a resident
+			// session surfaced as a bare "ACP connection closed" with nothing to read
+			// it by.
+			finishError(err, aborted, session.stderrTail, lifecycle);
+			// error/abort on a reused session → drop it and close the child (GPT ④).
 			session.retiring = true;
 			retainedChildren.delete(session.child);
 			session.connection.close?.(err);
 			teardownChild(session.child);
-			// The SAME diagnostics a new turn reports. Without the session-scoped
-			// tail a mid-turn child death on a resident session surfaced as a bare
-			// "ACP connection closed" with nothing to read it by.
-			finishError(err, aborted, session.stderrTail);
 		}
 	}
 

package/pi-extensions/lib/classify-tmux-cwd.ts

@@ -0,0 +1,50 @@
+/**
+ * classify-tmux-cwd — the ONE classification of a start directory that is about to be handed
+ * to tmux as a `-c` value. Shared leaf of the resume and fresh launch compositions; it owns
+ * the classification and NOTHING else — no hints (each consumer phrases its own: resume says
+ * "recorded cwd", fresh says "requested cwd"), no argv, no tmux, no fallback directory.
+ *
+ * Every rule below is a MEASURED tmux 3.6a behaviour (2026-08-06, private server), and each
+ * one is a way a launch would look successful while being wrong:
+ *
+ *   1. a NONEXISTENT `-c` is silent. tmux exits 0, opens the window, and the child falls back
+ *      to `$HOME`. A launch whose directory has been deleted would therefore open a visible
+ *      window in the wrong project and look successful. Nothing downstream can catch that:
+ *      the launch receipt would be perfectly well-formed.
+ *   2. `-c` is FORMAT-EXPANDED. `#{pane_id}` inside the value silently rewrote the path
+ *      (`<dir>/#{pane_id}` → `<dir>/%0`), and a `#(…)` value was observed running its
+ *      command. A path is data; tmux reads it as a format. So `#` is refused outright.
+ *   3. whitespace is SAFE — argv is an array and nothing re-splits. A dir named `with space`
+ *      arrived intact. So there is no quoting grammar here, and none is owed.
+ *
+ * That is the entire defence: one existence check and one character. No escaping layer, no
+ * sanitiser, no trim, no realpath/symlink policy — a symlinked project dir is a normal thing
+ * to work in, and a value is classified exactly as given.
+ */
+
+import { statSync } from "node:fs";
+import path from "node:path";
+
+/** Why a candidate `-c` value was refused. Four stable literals — both consuming
+ * compositions widen their own reject unions with this type, so the strings are contract. */
+export type TmuxCwdRejectReason = "cwd-not-absolute" | "cwd-format-token" | "cwd-missing" | "cwd-not-directory";
+
+/**
+ * Classify a candidate start directory. Split into separate reasons rather than one because
+ * the operator's next move differs: an absolute-path bug is a caller defect, a missing
+ * directory is a moved/deleted project, and a `#` is a path tmux would rewrite under us.
+ */
+export function classifyTmuxCwd(cwd: string): TmuxCwdRejectReason | null {
+	if (!path.isAbsolute(cwd)) return "cwd-not-absolute";
+	// tmux expands formats inside the `-c` VALUE. `#{…}` rewrote the path silently and `#(…)`
+	// was observed executing; neither is something to escape our way out of.
+	if (cwd.includes("#")) return "cwd-format-token";
+	let st: ReturnType<typeof statSync>;
+	try {
+		st = statSync(cwd);
+	} catch {
+		// tmux would NOT report this — it opens the window and lands the child in $HOME.
+		return "cwd-missing";
+	}
+	return st.isDirectory() ? null : "cwd-not-directory";
+}

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

@@ -25,9 +25,28 @@
  *      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, type TmuxCwdRejectReason } from "./classify-tmux-cwd.ts";
 import {
 	assertLaunchTarget,
 	LaunchPreconditionError,
@@ -142,10 +161,12 @@ export function buildFreshCallPrompt(params: {
 }
 
 /** A launch that was refused, or a placement that could not be established. Every value is a
- * NAMED refusal — this module has no fallback launch. */
+ * NAMED refusal — this module has no fallback launch and no fallback directory. The cwd members
+ * come from the shared classification leaf and their string values are stable contract. */
 export type FreshCallRejectReason =
 	| PlacementRejectReason
 	| LaunchRejectReason
+	| TmuxCwdRejectReason
 	| "caller-identity-unavailable"
 	| "model-empty"
 	| "model-invalid"
@@ -158,6 +179,10 @@ export type FreshCallRejectReason =
 export interface FreshCallReceipt extends WindowHandle {
 	backend: FreshCallBackend;
 	model: string;
+	/** The REQUESTED start directory — present only when the caller supplied one. The same kind
+	 * of fact as `runtimePath`: what tmux was asked for, never an observation of where the pane
+	 * landed. */
+	cwd?: string;
 	runtimePath: string;
 	nonce: string;
 }
@@ -174,20 +199,28 @@ function defaultRandomHex(): string {
 	return randomBytes(12).toString("hex");
 }
 
-/** Launch argv: the leaf's detached-append shape, the runtime, then the backend's dialect. */
+/** 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: Placement,
 	runtimePath: string,
 	backendArgs: readonly string[],
+	cwd?: string,
 ): string[] {
 	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,
@@ -207,7 +240,7 @@ 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; callerGardenId: string | null },
+	params: { backend: FreshCallBackend; model: string; task: string; cwd?: string; callerGardenId: string | null },
 	env: NodeJS.ProcessEnv = process.env,
 	nonce: string = mintNonce(),
 ): FreshCallResult {
@@ -220,6 +253,14 @@ export function freshCall(
 	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: string;
 	try {
@@ -240,7 +281,10 @@ export function freshCall(
 		callerGardenId: params.callerGardenId,
 		nonce,
 	});
-	const run = runTmux(buildFreshCallArgs(placement, runtimePath, buildBackendArgs(params.backend, prompt, model)), env);
+	const run = runTmux(
+		buildFreshCallArgs(placement, runtimePath, buildBackendArgs(params.backend, prompt, model), cwd),
+		env,
+	);
 	assertTmuxOk("new-window", run);
 
 	let fields: ReturnType<typeof parseWindowFields>;
@@ -265,6 +309,7 @@ export function freshCall(
 			...fields,
 			backend: params.backend,
 			model,
+			...(cwd === undefined ? {} : { cwd }),
 			runtimePath,
 			nonce,
 		},
@@ -280,6 +325,13 @@ const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	"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",
@@ -314,6 +366,7 @@ export function renderFreshCall(result: FreshCallResult): { text: string; isErro
 			`[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` +

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

@@ -4,12 +4,13 @@
  *
  * ── Why this is a module and not a parameter on fresh-call ──
  *
- * `mux-fresh-call` carries a TASK to a runtime it names; the sibling starts wherever the caller
- * happens to be. A resume carries neither: the argv comes from the record (`entwurf-v2-visible-
- * resume` builds it) and the cwd comes from the record too — it is the directory the citizen's
- * own transcript header remembers. Those are different inputs with a different risk, so they get
- * a different module rather than a fourth parameter on a composition whose contract is
- * "identity is an OUTPUT".
+ * `mux-fresh-call` carries a TASK to a runtime it names, and starts the sibling wherever the
+ * caller happens to be unless the caller REQUESTS one literal start directory (#73). A resume
+ * carries neither a task nor a caller choice: the argv comes from the record (`entwurf-v2-
+ * visible-resume` builds it) and the cwd comes from the record too — it is the directory the
+ * citizen's own transcript header remembers, never something the caller picks. Those are
+ * different inputs with a different risk, so they get a different module rather than a fourth
+ * parameter on a composition whose contract is "identity is an OUTPUT".
  *
  *   visible-resume composition → resume-call → placement leaf (unchanged, carrier-free)
  *   resume-call               -X-> garden identity, records, locks, delivery
@@ -20,22 +21,15 @@
  *
  * `mux-placement`'s `buildAppendArgs` deliberately emits no `-c` ("default shell only"), and it
  * stays that way — a resume must not widen the leaf's grammar for the three other callers. So
- * the `-c` shape lives here, with the three refusals MEASURED on tmux 3.6a (2026-08-06, private
- * server):
+ * the `-c` SHAPE lives here, while the classification of the value lives in the shared
+ * `classify-tmux-cwd.ts` leaf (fresh-call hands tmux the same flag, and a twin copy of the
+ * measured rules would rot apart on the next tmux hazard). The measured tmux 3.6a facts —
+ * a nonexistent `-c` silently lands the child in `$HOME`, `#` is format-expanded, whitespace
+ * is safe — are documented on that leaf. `|` is fine too: the cwd never enters the `-F` row
+ * (see `APPEND_FORMAT` below).
  *
- *   1. a NONEXISTENT `-c` is silent. tmux exits 0, opens the window, and the child falls back to
- *      `$HOME`. A resume whose recorded cwd has been deleted would therefore open a visible
- *      window in the wrong project and look successful. Nothing downstream can catch that: the
- *      launch receipt would be perfectly well-formed.
- *   2. `-c` is FORMAT-EXPANDED. `#{pane_id}` inside the value silently rewrote the path
- *      (`<dir>/#{pane_id}` → `<dir>/%0`), and a `#(…)` value was observed running its command.
- *      A path is data; tmux reads it as a format. So `#` is refused outright.
- *   3. whitespace is SAFE — argv is an array and nothing re-splits. A dir named `with space`
- *      arrived intact. So there is no quoting grammar here, and none is owed. `|` is fine too:
- *      the cwd never enters the `-F` row (see `APPEND_FORMAT` below).
- *
- * That is the entire defence: one existence check and one character. No escaping layer, no
- * sanitiser, no symlink policy — a symlinked project dir is a normal thing to work in.
+ * What stays HERE is the phrasing: this module's hints say "recorded cwd", because a resume's
+ * directory comes from the record — fresh-call's say "requested cwd" for the same reasons.
  *
  * ── What the receipt does NOT say ──
  *
@@ -47,8 +41,7 @@
  * to acceptance, not to the product's launch receipt.
  */
 
-import { statSync } from "node:fs";
-import path from "node:path";
+import { classifyTmuxCwd, type TmuxCwdRejectReason } from "./classify-tmux-cwd.ts";
 import {
 	assertLaunchTarget,
 	LaunchPreconditionError,
@@ -74,14 +67,9 @@ import {
 export const RESUME_CALL_RUNTIME = "pi";
 
 /** Why a resume window could not be opened. Every value is a NAMED refusal; this module has no
- * fallback launch and no fallback directory. */
-export type ResumeCallRejectReason =
-	| PlacementRejectReason
-	| LaunchRejectReason
-	| "cwd-not-absolute"
-	| "cwd-format-token"
-	| "cwd-missing"
-	| "cwd-not-directory";
+ * fallback launch and no fallback directory. The cwd members come from the shared classification
+ * leaf and their string values are stable contract. */
+export type ResumeCallRejectReason = PlacementRejectReason | LaunchRejectReason | TmuxCwdRejectReason;
 
 /** Coordinates plus what was handed to tmux. `cwd` is the REQUESTED start directory — the same
  * kind of fact as `runtimePath`, namely what tmux was asked for, not an observation. */
@@ -92,26 +80,6 @@ export interface ResumeCallReceipt extends WindowHandle {
 
 export type ResumeCallResult = { ok: true; receipt: ResumeCallReceipt } | { ok: false; reason: ResumeCallRejectReason };
 
-/**
- * Classify a candidate start directory. Split into three reasons rather than one because the
- * operator's next move differs: an absolute-path bug is a caller defect, a missing directory is
- * a moved/deleted project, and a `#` is a path tmux would rewrite under us.
- */
-export function classifyResumeCwd(cwd: string): ResumeCallRejectReason | null {
-	if (!path.isAbsolute(cwd)) return "cwd-not-absolute";
-	// tmux expands formats inside the `-c` VALUE. `#{…}` rewrote the path silently and `#(…)`
-	// was observed executing; neither is something to escape our way out of.
-	if (cwd.includes("#")) return "cwd-format-token";
-	let st: ReturnType<typeof statSync>;
-	try {
-		st = statSync(cwd);
-	} catch {
-		// tmux would NOT report this — it opens the window and lands the child in $HOME.
-		return "cwd-missing";
-	}
-	return st.isDirectory() ? null : "cwd-not-directory";
-}
-
 /**
  * Launch argv: the leaf's detached-append shape plus `-c`, the runtime, then the caller's flags.
  * `--` is what keeps tmux from reading the runtime or its flags as tmux options.
@@ -124,7 +92,7 @@ export function buildResumeCallArgs(
 ): string[] {
 	assertSelector("session", placement.sessionId);
 	assertLaunchTarget(runtimePath);
-	const bad = classifyResumeCwd(cwd);
+	const bad = classifyTmuxCwd(cwd);
 	if (bad) throw new Error(`mux-resume-call: refusing to build argv with an unusable cwd (${bad}): ${cwd}`);
 	return [
 		"new-window",
@@ -154,7 +122,7 @@ export function resumeCall(
 	params: { cwd: string; runtimeArgs: readonly string[] },
 	env: NodeJS.ProcessEnv = process.env,
 ): ResumeCallResult {
-	const badCwd = classifyResumeCwd(params.cwd);
+	const badCwd = classifyTmuxCwd(params.cwd);
 	if (badCwd) return { ok: false, reason: badCwd };
 
 	let runtimePath: string;