@junghanacs/entwurf 0.45.0 → 0.51.0

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

@@ -0,0 +1,810 @@
+/**
+ * herdr-resume-call — reopen ONE dormant pi citizen's own transcript in a new herdr tab, from inside
+ * herdr (#157 G1a).
+ *
+ * WHAT THIS IS. The herdr half of `entwurf_resume_call`, and only its LAUNCH. The v2 composition
+ * (`entwurf-v2-visible-resume.ts`) owns everything that makes a resume a resume: the record, the
+ * per-gid lock, the dormancy proof and the same-gid control-socket observation. It reaches this
+ * module through the injected launch seam the bridge composes (`mcp/entwurf-bridge/src/index.ts`),
+ * exactly as it reaches the tmux leaf `mux-resume-call.ts`; which of the two runs is chosen by the
+ * shared rail root (`dispatchResumeLaunch` in `fresh-call-dispatch.ts`), not by the bridge and not
+ * here — so this file never sees an address, never reads a record and never decides whether the
+ * citizen came back.
+ *
+ * PI ONLY ON THIS PATH. A Claude Code resume proves its return by joining the receiver marker's owner
+ * pid to the pid of the process its launch started, and `agent start` types the command into the
+ * pane's interactive shell, so the pane's direct child is that shell, not Claude Code. A Claude Code
+ * target therefore launches through ONE layout.apply instead (`herdrClaudeCodeResumeCall` below), and
+ * like every herdr refusal nothing here falls back to tmux: a window somewhere the operator is not
+ * looking is worse than a refusal.
+ *
+ * WHAT IS REUSED AND WHAT IS NOT. Every herdr protocol primitive comes from `herdr-fresh-call.ts`:
+ * the context, the cwd classification, the caller-pane read, the tab-create reply parser, the start
+ * argv and its reply parser, the argv echo check, herdr's error code and the conditional reclaim.
+ * The fresh tab-create BUILDER is not reused, because it carries the fresh callback env by contract
+ * and a resume has no callback, no nonce, no task, no prompt and no model of its own — the runtime
+ * argv is the record's, built on the v2 side. Borrowing that builder would mean faking a callback for
+ * a sibling nobody is waiting on. No other fresh-specific stage is reused either: no birth framing
+ * and no settle witness.
+ *
+ * THE ORDER IS THE FRESH RAIL'S, FOR THE SAME REASON. `tab create` and `agent start` are two
+ * mutations, so everything decidable is decided before the first: context, backend, cwd, control
+ * characters in the runtime argv, and the read-only question of which workspace the caller is in.
+ * Every failure after the tab create carries a recovery that says what is out there; none of them
+ * says that nothing was opened.
+ *
+ * WHAT THE RECEIPT IS NOT. A successful `agent start` is a LAUNCH: herdr made a tab and was asked to
+ * start pi on that transcript there. herdr's readiness and its `agent_session` are herdr's view of
+ * the pane, not garden addressability, so this module does not wait for either. The same-gid control
+ * socket the v2 side waits for afterwards is the only observation that says the citizen is back.
+ *
+ * PI-DURABLE IS A SECOND, SEPARATE LAUNCH (#157 B3). herdr has no agent kind for the durable app, so
+ * its same-id resume reuses the fresh rail's ONE `layout.apply` on the caller's own herdr socket
+ * (`herdrPiDurableResumeCall` below) rather than `tab create` + `agent start`. The pi path above is
+ * untouched and still refuses every non-pi backend; `launchHerdrResume` is the one place that tells
+ * the three apart, by the backend the v2 side resolved from the record.
+ *
+ * CLAUDE CODE IS A THIRD, SEPARATE LAUNCH (#157 stage 4): the same ONE layout.apply, then ONE
+ * `pane.process_info` read on the pane it created, so the v2 side can join the receiver marker's owner
+ * to that pane's direct child exactly as it joins the tmux pane pid.
+ */
+
+import { spawn as spawnChildProcess } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+	argvMatchesRequest,
+	boundHerdrDiagnostic,
+	buildHerdrAgentStartArgs,
+	buildHerdrLayoutApplyPacket,
+	buildHerdrPaneGetArgs,
+	buildHerdrPaneGetPacket,
+	classifyHerdrCwd,
+	classifyHerdrLayoutApplyReply,
+	classifyHerdrLayoutPaneRead,
+	containsControlChar,
+	createHerdrRunner,
+	HERDR_AGENT_KIND,
+	HERDR_LAYOUT_PRODUCTION_DEPS,
+	HERDR_REJECT_HINT,
+	type HerdrFreshCallRejectReason,
+	type HerdrLaunchFailureReason,
+	type HerdrLayoutDeps,
+	type HerdrLayoutFailure,
+	type HerdrLayoutFailureReason,
+	type HerdrRecovery,
+	type HerdrReportedDiagnostics,
+	type HerdrRun,
+	type HerdrSocketOutcome,
+	parseHerdrAgentStartResponse,
+	parseHerdrPaneGetResponse,
+	parseHerdrTabCreateResponse,
+	readHerdrEnvelope,
+	readHerdrErrorCode,
+	reclaim,
+	resolveHerdrContext,
+	resolveHerdrSocketPath,
+	resolvePiDurableLauncher,
+	type SpawnFn,
+} from "./herdr-fresh-call.ts";
+
+/** Why a herdr resume launch was refused BEFORE anything was created. The context, caller-pane and
+ * cwd words are the fresh rail's own, so an operator learns one word per herdr fact. */
+export type HerdrResumeRejectReason =
+	| Extract<
+			HerdrFreshCallRejectReason,
+			| "herdr-context-missing"
+			| "herdr-caller-pane-missing"
+			| "herdr-caller-pane-get-failed"
+			| "herdr-caller-pane-unparsable"
+			| "herdr-caller-pane-drift"
+			| "herdr-caller-workspace-missing"
+			| "herdr-argv-control-character"
+			| "cwd-not-absolute"
+			| "cwd-missing"
+			| "cwd-not-directory"
+	  >
+	/** Not the fresh rail's `herdr-backend-unsupported`: that word's hint promises pi AND claude-code,
+	 * and on this verb the herdr agent-start path opens pi only (pi-durable and Claude Code take their own layout branches). */
+	| "herdr-resume-backend-unsupported";
+
+/** Why a launch that had already reached the tab create failed. The fresh rail's words, minus
+ * `herdr-agent-start-vanished`, which names a settle witness this rail does not run, plus one word of
+ * this rail's own: `herdr-tab-create-workspace-drift`, a create reply that agrees with itself but
+ * names another workspace than the caller's one this call asked for. */
+export type HerdrResumeLaunchFailureReason =
+	| Exclude<HerdrLaunchFailureReason, "herdr-agent-start-vanished">
+	| "herdr-tab-create-workspace-drift";
+
+/** herdr's coordinates for the tab this call created — known only once the create reply was read.
+ * VIEWS, not addresses: `[측정 2026-09-14]` a pane id is not stable for the life of a sibling. */
+export interface HerdrResumeCreated {
+	readonly herdrWorkspaceId: string;
+	readonly herdrTabId: string;
+	/** The new tab's INITIAL pane — where pi was started, and the only thing this rail may close. */
+	readonly herdrPaneId: string;
+	readonly herdrTerminalId: string;
+}
+
+/**
+ * The launch receipt: what herdr was asked to start, at which requested directory, and where the view
+ * is. ABSENT BY CONTRACT, as on the fresh rail: any garden or native session id (the address is the
+ * record's, and the v2 side already holds it), screen text, `agent_status`, `interactive_ready` and
+ * `agent_session`. There is no witness field because there is no settle stage.
+ */
+export interface HerdrResumeReceipt extends HerdrResumeCreated {
+	/** The kind herdr was ASKED for — not proof that the runtime exists (see `HERDR_AGENT_KIND`). */
+	readonly requestedKind: string;
+	/** The REQUESTED start directory, the record's — not an observation of where the pane landed. */
+	readonly cwd: string;
+	readonly herdrAgentName: string;
+}
+
+export type HerdrResumeCallResult =
+	| { readonly ok: true; readonly receipt: HerdrResumeReceipt }
+	| { readonly ok: false; readonly reason: HerdrResumeRejectReason }
+	| {
+			readonly ok: false;
+			readonly reason: HerdrResumeLaunchFailureReason;
+			/** herdr's own error code when it gave one — quoted, never retyped. */
+			readonly herdrErrorCode?: string;
+			readonly recovery: HerdrRecovery;
+			/** Present exactly when the create reply was read, so the operator is told WHICH tab. */
+			readonly created?: HerdrResumeCreated;
+	  };
+
+/**
+ * The agent name herdr will know this launch by: `entwurf-resume-` plus 16 random hex, 31 characters.
+ * `[file:line @ c77af189]` `src/app/agents.rs:15-20` requires `[a-z][a-z0-9_-]{0,31}`. It is random
+ * per call, not derived from the session or the citizen: this module never learns either, and a name
+ * an operator could read an address into is the promotion this rail refuses.
+ */
+export function mintHerdrResumeAgentName(): string {
+	return `entwurf-resume-${randomBytes(8).toString("hex")}`;
+}
+
+/**
+ * `tab create` for a resume: the fresh rail's placement policy — a NEW tab in the caller's own
+ * workspace, named explicitly, without taking focus — and its fixed identity scrub, with NO callback
+ * env. The scrub is the reason the tmux resume leaf carries one too: a pi that inherits a stale
+ * `PI_SESSION_ID` would attach as the citizen that env names instead of the one its transcript
+ * belongs to. `--cwd` is always present because a resume always has the record's directory.
+ */
+export function buildHerdrResumeTabCreateArgs(params: { workspaceId: string; cwd: string }): string[] {
+	return [
+		"tab",
+		"create",
+		"--workspace",
+		params.workspaceId,
+		"--no-focus",
+		"--cwd",
+		params.cwd,
+		"--env",
+		"PI_SESSION_ID=",
+		"--env",
+		"PI_AGENT_ID=",
+	];
+}
+
+/**
+ * Open pi on the record's transcript in a new herdr tab.
+ *
+ * `makeRun` receives the herdr binary the context names and returns the one way this call talks to
+ * herdr; production passes `createHerdrRunner`, a test passes a table. It is called only after the
+ * context resolved, so a refusal for a missing context never builds a runner.
+ */
+export async function herdrResumeCall(
+	params: { readonly backend: string; readonly cwd: string; readonly runtimeArgs: readonly string[] },
+	makeRun: (bin: string) => HerdrRun,
+	env: NodeJS.ProcessEnv,
+	agentName: string = mintHerdrResumeAgentName(),
+): Promise<HerdrResumeCallResult> {
+	const context = resolveHerdrContext(env);
+	if (!context.ok) {
+		if (context.reason === "herdr-context-missing" || context.reason === "herdr-caller-pane-missing") {
+			return { ok: false, reason: context.reason };
+		}
+		// Crash, don't warn: a context refusal this rail has no word for is drift in the shared
+		// primitive, not something to rename into the nearest reason.
+		throw new Error(`herdr-resume-call: the herdr context refused as ${context.reason}, which this rail does not name`);
+	}
+
+	// Pi only, before anything is read or created — see the module header.
+	if (params.backend !== "pi") return { ok: false, reason: "herdr-resume-backend-unsupported" };
+
+	const badCwd = classifyHerdrCwd(params.cwd);
+	if (badCwd !== null) return { ok: false, reason: badCwd };
+	// herdr refuses ANY control character in an agent argument; it is checked while it is still free.
+	if (params.runtimeArgs.some(containsControlChar)) return { ok: false, reason: "herdr-argv-control-character" };
+
+	const run = makeRun(context.context.bin);
+	// Which workspace is the caller in? herdr's own answer about the caller's own pane, read and bound
+	// exactly as the fresh rail binds it. A read creates nothing, so every failure here is a refusal.
+	const callerPaneRun = await run(buildHerdrPaneGetArgs(context.context.callerPaneId));
+	if (callerPaneRun.status !== 0) return { ok: false, reason: "herdr-caller-pane-get-failed" };
+	const callerPane = parseHerdrPaneGetResponse(callerPaneRun.stdout);
+	if (callerPane === null) return { ok: false, reason: "herdr-caller-pane-unparsable" };
+	if (callerPane.paneId !== context.context.callerPaneId) return { ok: false, reason: "herdr-caller-pane-drift" };
+	if (callerPane.workspaceId === undefined) return { ok: false, reason: "herdr-caller-workspace-missing" };
+
+	// ── everything above this line leaves nothing behind ──────────────────────────────────
+	const tabRun = await run(buildHerdrResumeTabCreateArgs({ workspaceId: callerPane.workspaceId, cwd: params.cwd }));
+	if (tabRun.status !== 0) {
+		// herdr's own envelope means herdr answered and declined before making a tab; no envelope
+		// means our runner's own timeout/kill/spawn failure, after which a tab may well exist.
+		const code = readHerdrErrorCode(tabRun.stderr);
+		return {
+			ok: false,
+			reason: "herdr-tab-create-failed",
+			...(code === undefined ? {} : { herdrErrorCode: code }),
+			recovery: code === undefined ? { outcome: "unknown" } : { outcome: "none" },
+		};
+	}
+	const tab = parseHerdrTabCreateResponse(tabRun.stdout);
+	if (tab === null) return { ok: false, reason: "herdr-tab-create-unparsable", recovery: { outcome: "unknown" } };
+	const pane = tab.rootPane;
+	// Every coordinate below comes from the reply that CREATED the tab: it is the one the reclaim is
+	// bound to, so the coordinates an operator reads and the pane this rail may close are the same.
+	const created: HerdrResumeCreated = {
+		herdrWorkspaceId: tab.workspaceId,
+		herdrTabId: tab.tabId,
+		herdrPaneId: pane.paneId,
+		herdrTerminalId: pane.terminalId,
+	};
+	// The tab must be where this call ASKED for it: the caller's own workspace. The shared parser
+	// proves the reply agrees with itself (tab and root pane name one workspace), not that it agrees
+	// with the request — a coherent reply about another workspace would start pi where the operator
+	// is not looking, under a receipt that reads as a launch. So it is a named failure, reclaimed.
+	if (tab.workspaceId !== callerPane.workspaceId) {
+		return { ok: false, reason: "herdr-tab-create-workspace-drift", recovery: await reclaim(pane, run), created };
+	}
+	// Occupancy is TWO facts, as the shared reclaim reads them (`decideConditionalClose`): herdr naming
+	// an agent in the pane, and herdr holding that agent's session. An agent whose session has not been
+	// reported yet is still somebody in the pane, so either fact stops the start.
+	if (pane.agent !== undefined || pane.hasAgentSession) {
+		return { ok: false, reason: "herdr-tab-root-pane-occupied", recovery: await reclaim(pane, run), created };
+	}
+
+	const startRun = await run(
+		buildHerdrAgentStartArgs({
+			agentName,
+			kind: HERDR_AGENT_KIND.pi,
+			paneId: pane.paneId,
+			backendArgs: params.runtimeArgs,
+		}),
+	);
+	if (startRun.status !== 0) {
+		const code = readHerdrErrorCode(startRun.stderr);
+		return {
+			ok: false,
+			reason: "herdr-agent-start-failed",
+			...(code === undefined ? {} : { herdrErrorCode: code }),
+			recovery: await reclaim(pane, run),
+			created,
+		};
+	}
+	const started = parseHerdrAgentStartResponse(startRun.stdout);
+	if (started === null) {
+		return { ok: false, reason: "herdr-agent-start-unparsable", recovery: await reclaim(pane, run), created };
+	}
+	if (
+		started.pane.paneId !== pane.paneId ||
+		started.pane.terminalId !== pane.terminalId ||
+		(started.pane.tabId !== undefined && started.pane.tabId !== tab.tabId)
+	) {
+		return { ok: false, reason: "herdr-agent-start-pane-drift", recovery: await reclaim(pane, run), created };
+	}
+	// The argv IS the record's transcript, provider and model. A pi started with anything else is a
+	// citizen this call did not ask for, and nothing downstream would reveal it.
+	if (!argvMatchesRequest(started.argv, "pi", params.runtimeArgs)) {
+		return { ok: false, reason: "herdr-agent-start-argv-drift", recovery: await reclaim(pane, run), created };
+	}
+
+	return {
+		ok: true,
+		receipt: { ...created, requestedKind: HERDR_AGENT_KIND.pi, cwd: params.cwd, herdrAgentName: agentName },
+	};
+}
+
+/** Why each outcome happened, in the caller's terms. Code-owned like every herdr rail hint; root
+ * ENTWURF.json does not carry them. */
+export const HERDR_RESUME_HINT: Readonly<Record<HerdrResumeRejectReason | HerdrResumeLaunchFailureReason, string>> = {
+	"herdr-context-missing":
+		"HERDR_ENV/HERDR_BIN_PATH are absent, so this process cannot reach herdr and this rail does not exist here; nothing was sent to tmux instead",
+	"herdr-caller-pane-missing":
+		"herdr did not give this process a HERDR_PANE_ID, so there is no way to ask herdr which workspace this caller is in",
+	"herdr-caller-pane-get-failed":
+		"herdr would not report this process's own pane — run `herdr pane get $HERDR_PANE_ID` to see what it says",
+	"herdr-caller-pane-unparsable": "herdr's reply about this process's own pane could not be read",
+	"herdr-caller-pane-drift":
+		"herdr answered about a different pane than HERDR_PANE_ID names, so its workspace says nothing about where this caller is",
+	"herdr-caller-workspace-missing":
+		"herdr reported this process's pane with no workspace, and guessing one would reopen the citizen wherever the operator is looking",
+	"herdr-resume-backend-unsupported":
+		"inside herdr, same-id resume reopens pi, pi-durable and Claude Code; this agent-start path carries pi alone, and nothing was sent to tmux instead",
+	"herdr-argv-control-character":
+		"the recorded runtime argv holds a control character, which herdr refuses in an agent argument",
+	"cwd-not-absolute": "the recorded start directory is not an absolute path",
+	"cwd-missing": "the recorded start directory no longer exists",
+	"cwd-not-directory": "the recorded start path is not a directory",
+	"herdr-tab-create-failed": "the tab create did not succeed — read the recovery line for whether anything exists",
+	"herdr-tab-create-unparsable": "herdr's tab reply could not be read, so a tab may exist that this call cannot name",
+	"herdr-tab-create-workspace-drift":
+		"herdr created the tab in a different workspace than the caller's own one this call asked for, so pi was not started there",
+	"herdr-tab-root-pane-occupied": "the new tab's initial pane already holds an agent, so pi was not started into it",
+	"herdr-agent-start-failed": "herdr did not report pi as started in the tab that was just created",
+	"herdr-agent-start-unparsable": "herdr's start reply could not be read",
+	"herdr-agent-start-pane-drift": "herdr reported a different pane, terminal or tab than the one it just created",
+	"herdr-agent-start-argv-drift": "herdr echoed an argv that is not the recorded one this call asked it to start",
+};
+
+/**
+ * What the v2 launch seam receives. Structural on purpose, as the tmux leaf's own result is: naming
+ * v2's types here would import entwurf core into a herdr rail.
+ *
+ *   ok        a herdr handle — `rail: "herdr"` plus the receipt, nothing tmux-shaped invented
+ *   reject    reason + hint, and nothing was created
+ *   failure   reason + hint + what is out there: the rail, herdr's code, the recovery, the created tab;
+ *             the pi-durable layout failure tags its rail `herdr-layout`, so no tab create step is named
+ */
+export type HerdrResumeLaunchOutcome =
+	| { readonly ok: true; readonly handle: { readonly rail: "herdr" } & HerdrResumeReceipt }
+	/** #157 B3: the pi-durable layout launch — its own rail tag, because it carries no agent name and no
+	 * terminal id (herdr's layout reply names neither), and a pi resume must never read one as its own. */
+	| { readonly ok: true; readonly handle: { readonly rail: "herdr-layout" } & HerdrPiDurableResumeReceipt }
+	/** #157 stage 4: the Claude Code layout launch — its own rail tag, because it alone carries the pane's
+	 * direct-child pid its observation joins, and neither other resume may read one as its own. */
+	| { readonly ok: true; readonly handle: { readonly rail: "herdr-layout-claude" } & HerdrClaudeCodeResumeReceipt }
+	| { readonly ok: false; readonly reason: string; readonly hint: string }
+	| {
+			readonly ok: false;
+			readonly reason: string;
+			readonly hint: string;
+			readonly failure: {
+				readonly rail: "herdr" | "herdr-layout";
+				readonly vendorCode?: string;
+				readonly recovery: HerdrRecovery;
+				readonly created?: HerdrResumeCreated;
+			};
+	  };
+
+export function herdrResumeLaunchOutcome(result: HerdrResumeCallResult): HerdrResumeLaunchOutcome {
+	if (result.ok) return { ok: true, handle: { rail: "herdr", ...result.receipt } };
+	const hint = HERDR_RESUME_HINT[result.reason];
+	if (!("recovery" in result)) return { ok: false, reason: result.reason, hint };
+	return {
+		ok: false,
+		reason: result.reason,
+		hint,
+		failure: {
+			rail: "herdr",
+			...(result.herdrErrorCode === undefined ? {} : { vendorCode: result.herdrErrorCode }),
+			recovery: result.recovery,
+			...(result.created === undefined ? {} : { created: result.created }),
+		},
+	};
+}
+
+/** The production herdr launch the shared rail root (`dispatchResumeLaunch`) returns to the v2 seam
+ * when this process is inside herdr. A pi-durable resume (#157 B3) and a Claude Code resume (#157
+ * stage 4) are the layout launches below; every other backend goes to the pi path, which refuses all
+ * but pi. */
+export async function launchHerdrResume(
+	input: {
+		readonly backend: string;
+		readonly cwd: string;
+		readonly runtimeArgs: readonly string[];
+		readonly piDurableAdoptEnv?: HerdrPiDurableAdoptEnv;
+	},
+	env: NodeJS.ProcessEnv,
+	spawn: SpawnFn = spawnChildProcess as SpawnFn,
+): Promise<HerdrResumeLaunchOutcome> {
+	if (input.backend === "pi-durable") {
+		if (input.piDurableAdoptEnv === undefined) {
+			throw new Error("herdr-resume-call: a pi-durable resume reached the herdr rail without its adopt projection");
+		}
+		return herdrPiDurableResumeLaunchOutcome(
+			await herdrPiDurableResumeCall(
+				{ cwd: input.cwd, runtimeArgs: input.runtimeArgs, adoptEnv: input.piDurableAdoptEnv },
+				env,
+			),
+		);
+	}
+	if (input.backend === "claude-code") {
+		return herdrClaudeCodeResumeLaunchOutcome(
+			await herdrClaudeCodeResumeCall({ cwd: input.cwd, runtimeArgs: input.runtimeArgs }, env),
+		);
+	}
+	return herdrResumeLaunchOutcome(await herdrResumeCall(input, (bin) => createHerdrRunner(bin, env, spawn), env));
+}
+
+// ── #157 B3: the pi-durable same-id resume through ONE layout.apply ─────────────────────────────────
+//
+// The fresh rail's layout branch, minus everything a resume does not have: no nonce, no callback env,
+// no task, no model and no preflight of a first input. What it keeps is its order and its certainty
+// rules — every decidable refusal before the first socket request, the caller-pane read (a write on
+// the socket that mutates nothing) before the ONE layout mutation write, never resent, and no reclaim
+// (herdr's layout reply names no terminal id, so this branch holds no authority to close what it
+// opened). What it adds is the adopt launch projection as the layout's env map.
+//
+// WHAT "NOTHING WAS CREATED" MEANS HERE, NAMED FOR THIS LEAF (L3-A1 §6: no rail's mapping is borrowed
+// for another). A refusal (`ok:false` with no `recovery`) is decided before the layout write, so
+// nothing was asked of herdr. After the write, `recovery.outcome === "none"` is the shared layout
+// classifier's own certainty — the request was never written (a connect failure) or herdr answered a
+// well-formed error with a code its pinned handler returns before any creation — and every other
+// outcome is `unknown`. The v2 side withdraws its reservation for the first two and keeps it otherwise.
+
+/** The adopt launch projection, read by name: the same five names the tmux leaf emits. */
+export interface HerdrPiDurableAdoptEnv {
+	readonly PI_CODING_AGENT_DIR: string;
+	readonly ENTWURF_META_SESSIONS_DIR: string;
+	readonly ENTWURF_META_MAILBOX_DIR: string;
+	readonly ENTWURF_META_SENDERS_DIR: string;
+	readonly ENTWURF_META_RECEIVERS_DIR: string;
+}
+
+/** Why a pi-durable herdr resume was refused BEFORE the layout write. One word per herdr fact, the
+ * fresh layout branch's own. */
+export type HerdrPiDurableResumeRejectReason = Extract<
+	HerdrFreshCallRejectReason,
+	| "herdr-context-missing"
+	| "herdr-caller-pane-missing"
+	| "cwd-not-absolute"
+	| "cwd-missing"
+	| "cwd-not-directory"
+	| "herdr-socket-path-missing"
+	| "pi-durable-package-incomplete"
+	| "pi-durable-carrier-drift"
+	| "pi-durable-sdk-absent"
+	| "pi-durable-sdk-mismatch"
+	| "pi-durable-launcher-missing"
+	| "herdr-argv-control-character"
+	| "herdr-caller-pane-get-failed"
+	| "herdr-caller-pane-unparsable"
+	| "herdr-caller-pane-drift"
+	| "herdr-caller-workspace-missing"
+>;
+
+/** What herdr's layout reply proved for THIS launch: the launcher and directory asked for, and the
+ * view coordinates. No agent name, no terminal id, no garden or native session id. */
+export interface HerdrPiDurableResumeReceipt {
+	/** The verified package's launcher, first in the layout's argv vector. */
+	readonly runtime: string;
+	/** The REQUESTED start directory, the reservation's — not an observation of where the pane landed. */
+	readonly cwd: string;
+	readonly herdrWorkspaceId: string;
+	readonly herdrTabId: string;
+	readonly herdrPaneId: string;
+}
+
+export type HerdrPiDurableResumeResult =
+	| { readonly ok: true; readonly receipt: HerdrPiDurableResumeReceipt }
+	| {
+			readonly ok: false;
+			readonly reason: HerdrPiDurableResumeRejectReason;
+			readonly reported?: HerdrReportedDiagnostics;
+	  }
+	| HerdrLayoutFailure;
+
+/**
+ * Open the reserved pi-durable session in a new herdr tab: the verified launcher, the record-derived
+ * argv (the managed verb and its closed adopt context, built on the v2 side and passed through
+ * untouched), the reservation's cwd, and an env map of exactly the identity scrub plus the five adopt
+ * names. `deps` is the fresh layout branch's own seam; `requestBase` names this call's two request ids.
+ */
+export async function herdrPiDurableResumeCall(
+	params: { readonly cwd: string; readonly runtimeArgs: readonly string[]; readonly adoptEnv: HerdrPiDurableAdoptEnv },
+	env: NodeJS.ProcessEnv,
+	deps: HerdrLayoutDeps = HERDR_LAYOUT_PRODUCTION_DEPS,
+	requestBase: string = mintHerdrResumeAgentName(),
+): Promise<HerdrPiDurableResumeResult> {
+	const herdr = resolveHerdrContext(env);
+	if (!herdr.ok) {
+		if (herdr.reason === "herdr-context-missing" || herdr.reason === "herdr-caller-pane-missing") {
+			return { ok: false, reason: herdr.reason };
+		}
+		throw new Error(`herdr-resume-call: the herdr context refused as ${herdr.reason}, which this rail does not name`);
+	}
+	const badCwd = classifyHerdrCwd(params.cwd);
+	if (badCwd !== null) return { ok: false, reason: badCwd };
+	const socketPath = resolveHerdrSocketPath(env);
+	if (socketPath === null) return { ok: false, reason: "herdr-socket-path-missing" };
+	const layout = deps.packageLayout();
+	if (layout === null) return { ok: false, reason: "pi-durable-package-incomplete" };
+	const runtimeRefusal = deps.runtimeVerdict(layout);
+	if (runtimeRefusal !== null) return { ok: false, reason: runtimeRefusal };
+	const runtime = resolvePiDurableLauncher(layout);
+	if (runtime === null) return { ok: false, reason: "pi-durable-launcher-missing" };
+
+	const command = [runtime, ...params.runtimeArgs];
+	const launchEnv: Record<string, string> = {
+		PI_SESSION_ID: "",
+		PI_AGENT_ID: "",
+		PI_CODING_AGENT_DIR: params.adoptEnv.PI_CODING_AGENT_DIR,
+		ENTWURF_META_SESSIONS_DIR: params.adoptEnv.ENTWURF_META_SESSIONS_DIR,
+		ENTWURF_META_MAILBOX_DIR: params.adoptEnv.ENTWURF_META_MAILBOX_DIR,
+		ENTWURF_META_SENDERS_DIR: params.adoptEnv.ENTWURF_META_SENDERS_DIR,
+		ENTWURF_META_RECEIVERS_DIR: params.adoptEnv.ENTWURF_META_RECEIVERS_DIR,
+	};
+	// A control character anywhere in the vector or the env map is refused while it is still free:
+	// this exec path has no Cc rule of its own, and herdr's env check would answer only after the write.
+	if (command.some(containsControlChar) || Object.values(launchEnv).some(containsControlChar)) {
+		return { ok: false, reason: "herdr-argv-control-character" };
+	}
+
+	const call = deps.socket(socketPath);
+	const readId = `${requestBase}:pane.get`;
+	const read = classifyHerdrLayoutPaneRead(
+		await call(buildHerdrPaneGetPacket(readId, herdr.context.callerPaneId)),
+		readId,
+		herdr.context.callerPaneId,
+	);
+	if (!read.ok) return { ok: false, reason: read.reason, reported: read.reported };
+
+	// ── everything above this line leaves nothing behind; the ONE layout mutation write follows ──
+	const writeId = `${requestBase}:layout.apply`;
+	const applied = classifyHerdrLayoutApplyReply(
+		await call(
+			buildHerdrLayoutApplyPacket(writeId, {
+				workspaceId: read.workspaceId,
+				cwd: params.cwd,
+				command,
+				env: launchEnv,
+			}),
+		),
+		{ id: writeId, workspaceId: read.workspaceId, cwd: params.cwd, command },
+	);
+	if (!applied.ok) return applied;
+	return {
+		ok: true,
+		receipt: {
+			runtime,
+			cwd: params.cwd,
+			herdrWorkspaceId: applied.workspaceId,
+			herdrTabId: applied.tabId,
+			herdrPaneId: applied.paneId,
+		},
+	};
+}
+
+/** Why each pi-durable outcome happened. The context and caller-pane words are this verb's own (the
+ * pi resume table); the package, launcher, endpoint and layout words are the fresh layout branch's. */
+export const HERDR_PI_DURABLE_RESUME_HINT: Readonly<
+	Record<HerdrPiDurableResumeRejectReason | HerdrLayoutFailureReason, string>
+> = {
+	"herdr-context-missing": HERDR_RESUME_HINT["herdr-context-missing"],
+	"herdr-caller-pane-missing": HERDR_RESUME_HINT["herdr-caller-pane-missing"],
+	"cwd-not-absolute": HERDR_RESUME_HINT["cwd-not-absolute"],
+	"cwd-missing": HERDR_RESUME_HINT["cwd-missing"],
+	"cwd-not-directory": HERDR_RESUME_HINT["cwd-not-directory"],
+	"herdr-socket-path-missing": HERDR_REJECT_HINT["herdr-socket-path-missing"],
+	"pi-durable-package-incomplete": HERDR_REJECT_HINT["pi-durable-package-incomplete"],
+	"pi-durable-carrier-drift": HERDR_REJECT_HINT["pi-durable-carrier-drift"],
+	"pi-durable-sdk-absent": HERDR_REJECT_HINT["pi-durable-sdk-absent"],
+	"pi-durable-sdk-mismatch": HERDR_REJECT_HINT["pi-durable-sdk-mismatch"],
+	"pi-durable-launcher-missing": HERDR_REJECT_HINT["pi-durable-launcher-missing"],
+	"herdr-argv-control-character":
+		"the reservation's launch argv or adopt env holds a control character, which this rail refuses before asking herdr anything",
+	"herdr-caller-pane-get-failed":
+		"herdr would not report this process's own pane through one `pane.get` on HERDR_SOCKET_PATH; any cause herdr reported is quoted",
+	"herdr-caller-pane-unparsable": HERDR_RESUME_HINT["herdr-caller-pane-unparsable"],
+	"herdr-caller-pane-drift": HERDR_RESUME_HINT["herdr-caller-pane-drift"],
+	"herdr-caller-workspace-missing": HERDR_RESUME_HINT["herdr-caller-workspace-missing"],
+	"herdr-layout-transport-failed": HERDR_REJECT_HINT["herdr-layout-transport-failed"],
+	"herdr-layout-apply-refused": HERDR_REJECT_HINT["herdr-layout-apply-refused"],
+	"herdr-layout-apply-failed": HERDR_REJECT_HINT["herdr-layout-apply-failed"],
+	"herdr-layout-reply-unparsable": HERDR_REJECT_HINT["herdr-layout-reply-unparsable"],
+	"herdr-layout-reply-drift": HERDR_REJECT_HINT["herdr-layout-reply-drift"],
+};
+
+/** The reported diagnostics, already cut, quoted onto the hint so a value cannot pose as prose. */
+function reportedSuffix(reported: HerdrReportedDiagnostics | undefined): string {
+	if (reported === undefined) return "";
+	const all: ReadonlyArray<readonly [string, string | undefined]> = [
+		["transport", reported.transport],
+		["code", reported.errorCode],
+		["message", reported.errorMessage],
+		["workspace", reported.workspaceId],
+		["tab", reported.tabId],
+		["pane", reported.paneId],
+	];
+	const fields = all.filter((field): field is readonly [string, string] => field[1] !== undefined);
+	if (fields.length === 0) return "";
+	return ` (reported, display only and unverified: ${fields.map(([name, value]) => `${name} ${JSON.stringify(value)}`).join(", ")})`;
+}
+
+/** The pi-durable layout result as the v2 seam reads it: a `herdr-layout` handle, a refusal, or a
+ * failure carrying the layout's own `none | unknown` certainty — no created coordinates, none known. */
+export function herdrPiDurableResumeLaunchOutcome(result: HerdrPiDurableResumeResult): HerdrResumeLaunchOutcome {
+	if (result.ok) return { ok: true, handle: { rail: "herdr-layout", ...result.receipt } };
+	const hint = `${HERDR_PI_DURABLE_RESUME_HINT[result.reason]}${reportedSuffix(result.reported)}`;
+	if ("recovery" in result) {
+		return {
+			ok: false,
+			reason: result.reason,
+			hint,
+			failure: {
+				rail: "herdr-layout",
+				...(result.herdrErrorCode === undefined ? {} : { vendorCode: result.herdrErrorCode }),
+				recovery: result.recovery,
+			},
+		};
+	}
+	return { ok: false, reason: result.reason, hint };
+}
+
+// ── #157 stage 4: the Claude Code same-id resume through ONE layout.apply ───────────────────────────
+//
+// A Claude Code resume is observed by joining the receiver marker its Entwurf hook re-arms to the
+// process this launch started: the hook names its parent, the Claude Code process, as the marker's
+// owner. `agent start` types the command into the pane's interactive shell, so that process is the
+// shell's child and no herdr coordinate names it. A layout argv pane spawns the vector's program as
+// the pane's direct child (`[측정 S4-CC-A H1, 2026-11-02, herdr 0.9.5 at the pinned aarch64 digest]`:
+// a program's self-reported pid, written before one exec, equalled `pane.process_info` `shell_pid`
+// and its foreground pid, at the same kernel start time, with the herdr server as its parent). So
+// this branch is the pi-durable layout launch with the record's argv and no adopt env, followed by ONE
+// read of that report for the pane it created. The read mutates nothing; whatever it says, the tab
+// stays as it is — this branch closes nothing, as the pi-durable one closes nothing.
+//
+// The runtime is the bare name `claude`, resolved by herdr exactly as its `agent start` resolves the
+// fresh Claude Code launch: this module imports no tmux leaf, so it carries no PATH resolver, and the
+// receipt says herdr resolved it. Which binary ran is not what the observation proves; the join does.
+
+/** What herdr is asked to run first in a Claude Code resume's layout vector. */
+export const HERDR_CLAUDE_CODE_RESUME_RUNTIME = "claude";
+
+/** Why a Claude Code herdr resume was refused BEFORE the layout write — the pi-durable layout words
+ * that do not name its package. */
+export type HerdrClaudeCodeResumeRejectReason = Extract<
+	HerdrPiDurableResumeRejectReason,
+	| "herdr-context-missing"
+	| "herdr-caller-pane-missing"
+	| "cwd-not-absolute"
+	| "cwd-missing"
+	| "cwd-not-directory"
+	| "herdr-socket-path-missing"
+	| "herdr-argv-control-character"
+	| "herdr-caller-pane-get-failed"
+	| "herdr-caller-pane-unparsable"
+	| "herdr-caller-pane-drift"
+	| "herdr-caller-workspace-missing"
+>;
+
+/** The pane's direct child as herdr reported it right after the layout created the pane, or why no
+ * pid came back. A pid is a JOIN for the v2 observation, never an address. */
+export type HerdrPaneChild = { readonly pid: string } | { readonly unread: string };
+
+/** What the layout reply and the one process read proved for THIS launch. No agent name, no terminal
+ * id, no garden or native session id. */
+export interface HerdrClaudeCodeResumeReceipt {
+	/** What herdr was asked to run first — a name herdr resolved, not a path this module checked. */
+	readonly runtime: string;
+	/** The REQUESTED start directory, the record's — not an observation of where the pane landed. */
+	readonly cwd: string;
+	readonly herdrWorkspaceId: string;
+	readonly herdrTabId: string;
+	readonly herdrPaneId: string;
+	readonly paneChild: HerdrPaneChild;
+}
+
+export type HerdrClaudeCodeResumeResult =
+	| { readonly ok: true; readonly receipt: HerdrClaudeCodeResumeReceipt }
+	| {
+			readonly ok: false;
+			readonly reason: HerdrClaudeCodeResumeRejectReason;
+			readonly reported?: HerdrReportedDiagnostics;
+	  }
+	| HerdrLayoutFailure;
+
+/** The fixed process read. Product function, not an RPC surface: method and shape are literal. */
+export function buildHerdrPaneProcessInfoPacket(id: string, paneId: string): string {
+	return `${JSON.stringify({ id, method: "pane.process_info", params: { pane_id: paneId } })}\n`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The process read, reduced to the pane's direct-child pid. A success must name THIS pane and carry
+ * `shell_pid` (herdr's name for the pane runtime's direct child, `integer | null` in its bundled
+ * schema) as an integer above 1; anything else is `unread` with its cause — a pane whose process
+ * already exited reports null, and that is not a pid to join.
+ */
+export function classifyHerdrPaneProcessInfo(outcome: HerdrSocketOutcome, id: string, paneId: string): HerdrPaneChild {
+	if (outcome.kind !== "reply") {
+		return { unread: boundHerdrDiagnostic("code" in outcome ? `${outcome.kind}: ${outcome.code}` : outcome.kind) };
+	}
+	const envelope = readHerdrEnvelope(outcome.line, id);
+	if (envelope === null) return { unread: "herdr's process reply could not be read" };
+	if (envelope.arm === "error")
+		return { unread: boundHerdrDiagnostic(`herdr error ${envelope.code}: ${envelope.message}`) };
+	const info = envelope.result.process_info;
+	if (envelope.result.type !== "pane_process_info" || !isRecord(info) || info.pane_id !== paneId) {
+		return { unread: "herdr's process reply does not describe the pane this call created" };
+	}
+	const pid = info.shell_pid;
+	if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 1) {
+		return { unread: `herdr reported no live direct child for the pane (shell_pid ${JSON.stringify(pid ?? null)})` };
+	}
+	return { pid: String(pid) };
+}
+
+/**
+ * Open the dormant Claude Code session in a new herdr tab: `claude` plus the record-derived argv
+ * (`--resume <session id>`, built on the v2 side and passed through untouched), the record's cwd, and
+ * the identity scrub as the env map — then read which process the new pane runs.
+ */
+export async function herdrClaudeCodeResumeCall(
+	params: { readonly cwd: string; readonly runtimeArgs: readonly string[] },
+	env: NodeJS.ProcessEnv,
+	deps: Pick<HerdrLayoutDeps, "socket"> = HERDR_LAYOUT_PRODUCTION_DEPS,
+	requestBase: string = mintHerdrResumeAgentName(),
+): Promise<HerdrClaudeCodeResumeResult> {
+	const herdr = resolveHerdrContext(env);
+	if (!herdr.ok) {
+		if (herdr.reason === "herdr-context-missing" || herdr.reason === "herdr-caller-pane-missing") {
+			return { ok: false, reason: herdr.reason };
+		}
+		throw new Error(`herdr-resume-call: the herdr context refused as ${herdr.reason}, which this rail does not name`);
+	}
+	const badCwd = classifyHerdrCwd(params.cwd);
+	if (badCwd !== null) return { ok: false, reason: badCwd };
+	const socketPath = resolveHerdrSocketPath(env);
+	if (socketPath === null) return { ok: false, reason: "herdr-socket-path-missing" };
+
+	const command = [HERDR_CLAUDE_CODE_RESUME_RUNTIME, ...params.runtimeArgs];
+	const launchEnv: Record<string, string> = { PI_SESSION_ID: "", PI_AGENT_ID: "" };
+	if (command.some(containsControlChar)) return { ok: false, reason: "herdr-argv-control-character" };
+
+	const call = deps.socket(socketPath);
+	const readId = `${requestBase}:pane.get`;
+	const read = classifyHerdrLayoutPaneRead(
+		await call(buildHerdrPaneGetPacket(readId, herdr.context.callerPaneId)),
+		readId,
+		herdr.context.callerPaneId,
+	);
+	if (!read.ok) return { ok: false, reason: read.reason, reported: read.reported };
+
+	// ── everything above this line leaves nothing behind; the ONE layout mutation write follows ──
+	const writeId = `${requestBase}:layout.apply`;
+	const applied = classifyHerdrLayoutApplyReply(
+		await call(
+			buildHerdrLayoutApplyPacket(writeId, { workspaceId: read.workspaceId, cwd: params.cwd, command, env: launchEnv }),
+		),
+		{ id: writeId, workspaceId: read.workspaceId, cwd: params.cwd, command },
+	);
+	if (!applied.ok) return applied;
+	// The tab exists from here on. ONE read of what the pane this call created is running; whatever it
+	// says is reported, and nothing is closed or retried.
+	const { workspaceId, tabId, paneId } = applied;
+	const processId = `${requestBase}:pane.process_info`;
+	const paneChild = classifyHerdrPaneProcessInfo(
+		await call(buildHerdrPaneProcessInfoPacket(processId, paneId)),
+		processId,
+		paneId,
+	);
+	const receipt: HerdrClaudeCodeResumeReceipt = {
+		runtime: HERDR_CLAUDE_CODE_RESUME_RUNTIME,
+		cwd: params.cwd,
+		herdrWorkspaceId: workspaceId,
+		herdrTabId: tabId,
+		herdrPaneId: paneId,
+		paneChild,
+	};
+	return { ok: true, receipt };
+}
+
+/** The one shared word whose fresh-rail hint names pi-durable: for this launch it names Claude Code. */
+export const HERDR_CLAUDE_CODE_SOCKET_PATH_HINT =
+	"HERDR_SOCKET_PATH is absent, empty or not absolute, so there is no herdr endpoint for Claude Code's one layout request — this rail does not guess or scan for one, and nothing was sent to tmux instead";
+
+/** The Claude Code layout result as the v2 seam reads it: a `herdr-layout-claude` handle, or — every
+ * refusal and layout failure being one the pi-durable layout branch also names — that branch's own
+ * mapping, so the two layout launches cannot classify one herdr fact two ways. The one word whose hint
+ * names pi-durable is reworded for Claude Code; every other hint names no backend. */
+export function herdrClaudeCodeResumeLaunchOutcome(result: HerdrClaudeCodeResumeResult): HerdrResumeLaunchOutcome {
+	if (result.ok) return { ok: true, handle: { rail: "herdr-layout-claude", ...result.receipt } };
+	const shared = herdrPiDurableResumeLaunchOutcome(result);
+	if (shared.ok || result.reason !== "herdr-socket-path-missing") return shared;
+	return { ...shared, hint: HERDR_CLAUDE_CODE_SOCKET_PATH_HINT };
+}