@junghanacs/entwurf 0.45.0 → 0.50.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-visible-resume.js

@@ -1,6 +1,6 @@
 /**
- * entwurf-v2-visible-resume — stand a dormant pi or Claude Code citizen back up in a window the
- * operator can see, under the same garden id, and say only what was actually observed.
+ * entwurf-v2-visible-resume — stand a dormant pi, pi-durable or Claude Code citizen back up in a window
+ * (or herdr tab) the operator can see, under the same garden id, and say only what was actually observed.
  *
  * ── Two backends, one shape (#147 L2) ──
  *
@@ -19,7 +19,17 @@
  *                timeout, a store write failure, a launch after the re-read) is invisible to this
  *                proof. Back = a NEW live owner, in the pane this call opened, re-armed the marker
  *                for the same session with a fresh binding the current record also carries (same
- *                createdAt). The old marker read again is never success.
+ *                createdAt). The old marker read again is never success. "In the pane" is the owner
+ *                pid equal to that pane's direct child: tmux's pane pid, or on herdr (#157 stage 4)
+ *                the `pane.process_info` report of the pane ONE layout.apply created.
+ *
+ *   pi-durable   dormant = THIS process could reserve the session's directory D (#157 B3): the
+ *                owner-fence claim's holder is proven dead, or it closed clean, and the record and
+ *                its C4 location agree — decided by `reservePiDurableSession` inside its own
+ *                record-arm then S_D holds, under the per-target lock this module already holds as
+ *                the outer scope. The launched child adopts that one reservation from its closed
+ *                context. Back = its adoption write: the claim carries this reservation's generation
+ *                as its `adoptedFrom` — an adoption, never readiness, liveness or a turn.
  *
  * Every other backend is the leaf's named refusal. The argv is a fixed table per backend; the caller
  * supplies only the target.
@@ -28,12 +38,20 @@
  *
  *   surface (entwurf-control.ts · mcp bridge index.ts)   composition root: supplies `launch`
  *     └─ entwurf-v2-visible-resume  (this file)          v2 leaves ONLY: lock, record, socket
- *          └─ deps.launch(argv, cwd)  ── INJECTED SEAM ──→ mux-resume-call → placement leaf
+ *          └─ deps.launch(argv, cwd)  ── INJECTED SEAM ──→ fresh-call-dispatch (shared rail choice)
+ *                                                         ├→ mux-resume-call → placement leaf
+ *                                                         └→ herdr-resume-call (inside herdr: pi via agent
+ *                                                            start; pi-durable and Claude Code via ONE
+ *                                                            layout.apply)
  *
  * The seam is what keeps `docs/mux-launch-rail.md` §11 intact in both directions: v2 never
  * imports mux, mux never imports entwurf core. This module cannot open a window; it can only
  * ask whoever wired it to. That is deliberate — it means the delivery fence stays exactly where
- * `check-mux-launch` scans for it.
+ * `check-mux-launch` scans for it. The herdr rail (#157 G1a) reaches it through the same seam and
+ * the same fence: this module imports no herdr module either, and learns which rail ran only from
+ * the `rail` its launch handle carries. A herdr launch is two mutations (tab create, then agent
+ * start), so the seam may also answer with a failure AFTER something was created; that is its own
+ * result, never a refusal that says no window was opened.
  *
  * ── Why a resume is structurally SMALLER than a fresh call on identity, and LARGER on the lock ──
  *
@@ -63,8 +81,9 @@
  *
  * ── Two receipts, never merged ──
  *
- * `launch` says tmux made a window and was asked to start the runtime. `observation` says whether
- * the citizen came back under the same id (pi: its socket; Claude Code: its receiver marker).
+ * `launch` says tmux made a window (or, inside herdr, herdr made a tab) and was
+ * asked to start the runtime. `observation` says whether the citizen came back under the same id (pi:
+ * its socket; pi-durable: a child's adoption of the reservation; Claude Code: its receiver marker).
  * Neither says the resumed citizen did anything. This verb submits no prompt. For pi a resume ran
  * no turn (measured 2026-08-06, pi only — the transcript stayed byte-identical); for Claude Code
  * the runtime's own activity after resume (its SessionStart hook re-arms the doorbell, and unread
@@ -72,11 +91,13 @@
  * The socket-only description in the observation section above is the pi half; the Claude Code
  * half reads the receiver marker and the record instead.
  */
+import path from "node:path";
 import { ACP_MODEL_NOT_CURATED_HINT, AcpModelNotCuratedError } from "./acp/model-ids.js";
 import { ENTWURF_RESUME_REJECT_HINTS } from "./agent-guidance.js";
 import { buildResumePiArgs } from "./entwurf-resume-args.js";
 import { ENTWURF_V2_LOCK_DIR, acquireLock as realAcquireLock, releaseLock as realReleaseLock, } from "./entwurf-v2-lock.js";
-import { classifyMarkerOwner, metaReceiverMarkerPath, parseMetaReceiverMarker, probePidExistence, processStartKey, readStoreRecordFile, } from "./meta-session.js";
+import { classifyMarkerOwner, defaultMetaMailboxDir, defaultMetaReceiversDir, defaultMetaSendersDir, defaultMetaSessionsDir, metaReceiverMarkerPath, parseMetaReceiverMarker, probePidExistence, processStartKey, readStoreRecordFile, } from "./meta-session.js";
+import { observePiDurableReservation, PiDurableOwnerFenceError, reservePiDurableSession, withdrawPiDurableReservation, } from "./pi-durable-owner-fence.js";
 import { ResumeBackendUnsupportedError, resolveResumeLaunchIdentity, } from "./resume-launch-identity.js";
 import { isValidSessionId } from "./session-id.js";
 import { CONTROL_SOCKET_DIR, inspectTargetControlSocket, mapInspectionToLiveness, } from "./socket-discovery.js";
@@ -98,6 +119,19 @@ export function makeVisibleResumeDeps(launch, overrides = {}) {
         probeSocket: (socketPath) => probeSocketLiveness(socketPath),
         inspectReceiver: (gid) => inspectReceiverMarker(gid),
         launch,
+        // The four roots THIS process resolves now, handed to the reserve as given: a split shape is
+        // the reserve's own named refusal, never merged here.
+        reservePiDurable: (gid) => reservePiDurableSession({
+            gardenId: gid,
+            roots: {
+                sessionsDir: defaultMetaSessionsDir(),
+                mailboxDir: defaultMetaMailboxDir(),
+                sendersDir: defaultMetaSendersDir(),
+                receiversDir: defaultMetaReceiversDir(),
+            },
+        }),
+        withdrawPiDurable: (reservation) => withdrawPiDurableReservation(reservation),
+        observePiDurable: (reservation) => observePiDurableReservation(reservation),
         sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
         now: () => Date.now(),
         ...overrides,
@@ -219,7 +253,7 @@ export async function visibleResume(targetGardenId, deps) {
                 return {
                     ok: false,
                     reason: err.reason,
-                    detail: `${targetGardenId} is a ${err.backend} citizen; only pi and Claude Code citizens can be reopened ` +
+                    detail: `${targetGardenId} is a ${err.backend} citizen; only pi, pi-durable and Claude Code citizens can be reopened ` +
                         `under the same garden id`,
                 };
             }
@@ -227,6 +261,8 @@ export async function visibleResume(targetGardenId, deps) {
         }
         if (identity.backend === "claude-code")
             return await resumeClaudeCode(targetGardenId, identity, deps);
+        if (identity.backend === "pi-durable")
+            return await resumePiDurable(targetGardenId, deps);
         // Liveness preflight, still under the lock. A live citizen is addressed with
         // `entwurf_v2 fire-and-forget`, not reopened — and refusing here is also what stops two
         // windows existing for one garden id.
@@ -261,9 +297,14 @@ export async function visibleResume(targetGardenId, deps) {
             provider: identity.provider,
             model: identity.model,
         });
-        const launched = deps.launch({ backend: "pi", cwd: identity.cwd, runtimeArgs });
-        if (!launched.ok) {
-            return { ok: false, reason: "launch-refused", detail: `${launched.reason} — ${launched.hint}` };
+        const launched = await deps.launch({ backend: "pi", cwd: identity.cwd, runtimeArgs });
+        if (!launched.ok)
+            return launchNotLaunched(launched);
+        // Only a pi-durable launch carries a layout handle (#157 B3). Handed to a pi resume, it is a
+        // wiring defect, not an outcome: whatever was opened stays as it is and the lock is released.
+        if (launched.handle.rail === "herdr-layout" || launched.handle.rail === "herdr-layout-claude") {
+            throw new Error(`entwurf-v2-visible-resume: the launcher handed a pi resume of ${targetGardenId} a ${launched.handle.rail} handle — ` +
+                `only a pi-durable or Claude Code resume launches through layout.apply. Nothing was observed or closed.`);
         }
         const observation = await observeSameGidSocket(targetGardenId, mapped.socketPath, deps);
         return {
@@ -276,6 +317,19 @@ export async function visibleResume(targetGardenId, deps) {
         release();
     }
 }
+/**
+ * A launch that did not become a launch, kept in its own shape. A refusal created nothing and is
+ * `launch-refused`. A failure that carries what it created (herdr: after the tab create) is
+ * `launch-failed`, with the vendor code, recovery and coordinates passed through untouched — folding
+ * it into a refusal is what would print "No window was opened" over a tab that may be on screen.
+ * Neither is retried, and neither is followed by an observation.
+ */
+function launchNotLaunched(launched, note = "") {
+    const detail = `${launched.reason} — ${launched.hint}${note}`;
+    return "failure" in launched
+        ? { ok: false, reason: "launch-failed", detail, failure: launched.failure }
+        : { ok: false, reason: "launch-refused", detail };
+}
 /**
  * The Claude Code half, still under the caller's lock. Dormancy needs a DEAD owner verdict on the
  * receiver marker AND the binding: the record re-read AFTER that verdict must still name the same
@@ -357,26 +411,255 @@ async function resumeClaudeCode(targetGardenId, identity, deps) {
                 `after the dead owner's, and its process is not proven gone`,
         };
     }
-    const launched = deps.launch({
+    const launched = await deps.launch({
         backend: "claude-code",
         cwd: current.cwd,
         runtimeArgs: ["--resume", current.nativeSessionId],
     });
+    if (!launched.ok)
+        return launchNotLaunched(launched);
+    // The observation below joins the receiver marker's owner to the pane's DIRECT child: tmux's pane
+    // pid, or herdr's process report for the layout pane (#157 stage 4). A handle of any other rail
+    // carries no such pid, so it is a wiring defect, not an outcome: it fails loud rather than watching
+    // for a pid that does not exist. Whatever that launcher opened is left as it is; the lock is still
+    // released.
+    const handle = launched.handle;
+    if (handle.rail !== "tmux" && handle.rail !== "herdr-layout-claude") {
+        throw new Error(`entwurf-v2-visible-resume: the launcher handed a Claude Code resume of ${targetGardenId} a ${handle.rail} ` +
+            `handle — its observation joins the opened pane's direct child, which that rail does not carry. Nothing was ` +
+            `observed or closed.`);
+    }
+    const launch = { backend: "claude-code", targetGardenId, nativeSessionId: current.nativeSessionId, handle };
+    // herdr did not name the new pane's direct child: there is nothing to join, so no wait runs. The tab
+    // is open; nothing is retried or closed.
+    if (handle.rail === "herdr-layout-claude" && "unread" in handle.paneChild) {
+        return {
+            ok: true,
+            launch,
+            observation: { kind: "pane-process-unread", cause: handle.paneChild.unread, waitedMs: 0 },
+        };
+    }
+    const panePid = handle.rail === "tmux" ? handle.panePid : handle.paneChild.pid;
+    const observation = await observeReceiverReattached(targetGardenId, current, { ownerPid: marker.ownerPid, ownerStartKey: marker.ownerStartKey, attachIncarnation: current.attachIncarnation }, panePid, deps);
+    return { ok: true, launch, observation };
+}
+/**
+ * #157 B3: the adopt launch for ONE reservation — the managed verb with its closed context
+ * `{v:1, gardenId, metaRoot, sourceGeneration}` (no session, cwd, profile, model, prompt, module,
+ * nonce or callback rides it), the reservation's cwd, and the fixed five-name projection of its raw
+ * profile and its meta root. Pure: it reads nothing and writes nothing.
+ */
+export function buildPiDurableAdoptLaunch(reservation) {
+    const { metaRoot } = reservation;
+    const context = {
+        v: 1,
+        gardenId: reservation.gardenId,
+        metaRoot,
+        sourceGeneration: reservation.generation,
+    };
+    return {
+        backend: "pi-durable",
+        cwd: reservation.cwd,
+        runtimeArgs: ["pi-durable", "--entwurf-adopt", JSON.stringify(context)],
+        piDurableAdoptEnv: {
+            PI_CODING_AGENT_DIR: reservation.profile,
+            ENTWURF_META_SESSIONS_DIR: path.join(metaRoot, "meta-sessions"),
+            ENTWURF_META_MAILBOX_DIR: path.join(metaRoot, "meta-mailbox"),
+            ENTWURF_META_SENDERS_DIR: path.join(metaRoot, "meta-senders"),
+            ENTWURF_META_RECEIVERS_DIR: path.join(metaRoot, "meta-receivers"),
+        },
+    };
+}
+/**
+ * A reserve refusal this verb answers by name; every other fence refusal keeps its own cause. A live holder is not
+ * an address (S3 joint review D4): a reservation's parent is a bridge waiting for a child, which entwurf_v2 cannot
+ * reach, and any other live holder is a process this verb did not judge contact-ready — so neither answer tells the
+ * caller to send. The branch reads the refusal's structured holder state, never its message.
+ */
+function piDurableReserveRefusal(targetGardenId, err) {
+    if (err.reason === "owner-live") {
+        if (err.holderState === "reserved") {
+            return {
+                ok: false,
+                reason: "target-live",
+                detail: `${targetGardenId}'s pi-durable session is reserved for a child to adopt by a live process (${err.message}); ` +
+                    `while that reservation stays unadopted under that live process a resume of ${targetGardenId} refuses on it; ` +
+                    `nothing clears it automatically, a child that adopts it becomes its holder, and entwurf_v2 does not reach a reservation`,
+            };
+        }
+        return {
+            ok: false,
+            reason: "target-live",
+            detail: `${targetGardenId}'s pi-durable session is held by a live process (${err.message}); if that process is the ` +
+                `running citizen, entwurf_v2 reaches it only through the rail its own dispatch decides`,
+        };
+    }
+    if (err.reason === "owner-uncertain" || err.reason === "owner-other-host") {
+        return {
+            ok: false,
+            reason: "target-indeterminate",
+            detail: `the holder of ${targetGardenId}'s pi-durable session could not be proven gone on this host (${err.message}), ` +
+                `and resuming a session that is still open would put two processes on one transcript`,
+        };
+    }
+    return null;
+}
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * A reserve whose write committed and whose lock release then failed (S3 joint review D3). It says only what that
+ * call wrote and what its holder implies; the release's own words say what it left. Nothing is withdrawn, retried
+ * or repaired here.
+ */
+function piDurableReservedThenFailed(targetGardenId, err, written) {
+    const residue = err.reason === "tx-release-failed"
+        ? `; if the transaction file that release named remains, that process ending does not remove it, and it fails closed until an operator removes it`
+        : "";
+    return (`entwurf-v2-visible-resume: the reserve of ${targetGardenId} WROTE its reservation of ${written.resource} at ` +
+        `generation ${written.generation} for pid ${written.ownerPid}, then a lock release failed (${err.message}). ` +
+        `Nothing was launched and nothing withdrew that reservation: while it stays unadopted under live pid ` +
+        `${written.ownerPid}, a resume of ${targetGardenId} refuses, and nothing clears it automatically${residue}`);
+}
+/**
+ * A withdrawal that failed (S3 joint review D1). Only what the failure itself records is stated: a write this call
+ * made, or a transaction file the release left; any other failure leaves the claim's state unestablished here.
+ */
+function piDurableWithdrawFailed(targetGardenId, held, reservation, err) {
+    const residue = `if that transaction file remains, this process ending does not remove it, and it fails closed until an operator removes it`;
+    if (err instanceof PiDurableOwnerFenceError && err.written !== undefined) {
+        return (` — this call wrote the withdrawal of ${held} (the claim back to the donor's ${err.written.state} row at ` +
+            `generation ${err.written.generation}), then releasing its transaction failed (${err.message}); ${residue}`);
+    }
+    if (err instanceof PiDurableOwnerFenceError && err.reason === "tx-release-failed") {
+        return (` — withdrawing ${held} FAILED at its transaction release (${err.message}); whether this call ` +
+            `wrote anything is not recorded, and ${residue}`);
+    }
+    return (` — withdrawing ${held} FAILED (${messageOf(err)}); what its claim holds now is not established here: while it ` +
+        `stays reserved, unadopted, under this live process (pid ${reservation.owner.pid}), a resume of ${targetGardenId} ` +
+        `refuses`);
+}
+/**
+ * The pi-durable half (#157 B3), still under the caller's per-target lock, which stays the outer
+ * scope: the reserve takes record-arm then S_D itself and releases both before it returns, so before
+ * any launch. A reserve that refuses on eligibility writes nothing; a reserve whose lock release fails AFTER its
+ * write is named as such (its `written`), with the reservation it left. Neither opens anything.
+ *
+ * From the reservation on, this process holds D for one child, and what happens to that hold is
+ * decided by the launch outcome alone (L3-A1 §6), never by a guess:
+ *
+ *   no launch request was made                         definitely none created → withdraw
+ *   the seam refused (`ok:false`, no `failure`)        the seam's contract: refused before anything was
+ *                                                      created (tmux: one of its named reasons; herdr:
+ *                                                      decided before the layout write) → withdraw
+ *   a failure whose recovery is `none`                 that rail's own none-created certainty → withdraw
+ *   a failure whose recovery is anything else          something MAY exist → the reservation is KEPT
+ *   the launcher threw                                 unknown, whatever its position → KEPT
+ *   a launch                                           a child may adopt it → KEPT, then observed once
+ *
+ * A withdrawal that fails is reported with the refusal it followed and is never retried. A kept
+ * reservation is said so in the answer: it names this process as its holder, and while it stays unadopted
+ * under this live process a later resume of the same id refuses; nothing clears it automatically, and a
+ * child that adopts it becomes its holder.
+ */
+async function resumePiDurable(targetGardenId, deps) {
+    let reservation;
+    try {
+        reservation = await deps.reservePiDurable(targetGardenId);
+    }
+    catch (err) {
+        if (err instanceof PiDurableOwnerFenceError) {
+            const refused = piDurableReserveRefusal(targetGardenId, err);
+            if (refused !== null)
+                return refused;
+            // A release that failed after the reservation was WRITTEN (S3 joint review D3): the reservation exists,
+            // so the answer names it and what it blocks, beside the release's own cause; nothing launches or withdraws.
+            if (err.written !== undefined)
+                throw new Error(piDurableReservedThenFailed(targetGardenId, err, err.written));
+        }
+        throw err;
+    }
+    const held = `${targetGardenId}'s reservation of ${reservation.resource} at generation ${reservation.generation}`;
+    const withdraw = async () => {
+        try {
+            await deps.withdrawPiDurable(reservation);
+            return ` — ${held} was withdrawn, since nothing was created`;
+        }
+        catch (err) {
+            return piDurableWithdrawFailed(targetGardenId, held, reservation, err);
+        }
+    };
+    const kept = ` — ${held} was KEPT, because something may exist that can still adopt it; it names this process ` +
+        `(pid ${reservation.owner.pid}) as its holder: while it stays unadopted under this live process a resume of ` +
+        `${targetGardenId} refuses, nothing clears it automatically, and a child that adopts it becomes its holder`;
+    let input;
+    try {
+        input = buildPiDurableAdoptLaunch(reservation);
+    }
+    catch (err) {
+        throw new Error(`entwurf-v2-visible-resume: ${messageOf(err)}${await withdraw()}`);
+    }
+    let launched;
+    try {
+        launched = await deps.launch(input);
+    }
+    catch (err) {
+        throw new Error(`entwurf-v2-visible-resume: the pi-durable launch of ${targetGardenId} threw: ${messageOf(err)}${kept}`);
+    }
     if (!launched.ok) {
-        return { ok: false, reason: "launch-refused", detail: `${launched.reason} — ${launched.hint}` };
+        const noneCreated = !("failure" in launched) || launched.failure.recovery.outcome === "none";
+        return launchNotLaunched(launched, noneCreated ? await withdraw() : kept);
+    }
+    // A herdr agent-start handle belongs to the pi rail only: a pi-durable resume launches through
+    // tmux or ONE layout.apply. Handed one, it is a wiring defect; what was opened stays as it is.
+    if (launched.handle.rail === "herdr" || launched.handle.rail === "herdr-layout-claude") {
+        throw new Error(`entwurf-v2-visible-resume: the launcher handed a pi-durable resume of ${targetGardenId} a ` +
+            `${launched.handle.rail === "herdr" ? "herdr agent-start" : launched.handle.rail} handle — nothing was observed or closed${kept}`);
     }
-    const observation = await observeReceiverReattached(targetGardenId, current, { ownerPid: marker.ownerPid, ownerStartKey: marker.ownerStartKey, attachIncarnation: current.attachIncarnation }, launched.handle.panePid, deps);
+    const observation = await observePiDurableAdoption(reservation, deps);
     return {
         ok: true,
         launch: {
-            backend: "claude-code",
+            backend: "pi-durable",
             targetGardenId,
-            nativeSessionId: current.nativeSessionId,
+            cwd: reservation.cwd,
+            reservation: {
+                generation: reservation.generation,
+                resource: reservation.resource,
+                ownerPid: reservation.owner.pid,
+            },
             handle: launched.handle,
         },
         observation,
     };
 }
+/**
+ * ONE bounded operation, the pi-durable twin of `observeSameGidSocket` (#157 B3): read the
+ * reservation's D claim until a child's adoption write carries its generation, the claim is lost or
+ * unreadable, or the same fixed wait ends. Every read is the fence's strict reader; nothing here
+ * writes, withdraws, retries or watches past the deadline. A read that throws past that reader stops
+ * the wait as `unobserved` with its cause: the window is open, and the launch receipt must survive.
+ */
+export async function observePiDurableAdoption(reservation, deps, timeoutMs = RESUME_OBSERVE_TIMEOUT_MS, intervalMs = RESUME_OBSERVE_INTERVAL_MS) {
+    const started = deps.now();
+    for (;;) {
+        let seen;
+        try {
+            seen = deps.observePiDurable(reservation);
+        }
+        catch (err) {
+            return { kind: "unobserved", reason: "observe-threw", detail: messageOf(err), waitedMs: deps.now() - started };
+        }
+        if (seen.class === "adopted")
+            return { kind: "adopted", waitedMs: deps.now() - started };
+        if (seen.class === "lost")
+            return { kind: "reservation-lost", waitedMs: deps.now() - started };
+        if (seen.class === "unobserved") {
+            return { kind: "unobserved", reason: seen.reason, detail: seen.detail, waitedMs: deps.now() - started };
+        }
+        if (deps.now() - started >= timeoutMs)
+            return { kind: "not-yet-adopted", waitedMs: deps.now() - started };
+        await deps.sleep(intervalMs);
+    }
+}
 /**
  * ONE bounded operation, the Claude Code twin of `observeSameGidSocket`: wait for a NEW live owner
  * — in the pane this call opened (`panePid`), a join, not an address — to re-arm this garden id's
@@ -470,18 +753,29 @@ const REJECT_HINT = {
  */
 export function renderVisibleResume(result, attribution = { actor: null }) {
     if (!result.ok) {
+        if (result.reason === "launch-failed")
+            return renderLaunchFailed(result);
         return {
             text: `entwurf_resume_call rejected: ${result.reason} — ${REJECT_HINT[result.reason]}. ` +
                 `${result.detail}. No window was opened.`,
             isError: true,
         };
     }
-    const h = result.launch.handle;
     // Who asked is recorded, and it is not authority: the verb decides from the target's record and
     // live rail facts alone, whoever the caller is.
     const actor = attribution.actor === null
         ? `  actor:    unattributed (the caller has no record-backed garden identity)\n`
         : `  actor:    ${attribution.actor} (record-backed caller; attribution, not authority)\n`;
+    // #157 B3: pi-durable has its own receipts (a reservation, an adoption), on either rail.
+    if (result.launch.backend === "pi-durable") {
+        return renderPiDurableResume(result.launch, result.observation, actor);
+    }
+    const h = result.launch.handle;
+    // The herdr rail has its own coordinates and its own words; the tmux text below stays as it was.
+    if (h.rail === "herdr")
+        return renderHerdrPiResume(result, h, actor);
+    if (h.rail === "herdr-layout-claude")
+        return renderHerdrClaudeResume(result, h, actor);
     const window = `  runtime:  ${h.runtimePath} (requested start cwd ${h.cwd})\n` +
         `  window:   ${h.windowId} (index ${h.windowIndex}) in session ${h.sessionId}\n` +
         `  pane:     ${h.paneId} pid ${h.panePid}\n`;
@@ -532,3 +826,174 @@ export function renderVisibleResume(result, attribution = { actor: null }) {
         isError: false,
     };
 }
+/**
+ * The pi-durable resume (#157 B3), on tmux or on herdr's one layout.apply. Three facts kept apart: the
+ * reservation this process holds, the LAUNCH that was asked to adopt it, and what the D claim said
+ * after one bounded read. `adopted` says a child wrote its adoption — not that it is ready, alive,
+ * attached, addressable or that anything was recalled; entwurf_peers is where its rail is read.
+ */
+function renderPiDurableResume(launch, observation, actor) {
+    const h = launch.handle;
+    const place = h.rail === "tmux" ? "window" : "tab";
+    const where = h.rail === "tmux"
+        ? `  runtime:  ${h.runtimePath} pi-durable --entwurf-adopt (requested start cwd ${h.cwd})\n` +
+            `  window:   ${h.windowId} (index ${h.windowIndex}) in session ${h.sessionId}\n` +
+            `  pane:     ${h.paneId} pid ${h.panePid}\n`
+        : `  runtime:  ${h.runtime} pi-durable --entwurf-adopt (requested start cwd ${h.cwd})\n` +
+            `  tab:      ${h.herdrTabId} in workspace ${h.herdrWorkspaceId} — a NEW tab from ONE layout.apply, opened without taking focus\n` +
+            `  pane:     ${h.herdrPaneId} — herdr VIEW coordinates, not an address\n`;
+    const r = launch.reservation;
+    const heldBy = `this process (pid ${r.ownerPid})`;
+    const observed = observation.kind === "adopted"
+        ? `OBSERVATION receipt: adopted — after ${observation.waitedMs}ms the claim of ${r.resource} carries generation ` +
+            `${r.generation} as its adoptedFrom: a child process wrote its adoption of this reservation. That is not ` +
+            `readiness, liveness, an attach, a turn or a recall — entwurf_peers shows whether its rail answers. This ` +
+            `call submitted no prompt.`
+        : observation.kind === "not-yet-adopted"
+            ? `OBSERVATION receipt: not-yet-adopted — after ${observation.waitedMs}ms the claim of ${r.resource} was still ` +
+                `this reservation. The ${place} is open and visible; read it directly. The reservation stays held by ` +
+                `${heldBy}: a child there can still adopt it and become its holder; while it stays unadopted under this live ` +
+                `process a resume of ${launch.targetGardenId} refuses, and nothing clears it automatically. Nothing was ` +
+                `retried, withdrawn or killed.`
+            : observation.kind === "reservation-lost"
+                ? `OBSERVATION receipt: reservation-lost — after ${observation.waitedMs}ms the claim of ${r.resource} ` +
+                    `names neither this reservation nor an adoption of it (another owner, a reclaim or a withdrawal ` +
+                    `replaced it). The ${place} is open; read it directly. Nothing was retried or killed.`
+                : `OBSERVATION receipt: unobserved — the claim of ${r.resource} could not be read after ` +
+                    `${observation.waitedMs}ms (${observation.reason}: ${observation.detail}). The ${place} is open and ` +
+                    `visible; nothing was retried, withdrawn or killed.`;
+    return {
+        text: `[entwurf resume call ↻${h.rail === "tmux" ? "" : " herdr"}]\n` +
+            `  target:   ${launch.targetGardenId}\n` +
+            `  backend:  pi-durable\n` +
+            `  reserved: ${r.resource} at generation ${r.generation}, held by ${heldBy} for one child to adopt\n` +
+            where +
+            actor +
+            `\n` +
+            `LAUNCH receipt: ${h.rail === "tmux" ? "tmux created that window" : "herdr created that tab"} and was asked to ` +
+            `start the managed entwurf pi-durable with the closed adopt context of the reservation above, its raw ` +
+            `profile as PI_CODING_AGENT_DIR and its meta root's four ENTWURF_META_*_DIR children as its launch env, ` +
+            `in the record's cwd.\n` +
+            observed,
+        isError: false,
+    };
+}
+/**
+ * The pi resume on the herdr rail (#157 G1a). Same two receipts, kept apart the same way; the
+ * coordinates are herdr's VIEW of a tab, and herdr's own readiness or session report is not consulted
+ * — the same-gid control socket is the observation on both rails.
+ */
+function renderHerdrPiResume(result, h, actor) {
+    if (result.launch.backend !== "pi") {
+        throw new Error("entwurf-v2-visible-resume: a herdr launch handle arrived on a non-pi resume — only a pi resume renders through the herdr agent-start view");
+    }
+    const observation = result.observation;
+    const observed = observation.kind === "socket-alive";
+    return {
+        text: `[entwurf resume call ↻ herdr]\n` +
+            `  target:   ${result.launch.targetGardenId}\n` +
+            `  session:  ${result.launch.sessionFile}\n` +
+            `  runtime:  requested kind ${h.requestedKind} — herdr resolves the executable, we did not (requested start cwd ${h.cwd})\n` +
+            `  tab:      ${h.herdrTabId} in workspace ${h.herdrWorkspaceId} — a NEW tab beside the caller's, opened without taking focus\n` +
+            `  pane:     ${h.herdrPaneId} terminal ${h.herdrTerminalId} — herdr VIEW coordinates, not an address\n` +
+            `  agent:    ${h.herdrAgentName} (herdr's name for this launch, random per call)\n` +
+            actor +
+            `\n` +
+            `LAUNCH receipt: herdr created that tab and was asked to start pi on the transcript above.\n` +
+            (observed
+                ? `OBSERVATION receipt: the control socket for ${result.launch.targetGardenId} answered after ` +
+                    `${observation.waitedMs}ms — that citizen is addressable again, and entwurf_v2 fire-and-forget ` +
+                    `now reaches it. No turn was run by this call. herdr's own agent status was not consulted.`
+                : `OBSERVATION receipt: resume-unobserved — the control socket did not answer within ` +
+                    `${observation.waitedMs}ms. The tab is open and visible; read it directly. The lock was ` +
+                    `released, nothing was retried, and nothing was closed.`),
+        isError: false,
+    };
+}
+/**
+ * The Claude Code resume on the herdr rail (#157 stage 4). The same two receipts as on tmux, kept
+ * apart the same way. The tab and pane are herdr's VIEW; the pane's direct child is herdr's process
+ * report for the pane this call created — the pid the observation joins, never an address.
+ */
+function renderHerdrClaudeResume(result, h, actor) {
+    if (result.launch.backend !== "claude-code") {
+        throw new Error("entwurf-v2-visible-resume: a herdr Claude Code launch handle arrived on a non-Claude Code resume");
+    }
+    const target = result.launch.targetGardenId;
+    const observation = result.observation;
+    const child = "pid" in h.paneChild
+        ? `pid ${h.paneChild.pid} (herdr's process report for that pane; a join, not an address)`
+        : `unread — ${h.paneChild.unread}`;
+    const left = "The tab is open and visible; read it directly. The lock was released, nothing was retried, and nothing was closed.";
+    return {
+        text: `[entwurf resume call ↻ herdr]\n` +
+            `  target:   ${target}\n` +
+            `  backend:  claude-code\n` +
+            `  session:  ${result.launch.nativeSessionId}\n` +
+            `  runtime:  ${h.runtime} --resume — herdr resolved the executable, we did not (requested start cwd ${h.cwd})\n` +
+            `  tab:      ${h.herdrTabId} in workspace ${h.herdrWorkspaceId} — a NEW tab from ONE layout.apply, opened without taking focus\n` +
+            `  pane:     ${h.herdrPaneId} — herdr VIEW coordinates, not an address\n` +
+            `  child:    ${child}\n` +
+            actor +
+            `\n` +
+            `LAUNCH receipt: herdr created that tab and was asked to start claude --resume on the session above.\n` +
+            (observation.kind === "receiver-armed"
+                ? `OBSERVATION receipt: receiver-armed — a NEW live Claude Code process, the direct child of the pane this ` +
+                    `call opened (pid ${observation.ownerPid}), re-armed the receiver marker of ${target} for the same session ` +
+                    `after ${observation.waitedMs}ms, with a fresh arm binding the record also carries (same createdAt). ` +
+                    `entwurf_v2 fire-and-forget now reaches its mailbox. This call submitted no prompt; the runtime's own ` +
+                    `activity after resume (e.g. a doorbell on unread mail) is unmeasured.`
+                : observation.kind === "pane-process-unread"
+                    ? `OBSERVATION receipt: pane-process-unread — herdr did not report the direct child of the pane this ` +
+                        `call opened (${observation.cause}), so no receiver marker could be joined to it and no wait ran. ${left}`
+                    : observation.kind === "record-unreadable"
+                        ? `OBSERVATION receipt: record-unreadable — the record of ${target} could not be read after ` +
+                            `${observation.waitedMs}ms: ${observation.cause}. ${left}`
+                        : `OBSERVATION receipt: resume-unobserved — no new live receiver marker from the direct child of the pane ` +
+                            `this call opened, bound to the record, appeared within ${observation.waitedMs}ms. ${left}`),
+        isError: false,
+    };
+}
+/**
+ * A launch that failed after it created something. The header claims no more than the recovery
+ * knows — the fresh herdr rail learned that the hard way: `none` means herdr declined by name before
+ * making anything, `unknown` means no answer we can act on so a tab MAY exist, and anything else means
+ * the tab was created and the recovery says whether its pane was closed. No observation ran, so this
+ * says nothing about whether the citizen came back.
+ */
+function renderLaunchFailed(result) {
+    const f = result.failure;
+    const tabHeader = f.recovery.outcome === "none"
+        ? "entwurf_resume_call failed at the herdr tab create step"
+        : f.recovery.outcome === "unknown"
+            ? "entwurf_resume_call failed at the herdr tab create step with an UNKNOWN outcome"
+            : "entwurf_resume_call failed after the herdr tab was created";
+    // #157 B3: the pi-durable rail asks herdr for ONE layout.apply. Its classifier answers only none or
+    // unknown, so anything but none is UNKNOWN, and there is no tab create step to name.
+    const layout = f.rail === "herdr-layout";
+    const header = layout
+        ? `entwurf_resume_call failed at the herdr layout.apply step${f.recovery.outcome === "none" ? "" : " with an UNKNOWN outcome"}`
+        : tabHeader;
+    const code = f.vendorCode === undefined ? "" : ` [herdr: ${f.vendorCode}]`;
+    const created = f.created === undefined
+        ? ""
+        : `  created:  tab ${f.created.herdrTabId} in workspace ${f.created.herdrWorkspaceId}, pane ${f.created.herdrPaneId} ` +
+            `terminal ${f.created.herdrTerminalId} — herdr VIEW coordinates, not an address\n`;
+    const recovery = f.recovery.outcome === "none"
+        ? layout
+            ? "  recovery: none — the layout request was never written, or herdr declined it by name before making anything, so there is nothing to go look at\n"
+            : "  recovery: none — herdr declined by name before making anything, so there is nothing to go look at\n"
+        : f.recovery.outcome === "unknown"
+            ? "  recovery: UNKNOWN — we never got an answer we can act on, so a tab MAY exist that this call cannot name. Nothing was closed; check herdr\n"
+            : f.recovery.outcome === "closed"
+                ? `  recovery: closed ${f.recovery.paneId} (its terminal still matched the create receipt; the new tab went with it unless something else had joined it)\n`
+                : `  recovery: orphan-unreclaimed:${f.recovery.reason} (${f.recovery.paneId}) — this pane was NOT closed, on purpose\n`;
+    return {
+        text: `${header}: ${result.detail}.${code}\n` +
+            created +
+            recovery +
+            `No observation was attempted, so this says nothing about whether the citizen came back — entwurf_peers ` +
+            `shows whether its ${layout ? "rail" : "control socket"} answers. The lock was released and nothing was retried.`,
+        isError: true,
+    };
+}