@junghanacs/entwurf 0.45.0 → 0.50.0

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

@@ -41,30 +41,37 @@
  * not allowed to turn one into the other.
  */
 import { createHash } from "node:crypto";
-import { statSync } from "node:fs";
+import { accessSync, constants as fsConstants, statSync } from "node:fs";
+import { createConnection } from "node:net";
 import path from "node:path";
-import { HERDR_FRESH_CALL_BACKENDS } from "../../scripts/herdr-rails.mjs";
+import { HERDR_AGENT_START_BACKENDS, HERDR_FRESH_CALL_BACKENDS, HERDR_LAYOUT_LAUNCH_BACKENDS, } from "../../scripts/herdr-rails.mjs";
 import { callbackEnvAssignments } from "./callback-env.js";
-import { buildOmpBootstrapPayload, composeBackendArgs, composeFreshCallFraming, FRESH_CALL_PROVIDER_HINT, normalizeFreshCallInputs, TASK_MAX_CHARS, } from "./fresh-call-composition.js";
+import { buildOmpBootstrapPayload, composeBackendArgs, composeFreshCallFraming, composeFreshCallPrompt, FRESH_CALL_PROVIDER_HINT, normalizeFreshCallInputs, OMP_BOOTSTRAP_VERSION, TASK_MAX_CHARS, } from "./fresh-call-composition.js";
+import { PI_DURABLE_PREFLIGHT_HINT, piDurableFreshPreflight, } from "./pi-durable-fresh-preflight.js";
+import { checkPiDurableRuntime, PI_DURABLE_RUNTIME_HINT, piDurablePackageLayout, } from "./pi-durable-runtime.js";
 /**
- * The pilot set, closed. `[#116 decision]` herdr's own `--kind` enum is much larger, and that is
- * NOT evidence of support: every other backend is a pre-mutation named reject here, and there is
- * no fallback to the tmux rail — a caller inside herdr who asks for codex gets a refusal, not a
- * window somewhere else.
+ * Three closed sets, one leaf. `[#116 decision]` herdr's own `--kind` enum is much larger, and that
+ * is NOT evidence of support. Since #157 A-L1 the rail has two launch domains — the agent-start set
+ * (pi, claude-code: `tab create` + `agent start --kind`) and the layout set (pi-durable: one
+ * `layout.apply`) — and admits exactly their union: every backend outside it is a pre-mutation
+ * named reject, with no fallback to the tmux rail — a caller inside herdr who asks for codex gets a
+ * refusal, not a window somewhere else.
  *
- * The VALUE now lives in `scripts/herdr-rails.mjs`, the one leaf the status pane and the install
- * narration also read (#116 A7), so a fourth backend cannot appear in prose on one surface while
- * this rail still refuses it. The re-export keeps this module's public name unchanged. The TYPE
- * still has to be a tuple: a `.mjs` leaf infers `readonly string[]` without the JSDoc cast there,
- * and `HerdrFreshCallBackend` would silently widen to `string` while every runtime check still
- * passed. A gate pins that.
+ * The VALUES live in `scripts/herdr-rails.mjs` (#116 A7). The status pane's RAILS block renders
+ * the agent-start and layout sets as two groups (#157 A-L2); the install narration covers only the
+ * integrations it activated, which pi-durable never is. The re-export keeps this module's
+ * public names. The TYPES still have to be tuples: a `.mjs` leaf infers `readonly string[]` without
+ * the JSDoc cast there, and these types would silently widen to `string` while every runtime check
+ * still passed. A gate pins that.
  */
-export { HERDR_FRESH_CALL_BACKENDS };
+export { HERDR_AGENT_START_BACKENDS, HERDR_FRESH_CALL_BACKENDS, HERDR_LAYOUT_LAUNCH_BACKENDS };
 /** Our backend name → the `--kind` token herdr accepts. `[측정 2026-09-14]` both round-tripped with
  * the vendor executable echoed back in `argv`. This is a REQUESTED kind: `[file:line @ c77af189]`
  * `src/app/agents.rs:197-199` turns it into a bare executable name and writes it into the pane's
  * shell, so nothing here has proven the binary exists, is on PATH, or will start. Runtime failure
- * is a post-mutation outcome on this rail, named as such, never a precondition we can claim. */
+ * is a post-mutation outcome on this rail, named as such, never a precondition we can claim.
+ * Keyed by the agent-start domain ONLY: a layout-launched backend has no kind, and inventing one
+ * would start herdr's program for that kind under another backend's name. */
 export const HERDR_AGENT_KIND = {
     pi: "pi",
     "claude-code": "claude",
@@ -503,7 +510,7 @@ export function decideConditionalClose(created, current, getFailed) {
  * `callerGardenId` comes from the SURFACE that registered the tool, out of its own record-backed
  * context. This module never derives it, looks it up, or guesses: an empty value is a refusal.
  */
-export async function herdrFreshCall(params, run, env, nonce, clock = HERDR_REAL_CLOCK) {
+export async function herdrFreshCall(params, run, env, nonce, clock = HERDR_REAL_CLOCK, layoutDeps = {}) {
     const context = resolveHerdrContext(env);
     if (!context.ok)
         return { ok: false, reason: context.reason };
@@ -515,20 +522,36 @@ export async function herdrFreshCall(params, run, env, nonce, clock = HERDR_REAL
         // worse than a refusal they can read.
         return { ok: false, reason: "herdr-backend-unsupported" };
     }
+    if (HERDR_LAYOUT_LAUNCH_BACKENDS.includes(params.backend)) {
+        // #157 A-L1: a backend herdr has no kind for. It never reaches `tab create`/`agent start`
+        // below and never runs the herdr CLI; its own branch owns its whole order.
+        return herdrLayoutFreshCall(params, context.context, env, nonce, {
+            ...HERDR_LAYOUT_PRODUCTION_DEPS,
+            ...layoutDeps,
+        });
+    }
     const backend = params.backend;
     // The caller's inputs are judged by the SHARED contract — same order, same trimming, same
     // five words — so a caller cannot learn a different vocabulary by being inside herdr. The
-    // cwd omission rule comes with it: `undefined` and `""` both mean "no cwd", which this rail
-    // previously mistook for an invalid path.
+    // cwd omission rule comes with it: `undefined` and `""` both mean "no cwd requested", which this
+    // rail once mistook for an invalid path. An omitted cwd means the CALLER's directory, chosen by
+    // the same helper the layout branch uses (#157 A-L1x), and is always sent explicitly: herdr's own
+    // default for an omitted `--cwd` is herdr's, not a fact about the caller.
     const normalized = normalizeFreshCallInputs(params);
     if (!normalized.ok)
         return { ok: false, reason: normalized.reason };
-    const { callerGardenId, model, task, cwd } = normalized.inputs;
-    if (cwd !== undefined) {
-        const badCwd = classifyHerdrCwd(cwd);
-        if (badCwd !== null)
-            return { ok: false, reason: badCwd };
-    }
+    const { callerGardenId, model, task, cwd: requestedCwd } = normalized.inputs;
+    const chosenCwd = chooseHerdrLayoutCwd({
+        ...(requestedCwd === undefined ? {} : { requestedCwd }),
+        callerIsCodex: params.callerIsCodex === true,
+        ...(params.callerCwd === undefined ? {} : { callerCwd: params.callerCwd }),
+        callerProcessCwd: layoutDeps.callerProcessCwd ?? HERDR_LAYOUT_PRODUCTION_DEPS.callerProcessCwd,
+    });
+    if (!chosenCwd.ok)
+        return { ok: false, reason: chosenCwd.reason };
+    const badCwd = classifyHerdrCwd(chosenCwd.cwd);
+    if (badCwd !== null)
+        return { ok: false, reason: badCwd };
     const framing = composeFreshCallFraming({
         backend,
         callerGardenId,
@@ -576,7 +599,7 @@ export async function herdrFreshCall(params, run, env, nonce, clock = HERDR_REAL
     // ── everything above this line leaves nothing behind ──────────────────────────────────
     const tabRun = await run(buildHerdrTabCreateArgs({
         workspaceId: callerPane.workspaceId,
-        ...(cwd === undefined ? {} : { cwd }),
+        cwd: chosenCwd.cwd,
         callback: { target: callerGardenId, nonce },
     }));
     if (tabRun.status !== 0) {
@@ -665,7 +688,8 @@ export async function herdrFreshCall(params, run, env, nonce, clock = HERDR_REAL
             backend,
             requestedKind: HERDR_AGENT_KIND[backend],
             model,
-            ...(cwd === undefined ? {} : { cwd }),
+            cwd: chosenCwd.cwd,
+            cwdSource: chosenCwd.source,
             herdrAgentName: agentName,
             // The tab coordinates come from the reply that CREATED them, not from the start's
             // echo: the create receipt is what the reclaim above is bound to, so the receipt an
@@ -771,8 +795,13 @@ export async function settleAgentWitness(params) {
         }
     }
 }
-/** Reclaim the pane we opened — conditionally, or not at all. */
-async function reclaim(pane, run) {
+/** Reclaim the pane we opened — conditionally, or not at all.
+ *
+ * Exported for the ONE other herdr launch that creates a tab and can fail after it: the same-id pi
+ * resume (`herdr-resume-call.ts`, #157 G1a). It is the existing within-generation witness
+ * (`decideConditionalClose`) plus the one pane close, reused rather than copied, so the two herdr
+ * launches cannot drift into different ideas of what may be closed. */
+export async function reclaim(pane, run) {
     const getRun = await run(buildHerdrPaneGetArgs(pane.paneId));
     const decision = decideConditionalClose(pane, getRun.status === 0 ? parseHerdrPaneGetResponse(getRun.stdout) : null, getRun.status !== 0);
     if (!decision.close)
@@ -782,12 +811,477 @@ async function reclaim(pane, run) {
         return { outcome: "orphan-unreclaimed", paneId: pane.paneId, reason: "close-failed" };
     return { outcome: "closed", paneId: pane.paneId, terminalId: pane.terminalId };
 }
+// ── #157 A-L1: pi-durable through ONE layout.apply on the caller's own herdr socket ──────────────
+//
+// WHY A SOCKET AND NOT THE CLI. The documented herdr CLI exposes no layout mutation, and
+// `layout.apply` is the only herdr surface that execs an argv VECTOR in a new tab — no `--kind`, no
+// shell, no PTY keystrokes (`[blob 2ecf19a9]` app-api-layouts.rs:117-140, pane.rs:2456-2500). So this
+// branch sends one fixed JSON line per connection and reads one reply line: the framing herdr's own
+// pi integration uses, and the one measured on the pinned 0.9.5 server (G2/G3).
+//
+// ONE ENDPOINT FOR THE READ AND THE WRITE. The caller-pane read that names the workspace and the
+// mutation that uses it go to the SAME explicit endpoint, `HERDR_SOCKET_PATH` — never the CLI for one
+// and the socket for the other, which could each reach a different server where `w1` names a
+// different workspace. Two connections do NOT establish server-generation invariance across a
+// restart or rebind: a valid inherited env pair (`HERDR_PANE_ID`, `HERDR_SOCKET_PATH`) and endpoint
+// continuity during this call are ASSUMPTIONS, named here rather than proven, and no generation or
+// liveness manager is added for them. The read is also a physical socket write; "exactly one" below
+// always means exactly one LAYOUT MUTATION write.
+//
+// WHAT THE PARSERS ARE. An authority-bearing REDUCTION of herdr's replies, not a vendor-schema
+// validator: they check the envelope this launch relies on and the id/echo fields it needs, against
+// the binary-bundled schema (protocol 22) and recorded replies, and nothing else. `agent_status` is
+// checked for presence only and is never interpreted. `result` XOR `error` is Entwurf's own strict
+// acceptance policy — the schema does not forbid extra properties.
+/** Each reported diagnostic string is cut to this many characters for DISPLAY, and rendered quoted.
+ * Every decision is taken on the complete original value before it is cut. */
+export const HERDR_DIAGNOSTIC_MAX_CHARS = 256;
+/**
+ * The error codes that prove NOTHING was created, for exactly this request shape (a `workspace_id`,
+ * no `tab_id`, one pane). `[blob 2ecf19a9]` the pinned `handle_layout_apply` returns these only
+ * before its first creation call: `workspace_not_found` at app-api-layouts.rs:56/66/114,
+ * `invalid_layout` at :69/:97/:109, and `invalid_env` at :105 (app-api-env.rs:3-32 yields no other
+ * code). `tab_not_found`/`invalid_target` need a `tab_id`, which this branch never sends, so they are
+ * NOT here — and `layout_apply_failed` is returned at :143/:158/:196 and after the creation events,
+ * so it never proves anything about creation.
+ */
+export const HERDR_LAYOUT_NONE_CODES = Object.freeze([
+    "workspace_not_found",
+    "invalid_layout",
+    "invalid_env",
+]);
+/**
+ * The production socket client. The reply is collected as BYTES and decoded once, after its newline,
+ * so a multi-byte character split across chunks is never decoded in halves. A bound that expires
+ * before the connection exists is a connect failure (nothing written); after it, a timeout (the
+ * request may have been written). Exactly one settle: connect, data, error, close and the timer race.
+ */
+export function createHerdrSocketCall(socketPath, bounds = { timeoutMs: HERDR_CLI_TIMEOUT_MS, maxReplyBytes: HERDR_MAX_OUTPUT_BYTES }) {
+    return (requestLine) => new Promise((resolve) => {
+        let settled = false;
+        let connected = false;
+        let lineBytes = 0;
+        const chunks = [];
+        const socket = createConnection({ path: socketPath });
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(outcome);
+        };
+        const timer = setTimeout(() => settle(connected ? { kind: "timeout" } : { kind: "connect-failed", code: "timeout-before-connect" }), bounds.timeoutMs);
+        timer.unref?.();
+        socket.on("connect", () => {
+            connected = true;
+            socket.write(requestLine);
+        });
+        socket.on("data", (chunk) => {
+            const newline = chunk.indexOf(0x0a);
+            const part = newline === -1 ? chunk : chunk.subarray(0, newline);
+            lineBytes += part.length;
+            if (lineBytes > bounds.maxReplyBytes) {
+                settle({ kind: "oversize" });
+                return;
+            }
+            chunks.push(part);
+            if (newline !== -1)
+                settle({ kind: "reply", line: decodeHerdrReplyBytes(chunks) });
+        });
+        socket.on("error", (error) => {
+            const code = error.code ?? error.message;
+            settle(connected ? { kind: "io-failed", code } : { kind: "connect-failed", code });
+        });
+        socket.on("close", () => settle({ kind: "eof-before-newline" }));
+    });
+}
+/** The reply line's ONE decode: every collected chunk concatenated, then UTF-8 — never chunk by
+ * chunk, so a multi-byte character split between reads is decoded whole. */
+export function decodeHerdrReplyBytes(chunks) {
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** The fixed caller-pane read. Product function, not an RPC surface: method and shape are literal. */
+export function buildHerdrPaneGetPacket(id, paneId) {
+    return `${JSON.stringify({ id, method: "pane.get", params: { pane_id: paneId } })}\n`;
+}
+/** The fixed layout mutation: one unfocused pane tab in a named workspace, an explicit cwd, an argv
+ * vector and an env map. No `tab_id`, `tab_label`, split, label or ratio can be expressed through it. */
+export function buildHerdrLayoutApplyPacket(id, params) {
+    return `${JSON.stringify({
+        id,
+        method: "layout.apply",
+        params: {
+            workspace_id: params.workspaceId,
+            focus: false,
+            root: { type: "pane", cwd: params.cwd, command: [...params.command], env: { ...params.env } },
+        },
+    })}\n`;
+}
+/** The launch env: the identity scrub the other launches use, plus the callback pair from its one
+ * validating formatter (which throws rather than inject a pair the callback verb would refuse). */
+export function buildHerdrLayoutLaunchEnv(callback) {
+    const env = { PI_SESSION_ID: "", PI_AGENT_ID: "" };
+    for (const assignment of callbackEnvAssignments(callback)) {
+        const at = assignment.indexOf("=");
+        env[assignment.slice(0, at)] = assignment.slice(at + 1);
+    }
+    return env;
+}
+/**
+ * The argv vector: the verified package's own launcher, then the SHARED pi-durable composition, with
+ * the bootstrap payload made Cc-free at ITS OWN layer. `JSON.stringify` escapes C0, `"` and `\` but
+ * leaves DEL and C1 literal; escaping only the outer request would be undone by herdr's own decode,
+ * so the reversible `\uXXXX` escape is applied to the payload element itself. The bootstrap decoder
+ * is `JSON.parse` (meta-bridge-omp.ts `decodeOmpBootstrapPayload`), so the task comes back byte-exact
+ * — asserted here, and a failure is OUR bug, so it throws rather than launch a task we cannot
+ * reproduce. No blanket control-character refusal: this exec path has no Cc rule of its own.
+ */
+export function composeHerdrPiDurableCommand(params) {
+    const args = composeBackendArgs("pi-durable", {
+        prompt: params.prompt,
+        bootstrapPayload: buildOmpBootstrapPayload({
+            callerGardenId: params.callerGardenId,
+            nonce: params.nonce,
+            task: params.task,
+        }),
+    }, params.model, () => {
+        throw new Error("herdr-fresh-call: codex is not a herdr backend");
+    }, () => {
+        throw new Error("herdr-fresh-call: codex is not a herdr backend");
+    });
+    const raw = args.at(-1);
+    if (args.at(-2) !== "--entwurf-bootstrap" || raw === undefined) {
+        throw new Error("herdr-fresh-call: the pi-durable composition no longer ends with its bootstrap payload");
+    }
+    const payload = escapeRemainingControlChars(raw);
+    const decoded = JSON.parse(payload);
+    const intact = typeof decoded === "object" &&
+        decoded !== null &&
+        decoded.v === OMP_BOOTSTRAP_VERSION &&
+        decoded.task === params.prompt &&
+        !containsControlChar(payload);
+    if (!intact) {
+        throw new Error("herdr-fresh-call: the pi-durable bootstrap payload did not decode back to the framed prompt — refusing to launch a sibling with a task we cannot reproduce");
+    }
+    return [params.runtime, ...args.slice(0, -1), payload];
+}
+/** `HERDR_SOCKET_PATH`, read only here and only as given: non-empty and absolute, or `null`. */
+export function resolveHerdrSocketPath(env) {
+    const value = env.HERDR_SOCKET_PATH;
+    return typeof value === "string" && value.length > 0 && path.isAbsolute(value) ? value : null;
+}
+/**
+ * The explicit start directory. herdr's own default for an omitted `root.cwd` is the FOCUSED pane's
+ * cwd in the target workspace (`[blob 2ecf19a9]` app-api-layouts.rs:343-365) — unrelated to the
+ * caller — so this branch always sends one. Requested first; then a known Codex caller's RECORD
+ * cwd, with NO fallback when it has none (its process directory is the app-server's, #95 lane C);
+ * then, for every other caller, this process's own directory — the inherited fact the tmux rail's
+ * omitted cwd rests on. Never herdr's own `cwd`/`foreground_cwd` for the caller's pane: that is a view.
+ * The agent-start branch reuses this same choice for its `tab create --cwd` (#157 A-L1x), so both
+ * herdr branches start an omitted cwd where the caller is; the name stays layout-first only by history.
+ */
+export function chooseHerdrLayoutCwd(input) {
+    if (input.requestedCwd !== undefined)
+        return { ok: true, cwd: input.requestedCwd, source: "requested" };
+    if (input.callerIsCodex) {
+        const record = input.callerCwd === undefined || input.callerCwd === "" ? undefined : input.callerCwd;
+        return record === undefined
+            ? { ok: false, reason: "codex-caller-cwd-unavailable" }
+            : { ok: true, cwd: record, source: "codex-caller-record" };
+    }
+    return { ok: true, cwd: input.callerProcessCwd(), source: "caller-process" };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/** Cut for display, never for comparison. A lone high surrogate is not left at the cut. */
+export function boundHerdrDiagnostic(value) {
+    if (value.length <= HERDR_DIAGNOSTIC_MAX_CHARS)
+        return value;
+    let cut = HERDR_DIAGNOSTIC_MAX_CHARS - 1;
+    const last = value.charCodeAt(cut - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        cut -= 1;
+    return `${value.slice(0, cut)}…`;
+}
+/**
+ * The envelope, before any certainty is decided: a JSON object (not an array, not null), the exact
+ * id we sent, and EXACTLY ONE of `result`/`error`, whose value is itself a non-null, non-array
+ * object. An error arm also needs a non-empty string `code` and a string `message` (both required
+ * by the bundled schema). Anything else is `null`: unreadable, never a partially believed answer.
+ */
+export function readHerdrEnvelope(line, id) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!isPlainObject(parsed))
+        return null;
+    if (typeof parsed.id !== "string" || parsed.id !== id)
+        return null;
+    const hasResult = Object.hasOwn(parsed, "result");
+    if (hasResult === Object.hasOwn(parsed, "error"))
+        return null;
+    if (hasResult)
+        return isPlainObject(parsed.result) ? { arm: "result", result: parsed.result } : null;
+    const error = parsed.error;
+    if (!isPlainObject(error))
+        return null;
+    if (!isNonEmptyString(error.code) || typeof error.message !== "string")
+        return null;
+    return { arm: "error", code: error.code, message: error.message };
+}
+/** The transport cause of a read that got no reply line, cut for display. */
+function readTransportCause(outcome) {
+    return boundHerdrDiagnostic("code" in outcome ? `${outcome.kind}: ${outcome.code}` : outcome.kind);
+}
+/** The caller-pane read, reduced. Every failure is a REFUSAL: nothing has been mutated yet. A
+ * transport cause or a well-formed herdr error travels with it as bounded, display-only report. */
+export function classifyHerdrLayoutPaneRead(outcome, id, callerPaneId) {
+    if (outcome.kind !== "reply") {
+        return { ok: false, reason: "herdr-caller-pane-get-failed", reported: { transport: readTransportCause(outcome) } };
+    }
+    const envelope = readHerdrEnvelope(outcome.line, id);
+    if (envelope === null)
+        return { ok: false, reason: "herdr-caller-pane-unparsable", reported: {} };
+    if (envelope.arm === "error") {
+        return {
+            ok: false,
+            reason: "herdr-caller-pane-get-failed",
+            reported: {
+                errorCode: boundHerdrDiagnostic(envelope.code),
+                errorMessage: boundHerdrDiagnostic(envelope.message),
+            },
+        };
+    }
+    if (envelope.result.type !== "pane_info")
+        return { ok: false, reason: "herdr-caller-pane-unparsable", reported: {} };
+    const pane = envelope.result.pane;
+    if (!isPlainObject(pane) ||
+        !isNonEmptyString(pane.pane_id) ||
+        !isNonEmptyString(pane.terminal_id) ||
+        !isNonEmptyString(pane.tab_id) ||
+        typeof pane.focused !== "boolean" ||
+        typeof pane.revision !== "number" ||
+        !Number.isSafeInteger(pane.revision) ||
+        pane.revision < 0 ||
+        !Object.hasOwn(pane, "agent_status")) {
+        return { ok: false, reason: "herdr-caller-pane-unparsable", reported: {} };
+    }
+    if (pane.pane_id !== callerPaneId)
+        return { ok: false, reason: "herdr-caller-pane-drift", reported: {} };
+    if (!isNonEmptyString(pane.workspace_id)) {
+        return { ok: false, reason: "herdr-caller-workspace-missing", reported: {} };
+    }
+    return { ok: true, workspaceId: pane.workspace_id };
+}
+function layoutFailure(reason, outcome, reported, herdrErrorCode) {
+    return {
+        ok: false,
+        reason,
+        ...(herdrErrorCode === undefined ? {} : { herdrErrorCode }),
+        recovery: { outcome },
+        reported,
+    };
+}
+/** The coordinates a drifted success reply named — strings only, cut for display. Never a receipt. */
+function reportedCoordinates(layout, root) {
+    return {
+        ...(typeof layout?.workspace_id === "string" ? { workspaceId: boundHerdrDiagnostic(layout.workspace_id) } : {}),
+        ...(typeof layout?.tab_id === "string" ? { tabId: boundHerdrDiagnostic(layout.tab_id) } : {}),
+        ...(typeof root?.pane_id === "string" ? { paneId: boundHerdrDiagnostic(root.pane_id) } : {}),
+    };
+}
+function sameArgv(echoed, sent) {
+    return (Array.isArray(echoed) &&
+        echoed.length === sent.length &&
+        echoed.every((token, index) => typeof token === "string" && token === sent[index]));
+}
+/**
+ * The ONE layout mutation write's outcome. Envelope first (`readHerdrEnvelope`), certainty second:
+ * `none` only when the request was never written or herdr answered a well-formed matching error
+ * with a pre-create code; EVERY other non-success is `unknown` — a tab may exist, nothing is closed
+ * and nothing is resent. A success must prove THIS launch: the arm, the workspace we asked for, a
+ * tab, a single-pane root whose pane is the tab's focus, and the cwd and argv we sent echoed back
+ * (an echo, not an execution witness; schema-nullable `pane_id`/`cwd`/`command` that come back null
+ * cannot prove it, so they are `unknown` too).
+ */
+export function classifyHerdrLayoutApplyReply(outcome, expect) {
+    switch (outcome.kind) {
+        case "connect-failed":
+            return layoutFailure("herdr-layout-transport-failed", "none", {
+                transport: boundHerdrDiagnostic(`connect-failed: ${outcome.code}`),
+            });
+        case "io-failed":
+            return layoutFailure("herdr-layout-transport-failed", "unknown", {
+                transport: boundHerdrDiagnostic(`io-failed: ${outcome.code}`),
+            });
+        case "timeout":
+        case "oversize":
+        case "eof-before-newline":
+            return layoutFailure("herdr-layout-transport-failed", "unknown", { transport: outcome.kind });
+        default:
+            break;
+    }
+    const envelope = readHerdrEnvelope(outcome.line, expect.id);
+    if (envelope === null)
+        return layoutFailure("herdr-layout-reply-unparsable", "unknown", {});
+    if (envelope.arm === "error") {
+        const reported = {
+            errorCode: boundHerdrDiagnostic(envelope.code),
+            errorMessage: boundHerdrDiagnostic(envelope.message),
+        };
+        return HERDR_LAYOUT_NONE_CODES.includes(envelope.code)
+            ? layoutFailure("herdr-layout-apply-refused", "none", reported, envelope.code)
+            : layoutFailure("herdr-layout-apply-failed", "unknown", reported, envelope.code);
+    }
+    const layout = isPlainObject(envelope.result.layout) ? envelope.result.layout : undefined;
+    const root = isPlainObject(layout?.root) ? layout.root : undefined;
+    if (envelope.result.type !== "layout_apply" ||
+        layout === undefined ||
+        root === undefined ||
+        layout.workspace_id !== expect.workspaceId ||
+        !isNonEmptyString(layout.tab_id) ||
+        typeof layout.zoomed !== "boolean" ||
+        !isNonEmptyString(layout.focused_pane_id) ||
+        root.type !== "pane" ||
+        !isNonEmptyString(root.pane_id) ||
+        layout.focused_pane_id !== root.pane_id ||
+        root.cwd !== expect.cwd ||
+        !sameArgv(root.command, expect.command)) {
+        return layoutFailure("herdr-layout-reply-drift", "unknown", reportedCoordinates(layout, root));
+    }
+    return { ok: true, workspaceId: expect.workspaceId, tabId: layout.tab_id, paneId: root.pane_id };
+}
+export const HERDR_LAYOUT_PRODUCTION_DEPS = {
+    socket: (socketPath) => createHerdrSocketCall(socketPath),
+    callerProcessCwd: () => process.cwd(),
+    packageLayout: () => piDurablePackageLayout(),
+    runtimeVerdict: (layout) => {
+        const verdict = checkPiDurableRuntime(layout);
+        return verdict.ok ? null : verdict.reason;
+    },
+};
+/** A bounded environment probe: is the verified package's own launcher an executable regular file? */
+function isExecutableRegularFile(file) {
+    try {
+        if (!statSync(file).isFile())
+            return false;
+        accessSync(file, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * #157 B3: the verified package's own launcher for a layout command, or `null` when it is missing or
+ * not executable — the same path and probe the fresh layout branch puts first in its argv vector. The
+ * pi-durable same-id resume (`herdr-resume-call.ts`) asks it through this export.
+ */
+export function resolvePiDurableLauncher(layout) {
+    const runtime = path.join(layout.root, "run.sh");
+    return isExecutableRegularFile(runtime) ? runtime : null;
+}
+/**
+ * Open a pi-durable sibling in a new herdr tab. ORDER IS THE ARGUMENT: everything decidable without
+ * herdr — inputs, the explicit cwd, the endpoint, the pi-durable preflight (provider split, first
+ * input cap, package, carrier and SDK set, units), the launcher and the argv — is decided before
+ * the first socket request. The caller-pane read comes next and mutates nothing, so any failure of
+ * it refuses with zero layout writes. Then the ONE layout mutation write, never resent, and no
+ * reclaim: herdr's layout reply names no terminal id, so this branch holds no create-receipt
+ * terminal and therefore no authority to close what it opened.
+ */
+async function herdrLayoutFreshCall(params, context, env, nonce, deps) {
+    const normalized = normalizeFreshCallInputs(params);
+    if (!normalized.ok)
+        return { ok: false, reason: normalized.reason };
+    const { callerGardenId, model, task, cwd: requestedCwd } = normalized.inputs;
+    const chosen = chooseHerdrLayoutCwd({
+        ...(requestedCwd === undefined ? {} : { requestedCwd }),
+        callerIsCodex: params.callerIsCodex === true,
+        ...(params.callerCwd === undefined ? {} : { callerCwd: params.callerCwd }),
+        callerProcessCwd: deps.callerProcessCwd,
+    });
+    if (!chosen.ok)
+        return { ok: false, reason: chosen.reason };
+    const badCwd = classifyHerdrCwd(chosen.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 prompt = composeFreshCallPrompt({
+        backend: "pi-durable",
+        task,
+        callerGardenId,
+        nonce,
+        openingLine: HERDR_FRESH_CALL_OPENING_LINE,
+    });
+    const packageLayout = deps.packageLayout();
+    const missing = piDurableFreshPreflight({
+        model,
+        firstInput: prompt,
+        layout: packageLayout,
+        runtime: packageLayout === null ? null : deps.runtimeVerdict(packageLayout),
+    });
+    if (missing !== null)
+        return { ok: false, reason: missing };
+    if (packageLayout === null)
+        throw new Error("herdr-fresh-call: the pi-durable preflight passed without a package");
+    const runtime = path.join(packageLayout.root, "run.sh");
+    if (!isExecutableRegularFile(runtime))
+        return { ok: false, reason: "pi-durable-launcher-missing" };
+    const command = composeHerdrPiDurableCommand({ runtime, prompt, model, callerGardenId, nonce, task });
+    const launchEnv = buildHerdrLayoutLaunchEnv({ target: callerGardenId, nonce });
+    const call = deps.socket(socketPath);
+    const base = herdrAgentNameFromNonce(nonce);
+    const readId = `${base}:pane.get`;
+    const read = classifyHerdrLayoutPaneRead(await call(buildHerdrPaneGetPacket(readId, context.callerPaneId)), readId, 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 = `${base}:layout.apply`;
+    const applied = classifyHerdrLayoutApplyReply(await call(buildHerdrLayoutApplyPacket(writeId, {
+        workspaceId: read.workspaceId,
+        cwd: chosen.cwd,
+        command,
+        env: launchEnv,
+    })), { id: writeId, workspaceId: read.workspaceId, cwd: chosen.cwd, command });
+    if (!applied.ok)
+        return { ...applied, ...(applied.recovery.outcome === "unknown" ? { nonce } : {}) };
+    return {
+        ok: true,
+        receipt: {
+            backend: "pi-durable",
+            launch: "layout-apply",
+            model,
+            cwd: chosen.cwd,
+            cwdSource: chosen.source,
+            runtime,
+            herdrWorkspaceId: applied.workspaceId,
+            herdrTabId: applied.tabId,
+            herdrPaneId: applied.paneId,
+            nonce,
+        },
+    };
+}
 /** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
  * they will guess about. The five shared input reasons keep the wording the public verb has always
  * used; the rest are this rail's own. */
-const HERDR_REJECT_HINT = {
+export const HERDR_REJECT_HINT = {
     // #76: decided at the dispatch root, worded once in the shared composition leaf.
     ...FRESH_CALL_PROVIDER_HINT,
+    // #157 A-L1: the pi-durable preflight's repair text stays beside its predicates, as on tmux.
+    ...PI_DURABLE_PREFLIGHT_HINT,
+    ...PI_DURABLE_RUNTIME_HINT,
     "caller-identity-unavailable": "this surface has no record-backed identity, so a sibling would have nowhere to call home",
     "model-empty": "pass the model you want the sibling opened with — it is never inherited from this process",
     "model-invalid": "the model is not in the accepted grammar (no whitespace, no leading dash)",
@@ -798,11 +1292,19 @@ const HERDR_REJECT_HINT = {
     "task-too-long": `the task is over the ${TASK_MAX_CHARS}-character interface bound this verb shares with entwurf_v2`,
     "herdr-context-missing": "HERDR_ENV/HERDR_BIN_PATH are absent, so this process is not inside herdr and this rail does not exist here",
     "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-get-failed": "herdr would not report this process's own pane — for pi and claude-code run `herdr pane get $HERDR_PANE_ID` to see what it says; pi-durable asked through one `pane.get` on HERDR_SOCKET_PATH instead, and any cause herdr reported is quoted below",
     "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 open the sibling wherever the operator is looking",
-    "herdr-backend-unsupported": "this rail opens pi and claude-code only; nothing is opened elsewhere instead",
+    "herdr-backend-unsupported": "this rail opens pi and claude-code through herdr agent start, and pi-durable through one layout.apply tab; nothing is opened elsewhere instead",
+    "herdr-socket-path-missing": "HERDR_SOCKET_PATH is absent, empty or not absolute, so there is no herdr endpoint for pi-durable's one layout request — this rail does not guess or scan for one",
+    "pi-durable-launcher-missing": "this Entwurf package's own run.sh is missing or not executable, so the verified package has no launcher to put in the layout command — reinstall Entwurf",
+    "codex-caller-cwd-unavailable": "this Codex caller's record carries no directory, and its process directory is the app-server's, not its own — pass cwd explicitly",
+    "herdr-layout-transport-failed": "the one exchange with herdr's socket did not complete — read the recovery line for whether the request can have reached herdr",
+    "herdr-layout-apply-refused": "herdr declined the layout request with a code its handler returns before creating anything",
+    "herdr-layout-apply-failed": "herdr answered the layout request with an error that does not prove nothing was created",
+    "herdr-layout-reply-unparsable": "herdr's reply was not one well-formed answer to this exact request",
+    "herdr-layout-reply-drift": "herdr's success reply does not describe the tab this request asked for, so its coordinates were not accepted",
     "herdr-placement-tmux-rejected": "`placement` names a tmux session, which does not exist inside herdr — drop it rather than have the sibling silently placed somewhere else",
     "herdr-argv-control-character": "an argument still holds a control character after encoding; herdr refuses those and no pane was created",
     "cwd-not-absolute": "pass an absolute path, or omit cwd to use this agent's own directory",
@@ -863,6 +1365,76 @@ function renderFailureHeader(recovery) {
             return "entwurf_fresh_call failed after the tab was created";
     }
 }
+const HERDR_LAYOUT_FAILURE_REASONS = new Set([
+    "herdr-layout-transport-failed",
+    "herdr-layout-apply-refused",
+    "herdr-layout-apply-failed",
+    "herdr-layout-reply-unparsable",
+    "herdr-layout-reply-drift",
+]);
+/** The reported diagnostics, each already cut, rendered QUOTED so a value cannot pose as prose. */
+function renderReported(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, unverified, each value cut at ${HERDR_DIAGNOSTIC_MAX_CHARS} chars — not a receipt, a placement or anything to close): ${fields.map(([name, value]) => `${name} ${JSON.stringify(value)}`).join(", ")}\n`;
+}
+/** A layout-branch failure. The certainty line says only what the outcome licenses: `none` never
+ * says a sibling may exist, and only a POST-WRITE `unknown` mentions a possible callback. */
+function renderLayoutFailure(result, hint) {
+    const code = result.herdrErrorCode === undefined
+        ? ""
+        : ` [herdr: ${JSON.stringify(boundHerdrDiagnostic(result.herdrErrorCode))}]`;
+    if (result.recovery.outcome === "none") {
+        const why = result.reason === "herdr-layout-transport-failed"
+            ? "the request was never written to herdr"
+            : "herdr declined by name before creating anything";
+        return (`entwurf_fresh_call failed at the herdr layout.apply step: ${result.reason}${code} — ${hint}.\n` +
+            `  recovery: none — ${why}, so nothing was created\n` +
+            renderReported(result.reported));
+    }
+    const nonce = result.nonce === undefined ? "this call's launch nonce" : `nonce ${result.nonce}`;
+    return (`entwurf_fresh_call failed at the herdr layout.apply step with an UNKNOWN outcome: ${result.reason}${code} — ${hint}.\n` +
+        `  recovery: UNKNOWN — the layout write was attempted and may have reached herdr, so a pi-durable tab MAY exist and its sibling may still call back under ${nonce}; that callback's sender envelope is the only address. Nothing was closed and nothing will be retried — check herdr\n` +
+        renderReported(result.reported));
+}
+const HERDR_LAYOUT_CWD_SOURCE_TEXT = {
+    requested: "the requested start directory",
+    "codex-caller-record": "this Codex caller's own record directory",
+    "caller-process": "this agent's own process directory",
+};
+function renderLayoutReceipt(r) {
+    return (`[entwurf fresh call → herdr]\n` +
+        `  backend:  ${r.backend} (ONE layout.apply request — herdr has no agent kind for it, and none was requested)\n` +
+        `  model:    ${r.model} (requested on the runtime CLI)\n` +
+        `  cwd:      ${r.cwd} (${HERDR_LAYOUT_CWD_SOURCE_TEXT[r.cwdSource]}, sent explicitly — not an observation)\n` +
+        `  runtime:  ${r.runtime} (this package's verified launcher, the first element of the requested argv)\n` +
+        `  tab:      ${r.herdrTabId} in workspace ${r.herdrWorkspaceId} — a NEW tab beside the caller's, REQUESTED unfocused; whether it is actually unfocused is not observed here\n` +
+        `  pane:     ${r.herdrPaneId} — the tab's root pane; herdr VIEW coordinates, not an address (herdr's layout reply names no terminal)\n` +
+        `  nonce:    ${r.nonce}\n` +
+        `  detection: none requested — pi-durable has no herdr agent integration, so herdr is not told its session and its peers placement column reads unobserved\n` +
+        `\n` +
+        `This is a LAUNCH receipt: herdr accepted one layout request and named the tab above. It does NOT ` +
+        `mean the sibling is running, that its first turn ran, or that the task was delivered. The tab and pane ` +
+        `coordinates are a view and can change under the sibling — they are not an address and nothing may be ` +
+        `dispatched to them.\n` +
+        `The sibling's garden id arrives separately — before its task it calls the zero-argument callback verb ` +
+        `(a read-only look at the caller may come first), and ` +
+        `the sender envelope of THAT message is the address. The nonce above is the correlation tag it carries; ` +
+        `the sibling reads it from its own launch env, never from this receipt. Nothing is polling for it; if it ` +
+        `never comes — not started, stuck, or held back after its check; this receipt cannot tell which — the ` +
+        `pane is visible and can be read directly.`);
+}
 /**
  * Three outcomes, and an operator must be able to tell them apart at a glance: a refusal that
  * created nothing, a failure that may have left a tab behind, and a launch.
@@ -872,10 +1444,16 @@ export function renderHerdrFreshCall(result) {
         const hint = HERDR_REJECT_HINT[result.reason];
         if (!("recovery" in result)) {
             return {
-                text: `entwurf_fresh_call rejected: ${result.reason} — ${hint}. No tab and no pane were created.`,
+                text: `entwurf_fresh_call rejected: ${result.reason} — ${hint}. No tab and no pane were created.` +
+                    ("reported" in result && renderReported(result.reported) !== ""
+                        ? `\n${renderReported(result.reported).trimEnd()}`
+                        : ""),
                 isError: true,
             };
         }
+        if (HERDR_LAYOUT_FAILURE_REASONS.has(result.reason)) {
+            return { text: renderLayoutFailure(result, hint), isError: true };
+        }
         const code = result.herdrErrorCode === undefined ? "" : ` [herdr: ${result.herdrErrorCode}]`;
         return {
             text: `${renderFailureHeader(result.recovery)}: ${result.reason}${code} — ${hint}.\n` +
@@ -883,12 +1461,14 @@ export function renderHerdrFreshCall(result) {
             isError: true,
         };
     }
+    if (result.receipt.backend === "pi-durable")
+        return { text: renderLayoutReceipt(result.receipt), isError: false };
     const r = result.receipt;
     return {
         text: `[entwurf fresh call → herdr]\n` +
             `  backend:  ${r.backend} (requested kind ${r.requestedKind} — herdr resolves the executable, we did not)\n` +
             `  model:    ${r.model} (requested on the runtime CLI)\n` +
-            (r.cwd === undefined ? "" : `  cwd:      ${r.cwd} (requested start directory — not an observation)\n`) +
+            `  cwd:      ${r.cwd} (${HERDR_LAYOUT_CWD_SOURCE_TEXT[r.cwdSource]}, sent explicitly — not an observation)\n` +
             `  agent:    ${r.herdrAgentName} (herdr's name for it, derived from the nonce)\n` +
             `  tab:      ${r.herdrTabId} in workspace ${r.herdrWorkspaceId} — a NEW tab beside the caller's, opened without taking focus\n` +
             `  pane:     ${r.herdrPaneId} terminal ${r.herdrTerminalId} — the tab's initial pane; herdr VIEW coordinates, not an address\n` +