@junghanacs/entwurf 0.22.0 → 0.23.1

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

@@ -0,0 +1,1018 @@
+/**
+ * herdr-fresh-call — open ONE visible sibling in a new herdr tab, from inside herdr.
+ *
+ * THE TMUX RAIL IS NOT TOUCHED AND NOT REACHED FROM HERE. This module imports no `mux-*` and no
+ * `entwurf-*`: the pieces both rails genuinely share live in `fresh-call-composition.ts`, and
+ * everything below that line is different. herdr places with `tab create` + `agent start`, which
+ * is TWO mutations where tmux had one; it resolves no runtime for us; and its coordinates are
+ * workspace/tab/pane rather than server/session/window. Sharing a placement type between those
+ * would have been a shape, not a contract.
+ *
+ * WHY THE PROMPT ARRIVES JSON-ENCODED (#116 option G, measured 2026-09-14).
+ * `[file:line @ c77af189]` `src/app/agents.rs:157-162` refuses an `agent start` whose args contain
+ * ANY Unicode control character, before it even looks the pane up:
+ *
+ *     if params.args.iter().any(|arg| arg.chars().any(char::is_control)) { InvalidArgument }
+ *
+ * `[측정, 변이 0]` proven against a NONEXISTENT pane, so nothing was created: a two-line argument
+ * returned `invalid_agent_argument`, the same call with a one-line argument got as far as
+ * `agent_pane_not_found`. The first-turn framing is multi-line by contract and a caller's task is
+ * routinely multi-line, so neither can ride `-- <argv>` as written.
+ *
+ * Three other channels were measured and rejected before this one:
+ *   - `[측정]` delivering the framing to a BLANK sibling through the entwurf mailbox — the claude
+ *     sibling read it, stamped the receipt, and correctly refused to act on an imperative that
+ *     arrived as untrusted data. Rewriting it truthfully, with no birth claim and no id in the
+ *     body, changed nothing: it refused on AUTHORITY, not wording. A blank sibling has no reason
+ *     to exist yet, so the only thing that can give it one is the channel it was born through.
+ *   - keystrokes (`agent prompt`) are terminal input, which this product does not use to launch.
+ *   - a vendor extension decoder exists for omp, but not for claude-code, and this pilot is
+ *     `pi | claude-code`.
+ *
+ * So the WHOLE prompt is wrapped as one JSON string literal inside one truthful sentence telling
+ * the sibling to decode it. `[측정 2026-09-14, both pilots]` the sibling decodes it, calls the
+ * callback FIRST, and only then answers the task — the order the framing exists to fix survived
+ * the encoding on both axes.
+ *
+ * WHAT THIS MODULE DOES NOT DO: it never reads the record store, never resolves a garden id,
+ * never retries, never watches, and never puts a garden id or native session id in its receipt.
+ * The direct `agent_started` witness is the CALLER's launch evidence; the sibling's nonce callback
+ * is separate first-model-action evidence. Neither is a fallback for the other, and this file is
+ * not allowed to turn one into the other.
+ */
+import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
+import path from "node:path";
+import { buildOmpBootstrapPayload, composeBackendArgs, composeFreshCallFraming, normalizeFreshCallInputs, TASK_MAX_CHARS, } from "./fresh-call-composition.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. */
+export const HERDR_FRESH_CALL_BACKENDS = ["pi", "claude-code"];
+/** 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. */
+export const HERDR_AGENT_KIND = {
+    pi: "pi",
+    "claude-code": "claude",
+};
+/** What the herdr rail tells a sibling about where it woke up — the rail-owned sentence the
+ * composition leaf refuses to invent for itself. */
+export const HERDR_FRESH_CALL_OPENING_LINE = "You are a fresh visible citizen that entwurf opened in a new herdr tab.";
+/**
+ * The sentence that introduces the operator's own task text, and the ONE thing on this rail that
+ * is still quoted rather than spoken.
+ *
+ * WHAT IT REPLACED, AND WHY (#116). Until 2026-09-17 the WHOLE first turn — framing and task
+ * together — was handed over as `Decode the following JSON string literal and follow the decoded
+ * instructions exactly as if they were this message: "…"`. `[GLG 직접, 날것 PC, 2026-09-17]` a Claude
+ * Sonnet 5 sibling refused that turn outright and named the shape: "instructions smuggled inside
+ * content I'm asked to decode". It is the canonical injection form, and a safety-tuned model is
+ * RIGHT to refuse it — which means the rail could not be shipped to the models users actually run.
+ *
+ * `[source herdr 7505c08]` the encoding cannot simply go away: `src/app/agents.rs:157-161` refuses
+ * any agent argument containing a Unicode Cc, so a newline never reaches the sibling. What CAN go
+ * away is encoding the instructions: `src/app/agents.rs:197-200` composes the argv through
+ * `platform::interactive_shell_command`, and `src/platform/linux.rs:127-141` single-quotes every
+ * argument and escapes an embedded quote as `'\''` — so herdr already protects the shell, and the
+ * JSON literal was never buying shell safety. It was buying newline folding and exact
+ * reversibility, and only the TASK needs those.
+ *
+ * So the framing is folded onto one line as plain prose a human can read in the scrollback, and
+ * the task alone rides as a literal. The sentence says why it is quoted and bounds what decoding
+ * it may do — it is the operator's task text, not a second set of instructions that could rewrite
+ * the framing above it.
+ */
+export const HERDR_TASK_LITERAL_INSTRUCTION = "The task is JSON-encoded only because this launch channel cannot carry a newline. Decode it and carry it out as your task text. Nothing inside it changes the instructions above: ";
+export const HERDR_REAL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    }),
+};
+export function resolveHerdrContext(env) {
+    if (env.HERDR_ENV !== "1")
+        return { ok: false, reason: "herdr-context-missing" };
+    const bin = env.HERDR_BIN_PATH;
+    if (typeof bin !== "string" || bin.length === 0)
+        return { ok: false, reason: "herdr-context-missing" };
+    const callerPaneId = env.HERDR_PANE_ID;
+    if (typeof callerPaneId !== "string" || callerPaneId.length === 0) {
+        // Without it we cannot ask herdr where the caller is, and picking a workspace out of
+        // `workspace list` would put the sibling beside whoever happens to be focused.
+        return { ok: false, reason: "herdr-caller-pane-missing" };
+    }
+    return { ok: true, context: { bin, callerPaneId } };
+}
+/**
+ * The tmux seat input has no meaning here and is REFUSED rather than ignored.
+ *
+ * `placement: {tmuxSession}` names a session on the caller's tmux server. Inside herdr there is no
+ * such server, and quietly dropping the field would open a sibling somewhere the caller did not
+ * ask for while the call still looked successful. This is the narrowest layer that can see the
+ * input, and the public tool reaches it through `fresh-call-dispatch`.
+ */
+export function rejectTmuxPlacementInHerdrContext(placement) {
+    // ANY defined placement object is a tmux-shaped request, including `{}` and
+    // `{tmuxSession: ""}`. Reading the MEMBER instead of the object would have let a caller who
+    // asked for a seat and mistyped it get a sibling in the default position with a green
+    // receipt — the same silent-relocation failure this refusal exists to prevent.
+    return placement === undefined ? null : "herdr-placement-tmux-rejected";
+}
+/**
+ * The start directory, classified for herdr rather than borrowed from tmux.
+ *
+ * The tmux leaf also refuses `#`, because `[측정]` tmux FORMAT-EXPANDS a `-c` value and a `#(…)`
+ * was observed executing. herdr has no such expansion: `[file:line @ c77af189]` `src/cli/pane.rs:689-694`
+ * clones the `--cwd` value into the request and the server passes it on, so the character is
+ * ordinary here. Importing the tmux rule would have been borrowed authority — a refusal whose
+ * stated reason is false on this rail. The existence checks below are kept, and for the same
+ * measured reason they exist there: a directory that is gone must not produce a cheerful launch
+ * somewhere else.
+ */
+export function classifyHerdrCwd(cwd) {
+    if (!path.isAbsolute(cwd))
+        return "cwd-not-absolute";
+    let st;
+    try {
+        st = statSync(cwd);
+    }
+    catch {
+        return "cwd-missing";
+    }
+    return st.isDirectory() ? null : "cwd-not-directory";
+}
+/** Every Unicode control character, the same class herdr's server refuses. `JSON.stringify` escapes
+ * C0 and the quote/backslash pair, but leaves DEL (U+007F) and the C1 block (U+0080–U+009F)
+ * LITERAL — so the escape pass below is not decoration, it is the half `JSON.stringify` does not do. */
+const CONTROL_CHARS = /\p{Cc}/gu;
+/** Reversible: `\uXXXX` inside a JSON string decodes back to exactly this character. */
+function escapeRemainingControlChars(json) {
+    return json.replace(CONTROL_CHARS, (ch) => `\\u${ch.codePointAt(0)?.toString(16).padStart(4, "0")}`);
+}
+/**
+ * Fold the framing onto ONE physical line and append the task as a literal.
+ *
+ * Two independent things must hold and both are checked rather than assumed: herdr will accept the
+ * result (zero `\p{Cc}` anywhere in it), and the sibling can recover the operator's task EXACTLY
+ * (the JSON literal parses back to the input, byte for byte — no trimming, no normalisation, no
+ * reflow). A round-trip failure is OUR bug, not the caller's input, so it throws instead of
+ * returning a reject the caller could not act on.
+ *
+ * The FRAMING is not round-tripped, because it is not data: it is folded with single spaces and
+ * read as prose. What is asserted about it instead is that every composed line survives the fold
+ * verbatim, in order — the sibling reads the same sentences, on one line.
+ */
+export function encodeBirthPrompt(framing, task) {
+    const folded = framing.filter((line) => line.length > 0).join(" ");
+    const literal = escapeRemainingControlChars(JSON.stringify(task));
+    const argv = `${folded} ${HERDR_TASK_LITERAL_INSTRUCTION}${literal}`;
+    // Fail closed. Reachable when the FRAMING carries a control character (a rail opening line is
+    // the rail's own input) or if a future JS runtime leaves one both unescaped by JSON.stringify
+    // AND unmatched by \p{Cc}; the refusal is cheaper than the orphan pane a server-side rejection
+    // would cost us.
+    if (containsControlChar(argv))
+        return { ok: false, reason: "herdr-argv-control-character" };
+    const decoded = JSON.parse(literal);
+    if (decoded !== task) {
+        throw new Error("herdr-fresh-call: the encoded task did not decode back to the original — refusing to launch a sibling with a task we cannot reproduce");
+    }
+    return { ok: true, argv };
+}
+export function containsControlChar(value) {
+    CONTROL_CHARS.lastIndex = 0;
+    return CONTROL_CHARS.test(value);
+}
+/**
+ * The agent name herdr will know this sibling by.
+ *
+ * `[file:line @ c77af189]` `src/app/agents.rs:15-20` requires `[a-z][a-z0-9_-]{0,31}`, which the
+ * nonce itself does not satisfy (it is 39 characters). So the name is DERIVED from the per-call
+ * nonce by hash: same call, same name; different calls, different names; and the name discloses
+ * nothing. It is not a role, not a title and not an address — an operator reading `herdr agent
+ * list` should learn only that entwurf opened it.
+ */
+export function herdrAgentNameFromNonce(nonce) {
+    return `entwurf-${createHash("sha256").update(nonce).digest("hex").slice(0, 20)}`;
+}
+/**
+ * The ONE placement policy this rail has: a NEW TAB in the caller's own workspace, without taking
+ * the keyboard. `[GLG direct decision 2026-09-15]` after using the rail for real, a tab beside the
+ * caller reads better than a pane split under it; `--no-focus` stays, because a sibling opening
+ * under the operator's hands must not steal focus either way.
+ *
+ * `--workspace` IS PASSED EXPLICITLY AND IS NOT OPTIONAL HERE. `[측정 2026-09-15, private server]`
+ * omitting it still succeeds — herdr puts the tab in whatever workspace is currently focused. That
+ * is a silent relocation exactly like the tmux seat this rail already refuses, so the workspace is
+ * resolved from herdr's OWN answer about the caller's pane (see `herdrFreshCall`) and never from
+ * parsing the `w<N>:p<M>` shape of a pane id, which `[측정 2026-09-14]` is opaque anyway (`w7:pA`).
+ *
+ * `[측정 2026-09-15]` a workspace herdr does not know is refused BEFORE anything is created
+ * (`{"error":{"code":"workspace_not_found"}}`, exit 1) — the mutation is still one step, not two.
+ *
+ * This is deliberately NOT a layout manager: no `--label`, no ratio, no second placement axis. A
+ * caller who wants a different arrangement moves the tab in herdr, which owns layout.
+ *
+ * The identity scrub is explicit for the reason the tmux rail learned the hard way: a child that
+ * inherits a stale `PI_SESSION_ID` reports itself as a citizen it is not. `[측정 2026-09-15]` the
+ * flag behaves the same on `tab create` as it did on `pane split` and it beats inheritance: with
+ * `PI_SESSION_ID` deliberately poisoned in the SERVER's own environment, the process launched in
+ * the new tab carried `PI_SESSION_ID=''` and `PI_AGENT_ID=''` — read from `/proc/<pid>/environ`,
+ * not from a screen. Repeating the flag is the grammar; `--env KEY=` injects the EMPTY value
+ * rather than dropping the key.
+ */
+export function buildHerdrTabCreateArgs(params) {
+    return [
+        "tab",
+        "create",
+        "--workspace",
+        params.workspaceId,
+        "--no-focus",
+        ...(params.cwd === undefined ? [] : ["--cwd", params.cwd]),
+        "--env",
+        "PI_SESSION_ID=",
+        "--env",
+        "PI_AGENT_ID=",
+    ];
+}
+/** `agent start <name> --kind <kind> --pane <id> -- <backend argv>`. Everything after `--` is the
+ * vendor's own argv, echoed back in the response. */
+export function buildHerdrAgentStartArgs(params) {
+    return [
+        "agent",
+        "start",
+        params.agentName,
+        "--kind",
+        params.kind,
+        "--pane",
+        params.paneId,
+        // Never omitted: herdr's own default is 30s, which is shorter than a cold Claude Code start
+        // and turns a healthy launch into a named timeout over an unreclaimed pane.
+        "--timeout",
+        String(HERDR_START_READY_MS),
+        "--",
+        ...params.backendArgs,
+    ];
+}
+/** `[측정 2026-09-14]` both take a POSITIONAL pane id — `herdr pane get --pane <id>` is a usage
+ * error, not a synonym. */
+export function buildHerdrPaneGetArgs(paneId) {
+    return ["pane", "get", paneId];
+}
+export function buildHerdrPaneCloseArgs(paneId) {
+    return ["pane", "close", paneId];
+}
+/** `herdr agent get <target>` — POSITIONAL, exactly one argument (`[file:line @ c77af189]`
+ * `src/cli/agent.rs:450-458`). EXACT NAME, never `agent list`: a listing would make us pick "the
+ * one that looks like ours" out of every agent on the server, which is the guess this rail
+ * refuses. The name we ask about is the nonce-derived one we asked herdr to start. */
+export function buildHerdrAgentGetArgs(agentName) {
+    return ["agent", "get", agentName];
+}
+function readPaneFacts(pane) {
+    if (typeof pane !== "object" || pane === null)
+        return null;
+    const row = pane;
+    const paneId = row.pane_id;
+    const terminalId = row.terminal_id;
+    if (typeof paneId !== "string" || paneId.length === 0)
+        return null;
+    if (typeof terminalId !== "string" || terminalId.length === 0)
+        return null;
+    const workspaceId = typeof row.workspace_id === "string" ? row.workspace_id : undefined;
+    const tabId = typeof row.tab_id === "string" ? row.tab_id : undefined;
+    const agent = typeof row.agent === "string" && row.agent.length > 0 ? row.agent : undefined;
+    const agentStatus = typeof row.agent_status === "string" && row.agent_status.length > 0 ? row.agent_status : undefined;
+    const agentName = typeof row.name === "string" && row.name.length > 0 ? row.name : undefined;
+    return {
+        paneId,
+        terminalId,
+        ...(workspaceId === undefined ? {} : { workspaceId }),
+        ...(tabId === undefined ? {} : { tabId }),
+        hasAgentSession: row.agent_session !== undefined && row.agent_session !== null,
+        ...(agent === undefined ? {} : { agent }),
+        ...(agentStatus === undefined ? {} : { agentStatus }),
+        ...(agentName === undefined ? {} : { agentName }),
+    };
+}
+/** `{"id":"cli:pane:get","result":{"pane":{…},"type":"pane_info"}}` — measured. A payload that is
+ * not that shape is DECLINED (null); it is never partially believed. */
+export function parseHerdrPaneResponse(stdout) {
+    const root = parseJsonObject(stdout);
+    if (root === null)
+        return null;
+    const result = root.result;
+    if (typeof result !== "object" || result === null)
+        return null;
+    return readPaneFacts(result.pane);
+}
+/**
+ * `{"id":"cli:tab:create","result":{"root_pane":{…},"tab":{…},"type":"tab_created"}}` — measured
+ * verbatim on herdr 0.9.0, 2026-09-15.
+ *
+ * The reply names the new tab AND hands back its initial pane in one breath, which is why this
+ * rail never has to go looking: diffing `pane list` for "the new one" is the guess it refuses
+ * everywhere else.
+ *
+ * BOTH HALVES MUST NAME THE SAME TAB AND THE SAME WORKSPACE, and both must say so out loud.
+ * `[측정 2026-09-15]` every `tab_created` reply carried `tab_id` and `workspace_id` on the tab AND
+ * on its root pane, so an absent one is herdr disagreeing with this version rather than an
+ * optional field — and treating it as optional is how a contradictory reply gets assembled into a
+ * green launch whose receipt names one tab while the agent starts in another. Disagreement or
+ * absence declines the WHOLE payload; we do not pick the half we prefer.
+ */
+export function parseHerdrTabCreateResponse(stdout) {
+    const root = parseJsonObject(stdout);
+    if (root === null)
+        return null;
+    const result = root.result;
+    if (typeof result !== "object" || result === null)
+        return null;
+    const rootPane = readPaneFacts(result.root_pane);
+    if (rootPane === null)
+        return null;
+    const tab = result.tab;
+    if (typeof tab !== "object" || tab === null)
+        return null;
+    const tabId = tab.tab_id;
+    const workspaceId = tab.workspace_id;
+    if (typeof tabId !== "string" || tabId.length === 0)
+        return null;
+    if (typeof workspaceId !== "string" || workspaceId.length === 0)
+        return null;
+    // Required on the root pane too, and equal — not "checked when present".
+    if (rootPane.tabId !== tabId)
+        return null;
+    if (rootPane.workspaceId !== workspaceId)
+        return null;
+    return { tabId, workspaceId, rootPane };
+}
+/** `{"id":"cli:agent:start","result":{"agent":{…},"argv":[…],"type":"agent_started"}}` — measured. */
+export function parseHerdrAgentStartResponse(stdout) {
+    const root = parseJsonObject(stdout);
+    if (root === null)
+        return null;
+    const result = root.result;
+    if (typeof result !== "object" || result === null)
+        return null;
+    const pane = readPaneFacts(result.agent);
+    if (pane === null)
+        return null;
+    const rawArgv = result.argv;
+    const argv = Array.isArray(rawArgv) && rawArgv.every((token) => typeof token === "string") ? rawArgv : null;
+    return { pane, argv };
+}
+/** The canonical executable herdr writes for a requested kind, measured twice today (`["claude"]`
+ * and `["pi","--entwurf-control"]`) and pinned upstream at `src/detect/mod.rs:155-156 @ c77af189`.
+ * We only assert it for the two pilot kinds we have actually seen. */
+export const HERDR_CANONICAL_EXECUTABLE = {
+    pi: "pi",
+    "claude-code": "claude",
+};
+/** Did herdr compose the argv we asked for, exactly? A launch whose echoed argv differs is a
+ * sibling that was started with something other than our framing, which no later receipt would
+ * reveal. */
+export function argvMatchesRequest(echoed, backend, backendArgs) {
+    if (echoed === null)
+        return false;
+    const expected = [HERDR_CANONICAL_EXECUTABLE[backend], ...backendArgs];
+    return echoed.length === expected.length && echoed.every((token, index) => token === expected[index]);
+}
+/** `herdr pane get <id>` → `{"result":{"pane":{…}}}`. */
+export const parseHerdrPaneGetResponse = parseHerdrPaneResponse;
+/** `herdr agent get <name>` → `{"result":{"agent":{…AgentInfo…}}}` — the same reduction the start
+ * reply gets, because `AgentInfo` carries the same pane/terminal/tab/session keys
+ * (`[file:line @ c77af189]` `src/api/schema/agents.rs:187-215`). A payload that is not that shape
+ * is DECLINED (null); an absent agent and an unreadable reply are NOT the same answer, and the
+ * caller of this parser is the one that keeps them apart. */
+export function parseHerdrAgentGetResponse(stdout) {
+    const root = parseJsonObject(stdout);
+    if (root === null)
+        return null;
+    const result = root.result;
+    if (typeof result !== "object" || result === null)
+        return null;
+    return readPaneFacts(result.agent);
+}
+/** herdr's own failure envelope: `{"id":…,"error":{"code":…,"message":…}}` on stderr with exit 1
+ * (`[file:line @ c77af189]` `src/cli.rs:745-753`). The code is quoted into our reject, never
+ * re-typed into a vocabulary of ours that would go stale the moment herdr adds a case. */
+export function readHerdrErrorCode(stderr) {
+    const root = parseJsonObject(stderr);
+    if (root === null)
+        return undefined;
+    const error = root.error;
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const code = error.code;
+    return typeof code === "string" && code.length > 0 ? code : undefined;
+}
+function parseJsonObject(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        // Not JSON at all is what a usage error looks like: `[측정 2026-09-14]` a bad flag prints
+        // plain `usage: …` text and exits 2. Declining is the whole handling it needs.
+        return null;
+    }
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+        ? parsed
+        : null;
+}
+/**
+ * May we close the pane we just opened?
+ *
+ * Only with WITHIN-GENERATION proof: the pane we are looking at right now must be the same id AND
+ * the same terminal our creation receipt named, and it must be EMPTY. A bare pane id is not
+ * authority (see `HerdrOrphanReason`), and the honest answer when the proof does not hold is to
+ * leave the pane alone and say so by name.
+ *
+ * EMPTY IS TWO QUESTIONS, NOT ONE, and asking only the second one killed a living sibling.
+ * `[측정 oracle 2026-09-18, LIVE run XimC19]` this predicate refused to close only when herdr had
+ * already been told the pane's `agent_session`. On the Claude rail that id arrives through a
+ * SEPARATE hook round trip the child makes after it starts (`[file:line @ c77af189]`
+ * `src/integration/assets/claude/herdr-agent-state.sh:60-99`, one shot, 0.5s socket deadline,
+ * failures swallowed), so a pane holding a booted child read as empty and was closed 0.585s after
+ * that child wrote its own birth record. Occupancy — herdr naming an AGENT in the pane — is now the
+ * first refusal, and it does not depend on anybody having reported a session id. A bound that
+ * expires is not authority either: no finite wait converts "nobody told us the id" into "nobody is
+ * there".
+ *
+ * WHY THE RECLAIM IS STILL PANE-LEVEL ON A TAB-FIRST RAIL. `[측정 2026-09-15, private server]`
+ * `tab close` takes a bare `tab_id` and nothing else: it closed a tab holding a RUNNING agent and
+ * answered `{"result":{"type":"ok"}}`, so adopting it would be claiming authority over every pane
+ * a stranger had put in our tab meanwhile. Closing the one pane we own is strictly narrower and it
+ * is enough — `[측정]` closing the sole pane of a tab removed the tab with it (`tab get` →
+ * `tab_not_found`, no empty tab left behind), and on a tab that had gained a second pane the same
+ * close took only ours and left the tab and the stranger's pane alive. Fail-closed in both
+ * directions, with the proof we already had.
+ *
+ * A TOCTOU window remains between this decision and the close, and it is not closable through the
+ * public API: `[file:line @ c77af189]` `src/api/schema/common.rs:33-36` gives `close_pane` only a
+ * `pane_id`, with no expected-terminal token to make the close conditional server-side. The window
+ * is named here rather than papered over.
+ */
+export function decideConditionalClose(created, current, getFailed) {
+    if (getFailed)
+        return { close: false, reason: "pane-get-failed" };
+    if (current === null)
+        return { close: false, reason: "pane-get-unparsable" };
+    if (current.paneId !== created.paneId)
+        return { close: false, reason: "pane-id-mismatch" };
+    if (current.terminalId !== created.terminalId)
+        return { close: false, reason: "terminal-id-mismatch" };
+    if (current.agent !== undefined)
+        return { close: false, reason: "agent-present" };
+    if (current.hasAgentSession)
+        return { close: false, reason: "agent-session-present" };
+    return { close: true };
+}
+/**
+ * Open the sibling.
+ *
+ * ORDER IS THE ARGUMENT, and it is a different argument from the tmux rail's. There, validation
+ * could promise that "nothing above can leave a window behind"; here the tab create IS a mutation
+ * and the start can still fail after it. So everything decidable — context, backend, placement
+ * input, caller id, task, model, cwd, and the encoded argv's control characters — is decided
+ * BEFORE it, and the only failures that can survive into the two-step region are herdr's own.
+ *
+ * ONE READ SITS BETWEEN THEM, and it creates nothing: `pane get <HERDR_PANE_ID>` asks herdr which
+ * workspace the caller is in. It comes LAST among the refusals so a call we would have rejected
+ * anyway never reaches the herdr CLI, and its four failure modes are refusals rather than launch
+ * failures because a read leaves no tab behind.
+ *
+ * `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) {
+    const context = resolveHerdrContext(env);
+    if (!context.ok)
+        return { ok: false, reason: context.reason };
+    const tmuxPlacement = rejectTmuxPlacementInHerdrContext(params.placement);
+    if (tmuxPlacement !== null)
+        return { ok: false, reason: tmuxPlacement };
+    if (!HERDR_FRESH_CALL_BACKENDS.includes(params.backend)) {
+        // No tmux fallback, on purpose: a sibling opened on a rail the caller did not ask for is
+        // worse than a refusal they can read.
+        return { ok: false, reason: "herdr-backend-unsupported" };
+    }
+    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.
+    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 framing = composeFreshCallFraming({
+        backend,
+        callerGardenId,
+        nonce,
+        openingLine: HERDR_FRESH_CALL_OPENING_LINE,
+    });
+    const encoded = encodeBirthPrompt(framing, task);
+    if (!encoded.ok)
+        return { ok: false, reason: encoded.reason };
+    const composition = {
+        prompt: encoded.argv,
+        bootstrapPayload: buildOmpBootstrapPayload({ callerGardenId, nonce, task }),
+    };
+    const backendArgs = composeBackendArgs(backend, composition, model, () => {
+        // Unreachable: codex is not in the pilot set and was refused above. It throws rather than
+        // returning a plausible path, so a future widening cannot silently inherit a guess.
+        throw new Error("herdr-fresh-call: codex is not a pilot backend on this rail");
+    }, () => {
+        // Unreachable for the same reason, and refusing for the same reason: codex's `-C` names
+        // where a REMOTE thread opens, and this rail has no app-server to name it to.
+        throw new Error("herdr-fresh-call: codex is not a pilot backend on this rail");
+    });
+    // The server checks EVERY argument, not just the prompt, so we check every argument too —
+    // while it is still free to refuse.
+    if (backendArgs.some(containsControlChar))
+        return { ok: false, reason: "herdr-argv-control-character" };
+    // Which workspace is the caller in? herdr's own answer about the caller's own pane — not the
+    // focused workspace, not a listing, and not the `w<N>:` prefix of an id this rail treats as
+    // opaque. A pane we cannot read is a refusal: falling back to an omitted `--workspace` would
+    // open the sibling wherever the operator happens to be looking, under a green receipt.
+    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" };
+    // The answer must be about the pane we ASKED about. A readable reply describing some other
+    // pane carries some other pane's workspace, and using it would open the sibling in a
+    // workspace the caller never named — the exact silent relocation this whole policy exists to
+    // refuse, arriving through the read instead of through an omitted --workspace.
+    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(buildHerdrTabCreateArgs({
+        workspaceId: callerPane.workspaceId,
+        ...(cwd === undefined ? {} : { cwd }),
+    }));
+    if (tabRun.status !== 0) {
+        // WHETHER ANYTHING EXISTS depends on WHO failed, and the stderr says which. herdr's own
+        // envelope means herdr answered — it declined before making a tab. NO envelope means we
+        // never heard from it at all: `createHerdrRunner` reports its own timeout/kill/spawn
+        // failure as the same nonzero status with a plain-text stderr, and a `tab create` we
+        // killed mid-flight may well have created the tab. Claiming "nothing was created" there
+        // would send an operator away from a tab that is sitting on their screen.
+        const code = readHerdrErrorCode(tabRun.stderr);
+        return {
+            ok: false,
+            reason: "herdr-tab-create-failed",
+            ...(code === undefined ? {} : { herdrErrorCode: code }),
+            recovery: code === undefined ? indeterminate() : nothingCreated(),
+        };
+    }
+    const tab = parseHerdrTabCreateResponse(tabRun.stdout);
+    if (tab === null) {
+        // A tab may exist and its coordinates are precisely what we could not read. Diffing
+        // `tab list` to find "the new one" is the guess this rail refuses, so it is NAMED instead.
+        return { ok: false, reason: "herdr-tab-create-unparsable", recovery: indeterminate() };
+    }
+    const pane = tab.rootPane;
+    if (pane.hasAgentSession) {
+        // A brand-new tab's initial pane holding an agent is not a pane we understand. Starting
+        // into it would either be refused by herdr as busy or, worse, land beside somebody else's
+        // sibling. Declining here also means the reclaim below correctly REFUSES to close it.
+        return { ok: false, reason: "herdr-tab-root-pane-occupied", recovery: await reclaim(pane, run) };
+    }
+    const agentName = herdrAgentNameFromNonce(nonce);
+    const startRun = await run(buildHerdrAgentStartArgs({
+        agentName,
+        kind: HERDR_AGENT_KIND[backend],
+        paneId: pane.paneId,
+        backendArgs,
+    }));
+    if (startRun.status !== 0) {
+        return {
+            ok: false,
+            reason: "herdr-agent-start-failed",
+            ...errorCode(startRun.stderr),
+            recovery: await reclaim(pane, run),
+        };
+    }
+    const started = parseHerdrAgentStartResponse(startRun.stdout);
+    if (started === null) {
+        return { ok: false, reason: "herdr-agent-start-unparsable", recovery: await reclaim(pane, run) };
+    }
+    // EVERY reclaim below starts from the TAB-CREATE receipt, never from what the start reported:
+    // if those two disagree, the create receipt is the only coordinate we have authority over.
+    // The tab is checked too when herdr named one — the whole point of this policy is WHICH tab
+    // the sibling is in, so a start that reports another one is the same defect as another pane.
+    if (started.pane.paneId !== pane.paneId ||
+        started.pane.terminalId !== pane.terminalId ||
+        (started.pane.tabId !== undefined && started.pane.tabId !== tab.tabId)) {
+        // Readable, and actionable — so it is not folded into `unparsable`. Something started
+        // somewhere other than the pane we opened, and a green receipt would have pointed the
+        // caller at a coordinate that never held their sibling.
+        return { ok: false, reason: "herdr-agent-start-pane-drift", recovery: await reclaim(pane, run) };
+    }
+    if (!argvMatchesRequest(started.argv, backend, backendArgs)) {
+        // The framing is the argv. A sibling started with a different one is a sibling we did not
+        // compose, and nothing downstream would ever reveal it.
+        return { ok: false, reason: "herdr-agent-start-argv-drift", recovery: await reclaim(pane, run) };
+    }
+    // THE WITNESS IS THE LAST QUESTION, AND IT IS NOT A VETO. Everything above could disqualify the
+    // launch; this cannot. `settleAgentWitness` only re-READS, and its two answers are "herdr knows
+    // the session id" and "it does not yet" — both of which are successful launches. It fails only
+    // when a readable reply says the agent we started is no longer the agent in our pane.
+    const settled = await settleAgentWitness({
+        agentName,
+        kind: HERDR_AGENT_KIND[backend],
+        created: pane,
+        tabId: tab.tabId,
+        started: started.pane,
+        run,
+        clock,
+    });
+    if (!settled.ok) {
+        return { ok: false, reason: "herdr-agent-start-vanished", recovery: await reclaim(pane, run) };
+    }
+    return {
+        ok: true,
+        receipt: {
+            backend,
+            requestedKind: HERDR_AGENT_KIND[backend],
+            model,
+            ...(cwd === undefined ? {} : { cwd }),
+            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
+            // operator reads and the coordinate we would close must be the same one.
+            herdrWorkspaceId: tab.workspaceId,
+            herdrTabId: tab.tabId,
+            herdrPaneId: started.pane.paneId,
+            herdrTerminalId: started.pane.terminalId,
+            nonce,
+            witness: settled.witness,
+        },
+    };
+}
+function errorCode(stderr) {
+    const code = readHerdrErrorCode(stderr);
+    return code === undefined ? {} : { herdrErrorCode: code };
+}
+/** herdr declined by name, so nothing exists to reclaim. Not an unreclaimed orphan: there is no
+ * pane, and no `pane get` was attempted. */
+function nothingCreated() {
+    return { outcome: "none" };
+}
+/** We cannot say whether a tab exists — our own bound cut the call off, or the reply was
+ * unreadable. Nothing is closed, and the receipt says so instead of guessing either way. */
+function indeterminate() {
+    return { outcome: "unknown" };
+}
+/**
+ * The launch already succeeded. Wait — bounded, read-only — to see whether herdr learns the new
+ * agent's session id, and rebind every read to the launch we actually made.
+ *
+ * WHY THIS EXISTS AT ALL. `[측정 oracle 2026-09-18, LIVE run XimC19]` the rail used to treat a
+ * successful `agent start` whose reply carried no `agent_session` as a launch failure and CLOSED
+ * the pane. The premise was that herdr waits for detection before answering; it does not — it waits
+ * for `agent_status ∈ {idle,done}` plus `interactive_ready` (`[file:line @ c77af189]`
+ * `src/cli/agent.rs:592-615`) — and on the Claude rail the session id arrives afterwards, through
+ * the child's own hook. A booted Claude Code sibling was killed 0.585s after it wrote its birth
+ * record, and the same bytes passed five minutes later only because that child took 1m27s to
+ * become ready.
+ *
+ * WHAT EACH READ PROVES. `agent get <exact name>` — never a listing. Every reply is rebound to the
+ * CREATE receipt (pane id, terminal id, tab id when herdr names one) and to what we asked for
+ * (agent name, kind), because a reply about a different agent answers a different question. A read
+ * that drifts is not a slow witness; it is `herdr-agent-start-vanished`, and only then may the
+ * reclaim below even be consulted.
+ *
+ * WHAT EXPIRY DOES NOT BUY. Nothing. The window closing means we stop asking, and the launch is
+ * still a success with `witness: unavailable`. No finite bound turns "herdr was never told the id"
+ * into "there is nobody there" — the reporter is one-shot and swallows its failures.
+ */
+export async function settleAgentWitness(params) {
+    if (params.started.hasAgentSession)
+        return { ok: true, witness: { state: "reported", reads: 0, settleMs: 0 } };
+    const settleMs = params.settleMs ?? HERDR_AGENT_SESSION_SETTLE_MS;
+    const pollMs = params.pollMs ?? HERDR_AGENT_SESSION_POLL_MS;
+    const startedAt = params.clock.now();
+    let reads = 0;
+    /** Did ANY readable reply rebind the agent to the pane we opened? Nothing else licenses a
+     * receipt sentence about the sibling still being there. */
+    let observed = false;
+    for (;;) {
+        await params.clock.sleep(pollMs);
+        const getRun = await params.run(buildHerdrAgentGetArgs(params.agentName));
+        reads += 1;
+        const elapsed = params.clock.now() - startedAt;
+        // A failed or unreadable read is NOT evidence that the agent is gone. herdr answers a
+        // missing agent with its own error envelope, but so does a socket that blinked, and this
+        // module cannot tell those apart from an exit status. So an unreadable read only costs a
+        // poll; the ONLY thing that names a vanished launch is a readable reply that disagrees.
+        const agent = getRun.status === 0 ? parseHerdrAgentGetResponse(getRun.stdout) : null;
+        if (agent !== null) {
+            // REBINDING IS ALL FIVE AXES, PRESENT AND EQUAL `[sol 재검 2026-09-18]`. A reply that
+            // OMITS tab, name or kind cannot carry the exact-rebinding claim this loop makes, so it
+            // is not a usable witness — we keep polling. It is deliberately NOT drift: treating a
+            // missing optional field as disagreement would fail a healthy launch on a vendor that
+            // simply answered with less. Only a field that IS there and DISAGREES names a vanished
+            // sibling, because only that is a reply about somebody else.
+            const bound = agent.paneId === params.created.paneId &&
+                agent.terminalId === params.created.terminalId &&
+                agent.tabId === params.tabId &&
+                agent.agentName === params.agentName &&
+                agent.agent === params.kind;
+            const drifted = agent.paneId !== params.created.paneId ||
+                agent.terminalId !== params.created.terminalId ||
+                (agent.tabId !== undefined && agent.tabId !== params.tabId) ||
+                (agent.agentName !== undefined && agent.agentName !== params.agentName) ||
+                (agent.agent !== undefined && agent.agent !== params.kind);
+            if (drifted)
+                return { ok: false, reads };
+            if (bound) {
+                observed = true;
+                if (agent.hasAgentSession)
+                    return { ok: true, witness: { state: "reported", reads, settleMs: elapsed } };
+            }
+        }
+        if (elapsed >= settleMs) {
+            // The two expiry words are the whole point of `observed`: we may only say the agent is
+            // still in our pane if a readable reply said so.
+            return {
+                ok: true,
+                witness: { state: observed ? "unavailable" : "unobserved", reads, settleMs: elapsed },
+            };
+        }
+    }
+}
+/** Reclaim the pane we opened — conditionally, or not at all. */
+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)
+        return { outcome: "orphan-unreclaimed", paneId: pane.paneId, reason: decision.reason };
+    const closeRun = await run(buildHerdrPaneCloseArgs(pane.paneId));
+    if (closeRun.status !== 0)
+        return { outcome: "orphan-unreclaimed", paneId: pane.paneId, reason: "close-failed" };
+    return { outcome: "closed", paneId: pane.paneId, terminalId: pane.terminalId };
+}
+/** 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 = {
+    "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)",
+    "task-empty": "a sibling opened with nothing to do is a window nobody asked for",
+    "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-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-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",
+    "cwd-missing": "the requested start directory does not exist",
+    "cwd-not-directory": "the requested start path is not a directory",
+    "herdr-tab-create-failed": "the tab create did not succeed — read the recovery line below 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-root-pane-occupied": "the new tab's initial pane already holds an agent, so nothing was started into it",
+    "herdr-agent-start-failed": "herdr refused to start the agent 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-vanished": "herdr started the agent and then answered about a different one, so the sibling it named is not in the pane we opened",
+    "herdr-agent-start-argv-drift": "herdr echoed an argv that is not the one we composed",
+};
+/** How a recovery reads to an operator who has to decide whether to go look. `[측정 2026-09-15]`
+ * closing the tab's only pane takes the tab with it, so the closed line says that — conditionally,
+ * because a pane a stranger added meanwhile keeps the tab alive and this rail never closed it. */
+/** The witness line an operator reads. `unavailable` is a DIAGNOSIS on a successful launch, so it
+ * says what it costs (the peers placement column has nothing to join) and what it does not (the
+ * address was never a pane; it arrives in the sibling's callback). */
+function renderWitness(witness) {
+    const cost = `${witness.reads} read(s), ${witness.settleMs}ms`;
+    switch (witness.state) {
+        case "reported":
+            return `reported to herdr after ${cost} — its placement can be joined in entwurf_peers`;
+        case "unavailable":
+            return `unavailable after ${cost} — herdr was not told this agent's session id, which its own reporter may never send. herdr DID still show this agent in the pane we opened when we last read it; its peers placement column will read unobserved, and its garden id still arrives in the callback`;
+        default:
+            // `[sol 재검 2026-09-18]` the branch that used to borrow the sentence above. Every read
+            // failed or could not be bound to our pane, so this receipt asserts NOTHING about the
+            // sibling's current state — and says so, rather than letting a reader infer liveness
+            // from a word that merely means "we stopped asking".
+            return `unobserved after ${cost} — no readable answer about this agent ever came back, so this receipt says nothing about whether the sibling is running. Nothing was reclaimed on that silence: an unreadable read is not evidence that a sibling is gone. Its peers placement column will read unobserved, and its garden id still arrives in the callback`;
+    }
+}
+function renderRecovery(recovery) {
+    switch (recovery.outcome) {
+        case "none":
+            return "  recovery: none — herdr declined by name before making anything, so there is nothing to go look at\n";
+        case "unknown":
+            return "  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";
+        case "closed":
+            return `  recovery: closed ${recovery.paneId} (its terminal still matched the create receipt; the new tab went with it unless something else had joined it)\n`;
+        default:
+            return `  recovery: orphan-unreclaimed:${recovery.reason} (${recovery.paneId}) — this pane was NOT closed, on purpose\n`;
+    }
+}
+/** The failure header, which must not claim more than the recovery below it knows. An earlier
+ * shape said "failed after the tab was created" on EVERY post-attempt failure, including the one
+ * whose own hint said nothing was created. */
+function renderFailureHeader(recovery) {
+    switch (recovery.outcome) {
+        case "none":
+            return "entwurf_fresh_call failed at the tab create step";
+        case "unknown":
+            return "entwurf_fresh_call failed at the tab create step with an UNKNOWN outcome";
+        default:
+            return "entwurf_fresh_call failed after the tab was created";
+    }
+}
+/**
+ * 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.
+ */
+export function renderHerdrFreshCall(result) {
+    if (!result.ok) {
+        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.`,
+                isError: true,
+            };
+        }
+        const code = result.herdrErrorCode === undefined ? "" : ` [herdr: ${result.herdrErrorCode}]`;
+        return {
+            text: `${renderFailureHeader(result.recovery)}: ${result.reason}${code} — ${hint}.\n` +
+                renderRecovery(result.recovery),
+            isError: true,
+        };
+    }
+    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`) +
+            `  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` +
+            `  nonce:    ${r.nonce}\n` +
+            `  witness:  ${renderWitness(r.witness)}\n` +
+            `\n` +
+            `This is a LAUNCH receipt: herdr created a tab and was asked to start the agent above in it. 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 — it calls entwurf_v2 back with the nonce above as its first ` +
+            `action, and the sender envelope of THAT message is the address. Nothing is polling for it; if it never ` +
+            `comes, the pane is visible and can be read directly.`,
+        isError: false,
+    };
+}
+/** How long a herdr command may take. `[측정, herdr 0.9.1 `agent start --help`]` the start verb waits
+ * for interactive readiness with a default of 30s and a documented ceiling of 300s, so the start
+ * bound is that ceiling: cutting it shorter would kill a launch herdr was still legitimately
+ * waiting on. Every other verb is a socket round trip and gets the short bound. */
+export const HERDR_START_TIMEOUT_MS = 300_000;
+/**
+ * How long HERDR may wait for interactive readiness — passed as `--timeout`, and NOT the same
+ * number as the bound above.
+ *
+ * `[측정 2026-09-17, oracle, LIVE]` the rail never passed this flag, so herdr used its own 30s
+ * default while our process bound sat at 300s. A Claude Code cold start in a fresh pane exceeds
+ * 30s on this host, so herdr gave up on an agent that WAS alive and starting, and the rail reported
+ * `herdr-agent-start-failed [herdr: timeout]` with an unreclaimed pane holding a healthy sibling.
+ * The gate had never seen it because its LIVE cell pinned a runtime that starts fast.
+ *
+ * It is deliberately BELOW `HERDR_START_TIMEOUT_MS`. The two bounds race, and herdr has to lose:
+ * if our process kill landed first we would learn nothing but "no exit status", while herdr's own
+ * expiry answers with a named `timeout` we can report and reclaim from. Sixty seconds of daylight
+ * is the margin.
+ */
+export const HERDR_START_READY_MS = 240_000;
+export const HERDR_CLI_TIMEOUT_MS = 30_000;
+/**
+ * How long we keep ASKING herdr for the agent session of a launch that already succeeded — a
+ * SEPARATE stage from `HERDR_START_READY_MS`, which is herdr's own interactive-readiness budget and
+ * has by then already returned.
+ *
+ * `[측정 oracle 2026-09-18, LIVE runs XimC19 / TCatjF]` the same bytes on the same host answered
+ * twice within five minutes: the fast run returned a successful `agent start` in 4.9s with no
+ * `agent_session`, and the slow one took 1m27s and had it. Nothing about the launch differed —
+ * upstream returns on `agent_status ∈ {idle,done}` plus `interactive_ready`
+ * (`[file:line @ c77af189]` `src/cli/agent.rs:592-615`) and never waits for a session report, so
+ * the slow run's 85s of extra waiting was not a bound, it was a race the wait happened to hide.
+ *
+ * THIS NUMBER IS A PROPOSAL, and it is honest to say so. The red run still had no session 585ms
+ * after the child's own birth record, the reporter's socket deadline alone is 0.5s, and hook
+ * scheduling sits outside both — so the observed pair justifies neither a few hundred ms nor the
+ * slow run's 85s. It is set to one bounded window big enough to absorb an ordinary hook tail and
+ * small enough that nobody waits on it, and the LIVE distribution is what may move it.
+ *
+ * WHAT IT IS NOT: expiry is never authority to close anything. A session id that never arrives is
+ * a launch we cannot NAME, not a launch that did not happen — the reporter is one-shot and
+ * swallows its own failures, so "never" is a reachable state for a perfectly healthy sibling.
+ */
+export const HERDR_AGENT_SESSION_SETTLE_MS = 5_000;
+/** How often we re-read during that window. Matched to the vendor's own start-poll cadence
+ * (`[file:line @ c77af189]` `src/cli/agent.rs:9`), because there is no reason to ask a server
+ * faster than it changes its own mind. */
+export const HERDR_AGENT_SESSION_POLL_MS = 100;
+/** How much of one herdr reply we are willing to hold. Every verb on this rail answers with one
+ * JSON object; a stream larger than this is not a reply we can parse, and an unbounded buffer would
+ * let a runaway child take the caller's memory with it. Overflow is reported as the same
+ * nonzero-status shape as any other failure rather than truncated into a parse we would believe. */
+export const HERDR_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+/**
+ * The production runner: argv array, no shell, explicit env, bounded — and ASYNCHRONOUS.
+ *
+ * WHY IT MUST NOT BLOCK `[측정 2026-09-14, C4 첫 LIVE]`. The first thing a sibling does is call its
+ * caller back on the caller's own control socket. On this rail the caller is, at that exact moment,
+ * inside `agent start` waiting for herdr to report readiness — up to 300s. A SYNCHRONOUS child wait
+ * holds the caller's event loop for that whole window, so the callback cannot be read, the sender
+ * times out and hangs up, and the caller's late reply then lands on a socket whose peer is gone.
+ * The runner is therefore async: the child runs while the loop keeps serving sockets and timers.
+ *
+ * A spawn that never produced an exit status (binary missing, timeout, signal) is mapped to a
+ * nonzero status with the failure on stderr — the SAME shape herdr's own error path produces, so
+ * the rail above has one thing to read. Nothing here looks at a terminal.
+ *
+ * The timeout KILLS: a bound that only stops waiting would leave the child holding a pane while we
+ * report it gone. SIGKILL, because a bound we cannot enforce is not a bound. Exactly one settle —
+ * `close`, `error` and the timeout all race, and whichever arrives first is the only answer.
+ */
+export function createHerdrRunner(bin, env, spawn, 
+// The production bounds ARE the exported constants; this parameter exists so a gate can prove
+// the kill and the cap on a real child within a gate's patience instead of waiting 30 seconds
+// for them. The composition root passes nothing, and a structural cell keeps it that way — a
+// caller who could shorten the start bound could kill a launch herdr was still waiting on.
+bounds = {
+    startMs: HERDR_START_TIMEOUT_MS,
+    cliMs: HERDR_CLI_TIMEOUT_MS,
+    maxOutputBytes: HERDR_MAX_OUTPUT_BYTES,
+}) {
+    return (args) => {
+        const timeout = args[0] === "agent" && args[1] === "start" ? bounds.startMs : bounds.cliMs;
+        return new Promise((resolve) => {
+            let stdout = "";
+            let stderr = "";
+            let settled = false;
+            const child = spawn(bin, [...args], { env, shell: false });
+            const settle = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(result);
+            };
+            const failed = (why, out = stdout) => settle({ status: 1, stdout: out, stderr: `herdr ${args.join(" ")}: ${why}` });
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                failed(`no exit status (timeout ${timeout}ms or signal null)`);
+            }, timeout);
+            // The bound must not itself keep this process alive once the answer is in.
+            timer.unref?.();
+            const collect = (into) => (chunk) => {
+                const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+                if (into === "stdout")
+                    stdout += text;
+                else
+                    stderr += text;
+                if (stdout.length + stderr.length <= bounds.maxOutputBytes)
+                    return;
+                child.kill("SIGKILL");
+                failed(`output exceeded ${bounds.maxOutputBytes} bytes`, "");
+            };
+            child.stdout?.on("data", collect("stdout"));
+            child.stderr?.on("data", collect("stderr"));
+            child.on("error", (error) => failed(error.message, ""));
+            child.on("close", (code, signal) => {
+                if (code === null) {
+                    // Killed by a signal: herdr said nothing, so we say that rather than inventing
+                    // an exit code that would read as herdr's own refusal.
+                    failed(`no exit status (timeout ${timeout}ms or signal ${String(signal)})`);
+                    return;
+                }
+                settle({ status: code, stdout, stderr });
+            });
+        });
+    };
+}