@junghanacs/entwurf 0.45.0 → 0.51.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/herdr-resume-call.js

@@ -0,0 +1,497 @@
+/**
+ * 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, parseHerdrAgentStartResponse, parseHerdrPaneGetResponse, parseHerdrTabCreateResponse, readHerdrEnvelope, readHerdrErrorCode, reclaim, resolveHerdrContext, resolveHerdrSocketPath, resolvePiDurableLauncher, } from "./herdr-fresh-call.js";
+/**
+ * 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() {
+    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) {
+    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, makeRun, env, agentName = mintHerdrResumeAgentName()) {
+    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 = {
+        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 = {
+    "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",
+};
+export function herdrResumeLaunchOutcome(result) {
+    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, env, spawn = spawnChildProcess) {
+    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));
+}
+/**
+ * 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, env, deps = HERDR_LAYOUT_PRODUCTION_DEPS, requestBase = mintHerdrResumeAgentName()) {
+    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 = {
+        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 = {
+    "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) {
+    if (reported === undefined)
+        return "";
+    const all = [
+        ["transport", reported.transport],
+        ["code", reported.errorCode],
+        ["message", reported.errorMessage],
+        ["workspace", reported.workspaceId],
+        ["tab", reported.tabId],
+        ["pane", reported.paneId],
+    ];
+    const fields = all.filter((field) => 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) {
+    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";
+/** The fixed process read. Product function, not an RPC surface: method and shape are literal. */
+export function buildHerdrPaneProcessInfoPacket(id, paneId) {
+    return `${JSON.stringify({ id, method: "pane.process_info", params: { pane_id: paneId } })}\n`;
+}
+function isRecord(value) {
+    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, id, paneId) {
+    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, env, deps = HERDR_LAYOUT_PRODUCTION_DEPS, requestBase = mintHerdrResumeAgentName()) {
+    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 = { 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 = {
+        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) {
+    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 };
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js

@@ -1228,7 +1228,9 @@ export function defaultMetaReceiversDir() {
  * sandboxed receivers root sandboxes it too and no new environment carrier exists. It is
  * deliberately NOT the v2 dispatch lock dir — visible resume holds that per-gid lock across
  * its whole launch + observation window, and the relaunched session's own arm must not wait
- * on it. Only the Claude Code hook takes this lock; nothing else reads or writes here.
+ * on it. The Claude Code hook and the pi-durable birth (`pi-durable-location.ts`, #157 B3 C4)
+ * take this lock, each around the upsert that mints `attachIncarnation`; nothing else reads or
+ * writes here.
  */
 export function defaultMetaRecordArmLocksDir(receiversDir = defaultMetaReceiversDir()) {
     return path.join(path.dirname(receiversDir), "meta-record-arm-locks");

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

@@ -23,7 +23,11 @@
  * This is the tmux rail. A caller inside herdr (`HERDR_ENV=1`, herdr's own marker, read for its
  * exact value as `fresh-call-dispatch` does) is refused by name before anything else: herdr owns
  * placement there, and an ambient `TMUX` that happens to be set would otherwise put the window in
- * a session the operator is not looking at. There is no herdr resume rail yet and no fallback.
+ * a session the operator is not looking at. Since #157 G1a the shared rail root (`fresh-call-dispatch`)
+ * hands a resume inside herdr to the separate herdr rail (`herdr-resume-call.ts`) and never reaches
+ * this leaf there;
+ * this guard stays so that a direct caller still cannot open a tmux window from inside herdr. No
+ * fallback in either direction.
  *
  * ── The cwd is the whole reason this module owns its own tmux argv ──
  *
@@ -56,24 +60,53 @@ import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWin
  * backend boundary is enforced upstream by `resolveResumeLaunchIdentity`, and this is the mux half
  * of the same fact. */
 export const RESUME_CALL_RUNTIME = { pi: "pi", "claude-code": "claude" };
+/**
+ * #157 B3: a pi-durable resume reopens through the MANAGED verb, exactly as its fresh call does —
+ * `entwurf pi-durable` verifies this package's carrier and its SDK set before anything runs, and the
+ * durable app is never started bare. It is its own entry (`resumePiDurableCall`) rather than a row of
+ * the table above, because it is the one resume whose launch also carries an environment.
+ */
+export const RESUME_CALL_PI_DURABLE_RUNTIME = "entwurf";
+/** The five `NAME=value` assignments, in the fixed order, or none. Every value must be an absolute
+ * path: a relative one would resolve against whatever directory the child starts in. */
+function adoptEnvAssignments(adoptEnv) {
+    if (adoptEnv === undefined)
+        return [];
+    const pairs = [
+        ["PI_CODING_AGENT_DIR", adoptEnv.PI_CODING_AGENT_DIR],
+        ["ENTWURF_META_SESSIONS_DIR", adoptEnv.ENTWURF_META_SESSIONS_DIR],
+        ["ENTWURF_META_MAILBOX_DIR", adoptEnv.ENTWURF_META_MAILBOX_DIR],
+        ["ENTWURF_META_SENDERS_DIR", adoptEnv.ENTWURF_META_SENDERS_DIR],
+        ["ENTWURF_META_RECEIVERS_DIR", adoptEnv.ENTWURF_META_RECEIVERS_DIR],
+    ];
+    for (const [name, value] of pairs) {
+        if (typeof value !== "string" || !value.startsWith("/")) {
+            throw new Error(`mux-resume-call: refusing to build argv with a non-absolute ${name}: ${JSON.stringify(value)}`);
+        }
+    }
+    return pairs.map(([name, value]) => `${name}=${value}`);
+}
 /**
  * Launch argv: the leaf's detached-append shape, the fixed identity scrub (`SCRUBBED_INHERITED_ENV`,
- * the same two assignments every fresh window carries), `-c`, the runtime, then the caller's flags.
+ * the same two assignments every fresh window carries), for a pi-durable adoption the five fixed
+ * projection assignments after it (#157 B3), `-c`, the runtime, then the caller's flags.
  * `--` is what keeps tmux from reading the runtime or its flags as tmux options. The scrub is not a
  * carrier: it only empties identity a tmux server may have inherited, and a resumed Claude Code
  * (which, unlike pi, never re-exports its own) would otherwise present a stale one to its bridge.
  */
-export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs) {
+export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs, adoptEnv) {
     assertSelector("session", placement.sessionId);
     assertLaunchTarget(runtimePath);
     const bad = classifyTmuxCwd(cwd);
     if (bad)
         throw new Error(`mux-resume-call: refusing to build argv with an unusable cwd (${bad}): ${cwd}`);
+    const adoptAssignments = adoptEnvAssignments(adoptEnv);
     return [
         "new-window",
         "-d",
         "-a",
         ...SCRUBBED_INHERITED_ENV.flatMap((assignment) => ["-e", assignment]),
+        ...adoptAssignments.flatMap((assignment) => ["-e", assignment]),
         "-t",
         `${placement.sessionId}:{end}`,
         "-c",
@@ -94,6 +127,18 @@ export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs) {
  * `runtimeArgs` is passed through untouched. This module does not know what `--session` means.
  */
 export function resumeCall(params, env = process.env) {
+    return openResumeWindow(RESUME_CALL_RUNTIME[params.backend], params, undefined, env);
+}
+/**
+ * #157 B3: the pi-durable resume window. The same order, refusals and receipt as `resumeCall` — the
+ * runtime is the managed `entwurf`, and the window additionally carries the fixed adopt projection.
+ * `runtimeArgs` (the managed verb and its closed adopt context) is passed through untouched; this
+ * module never decodes it.
+ */
+export function resumePiDurableCall(params, env = process.env) {
+    return openResumeWindow(RESUME_CALL_PI_DURABLE_RUNTIME, params, params.adoptEnv, env);
+}
+function openResumeWindow(runtime, params, adoptEnv, env) {
     if (env.HERDR_ENV === "1")
         return { ok: false, reason: "herdr-resume-unsupported" };
     const badCwd = classifyTmuxCwd(params.cwd);
@@ -101,7 +146,7 @@ export function resumeCall(params, env = process.env) {
         return { ok: false, reason: badCwd };
     let runtimePath;
     try {
-        runtimePath = resolveRuntimeOnPath(RESUME_CALL_RUNTIME[params.backend], env);
+        runtimePath = resolveRuntimeOnPath(runtime, env);
     }
     catch (err) {
         if (err instanceof LaunchPreconditionError)
@@ -113,7 +158,7 @@ export function resumeCall(params, env = process.env) {
         return { ok: false, reason: inspected.reason };
     const placement = inspected.placement;
     requireSameContext("resumeCall", placement, env);
-    const run = runTmux(buildResumeCallArgs(placement, params.cwd, runtimePath, params.runtimeArgs), env);
+    const run = runTmux(buildResumeCallArgs(placement, params.cwd, runtimePath, params.runtimeArgs, adoptEnv), env);
     assertTmuxOk("new-window", run);
     let fields;
     try {

package/mcp/entwurf-bridge/dist/pi-extensions/lib/pi-durable-fresh-preflight.js

@@ -19,7 +19,7 @@
  *                 `{v:2,task}` payload, whose decoder caps `task` at 16000 characters. A framed
  *                 task over that cap would open a window whose bootstrap refuses its own argv.
  *
- * ── Then the carrier, then the four units ──
+ * ── Then the carrier, then the five units ──
  *
  *   carrier          the package's own pi-durable carrier and its declared SDK set, verified
  *                    (`pi-durable-runtime.ts`); passed in as that check's verdict.
@@ -29,6 +29,9 @@
  *                    it every dispatch to the citizen is the honest `mailbox-undeliverable`.
  *   visible identity the packaged bootstrap — the one that hands the TUI the view whose conversation
  *                    labels carry the garden id.
+ *   owner fence      the compiled owner fence in the same closure — the packaged bootstrap imports it,
+ *                    so without it the bootstrap cannot load. Asked here as a file this package must
+ *                    ship, nothing more; the carrier verdict above does not cover it.
  *
  * ── What this deliberately does NOT claim ──
  *
@@ -78,6 +81,8 @@ export function piDurableFreshPreflight(params) {
         return "pi-durable-receive-unit-missing";
     if (!existsSync(layout.bootstrap))
         return "pi-durable-visible-identity-missing";
+    if (!existsSync(layout.ownerFence))
+        return "pi-durable-owner-fence-missing";
     return null;
 }
 /** Repair text beside the predicate that decides it. The runtime reasons keep theirs on the runtime
@@ -89,4 +94,5 @@ export const PI_DURABLE_PREFLIGHT_HINT = {
     "pi-durable-mcp-hand-missing": "this Entwurf package has no compiled entwurf-bridge entry, so the sibling's callback tool would not exist — reinstall or rebuild Entwurf",
     "pi-durable-receive-unit-missing": "this Entwurf package's compiled owner join does not admit pi-durable-host, so nothing could ever be delivered to the sibling — reinstall or rebuild Entwurf",
     "pi-durable-visible-identity-missing": "this Entwurf package has no packaged pi-durable bootstrap (pi/pi-durable/bootstrap.mjs), so no TUI would carry the garden id — reinstall Entwurf",
+    "pi-durable-owner-fence-missing": "this Entwurf package has no compiled pi-durable owner fence (mcp/entwurf-bridge/dist/pi-extensions/lib/pi-durable-owner-fence.js), which its packaged bootstrap imports — reinstall or rebuild Entwurf",
 };