@junghanacs/entwurf 0.22.0 → 0.23.1

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

@@ -0,0 +1,213 @@
+/**
+ * herdr-placement — the PURE half of the placement evidence axis (#116 S1).
+ *
+ * WHAT THIS IS FOR. A citizen opened inside herdr is visible in one of herdr's panes.
+ * That pane is an EPHEMERAL VIEW, never an address and never a liveness receipt
+ * (AGENTS Hard Rule 16, `docs/mux-launch-rail.md` §7). It earns a column in
+ * `entwurf_peers` for one reason: on a herdr host the operator's own question is
+ * "which pane is that one in", and answering it by hand means reading two listings
+ * side by side.
+ *
+ * WHY THIS JOIN IS EXACT EVIDENCE AND NOT A GUESS. §7 admitted exactly two forms of
+ * exact placement evidence (our own launch receipt, and a peer's verifiable
+ * self-report) and named the guesses it refuses: window title, cwd match, and time
+ * proximity. This is a THIRD form and it belongs to neither the receipts nor the
+ * guesses: herdr reports the native session id its OWN OFFICIAL integration told it,
+ * and `nativeSessionId` is unique across the whole meta-store (Hard Rule 7). Two
+ * independently-owned facts meet on one unique key. Nothing here narrows candidates
+ * by cwd, reads a title, or prefers the nearest timestamp. §7 was amended in the same
+ * change that added this module; if the two ever disagree, §7 is the owning document.
+ *
+ * THE TWO AXES ARE NOT EQUALLY EXACT, AND THE DIFFERENCE IS NAMED. On the claude axis
+ * the reported value IS the key, byte for byte. On the pi axis it is a session FILE
+ * PATH, and the key is recovered from that filename by a strict conversion measured on
+ * pi 0.85.1 — a VENDOR FLOOR, not a key equality. Calling both "a unique-key join"
+ * would hide which one can drift when a vendor renames a file. The conversion is
+ * deliberately strict at both ends so that drift lands as a missed join, never a wrong
+ * one, and a listing that declined to read anything says so (see `declinedReports`).
+ *
+ * ONE READ, NO WATCHER. The observer performs exactly ONE `pane list` read for a
+ * whole listing and never retries. herdr publishes no event that says "this pane's
+ * `agent_session` is now settled" — measured on herdr 0.9.0: `pane.updated` is the
+ * only event whose payload carries `agent_session` and plugin `[[events]]` refuses
+ * that name, `events.subscribe` offers three pane kinds and none of them carry it,
+ * and `pane.agent_detected` arrives BEFORE the session reference exists. A retry loop
+ * around that gap is a discovery watcher, which §7 forbids by name. So a citizen
+ * whose pane has not reported yet reads `none` on this pass and is simply asked again
+ * next time.
+ *
+ * FACTS, NOT VERBS. Nothing here returns a transport, a target, or a suggestion. A
+ * pane id must never reach dispatch: `entwurf_v2` resolves its rail from the record
+ * and a live probe, and a placement that is one server restart from being false has
+ * no business in that decision.
+ */
+export const UNOBSERVED_PLACEMENT = { kind: "unobserved" };
+export const NO_PLACEMENT = { kind: "none" };
+export const AMBIGUOUS_PLACEMENT = { kind: "ambiguous" };
+/**
+ * The OFFICIAL integration reports this join accepts, and nothing else.
+ *
+ * WHY THIS TABLE EXISTS. herdr accepts a session reference from any integration,
+ * including one a user wrote (`integrations.mdx:65-90 @ c77af189`), and the row
+ * carries who reported it in `agent_session.agent` / `.source`. Reading only
+ * `kind`/`value` would have let a third party's report stand in for the placement
+ * owner's own — and "the placement owner reported it" is the entire reason
+ * `docs/mux-launch-rail.md` §7 admits this as exact evidence. So the triple is
+ * pinned: source, agent, AND the shape that source is measured to emit. A row that
+ * misses any leg carries no key.
+ *
+ * `backend` is the meta-record backend this report may speak for. It is checked at
+ * resolve time so a claude-reported pane can never be handed to a pi citizen whose
+ * native id happens to collide.
+ */
+const OFFICIAL_REPORTS = {
+    "herdr:claude": { agent: "claude", kind: "id", backend: "claude-code" },
+    "herdr:pi": { agent: "pi", kind: "path", backend: "pi" },
+};
+/**
+ * A pi session filename, measured 2026-09-14 on pi 0.85.1:
+ *
+ *   2026-09-14T05-17-03-979Z_01a09e58-f06a-70e8-b14a-1f0f0c7f7c7d.jsonl
+ *   └────────── start stamp ─────────┘ └──────── nativeSessionId ────────┘
+ *
+ * WHY THIS IS PINNED HERE AND NOT INFERRED. The uuid is the join key and it lives in
+ * a VENDOR filename, so this rule depends on pi's naming and would break silently if
+ * pi changed it. **Vendor floor: pi 0.85.1, measured 2026-09-14** — whether that layout
+ * is a vendor contract or a convention is NOT measured, so this is the one place in the
+ * axis that can drift under us. It is therefore strict on both ends — the name must end
+ * in `.jsonl` and the tail after the last `_` must be a well-formed uuid — and a name
+ * that fails either test yields no key at all rather than a substring that happens to
+ * look plausible. Drift then lands as a DECLINED report (the citizen reads `unobserved`,
+ * not `none`), never as a wrong join onto someone else's pane.
+ */
+const PI_SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const PI_SESSION_SUFFIX = ".jsonl";
+export function piNativeSessionIdFromPath(value) {
+    if (!value.endsWith(PI_SESSION_SUFFIX))
+        return null;
+    const stem = value.slice(0, -PI_SESSION_SUFFIX.length);
+    const base = stem.slice(stem.lastIndexOf("/") + 1);
+    const cut = base.lastIndexOf("_");
+    if (cut < 0)
+        return null;
+    const candidate = base.slice(cut + 1);
+    return PI_SESSION_UUID.test(candidate) ? candidate : null;
+}
+export function joinKeyOf(row) {
+    if (row.sessionSource === null)
+        return null;
+    const official = OFFICIAL_REPORTS[row.sessionSource];
+    // An unmeasured source — a herdr version we have not run, or a third-party
+    // integration. Declined on purpose: coercing it would invent a rule, and the
+    // whole exact-evidence argument rests on WHO reported.
+    if (official === undefined)
+        return null;
+    if (row.agent !== official.agent)
+        return null;
+    if (row.sessionKind !== official.kind)
+        return null;
+    if (row.sessionValue === null || row.sessionValue.length === 0)
+        return null;
+    const nativeSessionId = official.kind === "id" ? row.sessionValue : piNativeSessionIdFromPath(row.sessionValue);
+    return nativeSessionId === null ? null : { nativeSessionId, backend: official.backend };
+}
+export function buildPlacementIndex(rows) {
+    const byNativeSessionId = new Map();
+    const ambiguous = new Set();
+    let declinedReports = 0;
+    for (const row of rows) {
+        const entry = joinKeyOf(row);
+        if (entry === null) {
+            // Only a row that actually CARRIED a report counts as declined.
+            if (row.sessionSource !== null || row.sessionValue !== null)
+                declinedReports++;
+            continue;
+        }
+        const key = entry.nativeSessionId;
+        if (ambiguous.has(key))
+            continue;
+        const seen = byNativeSessionId.get(key);
+        if (seen !== undefined && seen.paneId !== row.paneId) {
+            byNativeSessionId.delete(key);
+            ambiguous.add(key);
+            continue;
+        }
+        byNativeSessionId.set(key, { ...entry, paneId: row.paneId });
+    }
+    return { byNativeSessionId, ambiguous, declinedReports };
+}
+/**
+ * Parse what `herdr pane list` printed. Returns `null` — "nobody looked" — for any
+ * payload this does not recognise, because a herdr that answered in a shape we cannot
+ * read has told us nothing, and reporting `none` for every citizen on that basis
+ * would be a fabricated measurement. A row missing `pane_id` is the one hard error:
+ * the whole payload is unreadable rather than partially trusted.
+ */
+export function parseHerdrPaneList(stdout) {
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const result = raw.result;
+    if (typeof result !== "object" || result === null)
+        return null;
+    const panes = result.panes;
+    if (!Array.isArray(panes))
+        return null;
+    const rows = [];
+    for (const pane of panes) {
+        if (typeof pane !== "object" || pane === null)
+            return null;
+        const paneId = pane.pane_id;
+        if (typeof paneId !== "string" || paneId.length === 0)
+            return null;
+        const session = pane.agent_session;
+        if (typeof session !== "object" || session === null) {
+            rows.push({ paneId, agent: null, sessionSource: null, sessionKind: null, sessionValue: null });
+            continue;
+        }
+        const agent = session.agent;
+        const source = session.source;
+        const kind = session.kind;
+        const value = session.value;
+        rows.push({
+            paneId,
+            agent: typeof agent === "string" ? agent : null,
+            sessionSource: typeof source === "string" ? source : null,
+            sessionKind: kind === "id" || kind === "path" ? kind : null,
+            sessionValue: typeof value === "string" ? value : null,
+        });
+    }
+    return rows;
+}
+/**
+ * The whole decision, for one citizen. A `null` index is the no-herdr host and every
+ * citizen on it reads `unobserved` — which is why this takes the index rather than a
+ * reader: the read happened once, above, and this stays pure.
+ */
+export function resolvePlacement(index, identity) {
+    if (index === null)
+        return UNOBSERVED_PLACEMENT;
+    if (index.ambiguous.has(identity.nativeSessionId))
+        return AMBIGUOUS_PLACEMENT;
+    const entry = index.byNativeSessionId.get(identity.nativeSessionId);
+    if (entry !== undefined) {
+        // The reporting integration must speak for THIS citizen's backend. A pi
+        // integration reporting an id that collides with a claude-code record is a
+        // contradiction, not a placement, and we decline to claim either way.
+        return entry.backend === identity.backend ? { kind: "herdr-pane", paneId: entry.paneId } : UNOBSERVED_PLACEMENT;
+    }
+    // No join. `none` is only honest when the read was COMPLETE — if any report was
+    // declined, the thing we did not read might have been this one.
+    return index.declinedReports > 0 ? UNOBSERVED_PLACEMENT : NO_PLACEMENT;
+}
+/** Render one observation as the listing's column value. `herdr <pane>` says WHERE it
+ * was seen and by WHOM, so a reader never mistakes the pane id for one of ours. */
+export function renderPlacement(placement) {
+    return placement.kind === "herdr-pane" ? `herdr ${placement.paneId}` : placement.kind;
+}

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

@@ -85,22 +85,46 @@
  *     the session the window is actually in. It still reports no `pane_current_path`, and
  *     there is no "session created" field because nothing here creates one.
  */
-import { randomBytes } from "node:crypto";
 import { classifyTmuxCwd } from "./classify-tmux-cwd.js";
 import { CODEX_CALLER_SEAT_HINT, resolveCodexCallerSeat, } from "./codex-caller-seat.js";
 import { CODEX_CALLER_PREFLIGHT_HINT, CODEX_LAUNCH_CWD_PREFLIGHT_HINT, CODEX_PREFLIGHT_HINT, codexLaunchCwdFreshPreflight, } from "./codex-fresh-preflight.js";
 import { COPILOT_PREFLIGHT_HINT, copilotFreshPreflight, } from "./copilot-fresh-preflight.js";
+import { buildOmpBootstrapPayload, composeBackendArgs, composeFreshCallPrompt, FRESH_CALL_BACKENDS, FRESH_CALL_CALLBACK_TOOL, isSafeFreshCallModel, MODEL_MAX_CHARS, mintNonce, normalizeFreshCallInputs, OMP_BOOTSTRAP_FLAG, OMP_BOOTSTRAP_VERSION, TASK_MAX_CHARS, } from "./fresh-call-composition.js";
 import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, } from "./mux-launch.js";
 import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
 import { resolveCodexDefaultSocketPath } from "./native-push/codex-ws-client.js";
 import { OMP_PREFLIGHT_HINT, ompFreshPreflight } from "./omp-fresh-preflight.js";
 import { classifyTmuxSessionName, resolveTmuxSessionId } from "./resolve-tmux-session.js";
-/** The backends this rail can open. Fixed set, not a profile — a further one is a decision,
- * not a config entry. `copilot` was added by #82 RAIL 9, `omp` by #87 Bundle C, and `codex`
- * by #95 after its system birth and app-server rails were measured. The set is joined to the
- * citizen backends by `check-harness-admission-parity`: a harness that mints records but is
- * missing HERE is not an unwired convenience, it is a release blocker. */
-export const FRESH_CALL_BACKENDS = ["pi", "claude-code", "copilot", "omp", "codex"];
+/**
+ * THE COMPOSITION MOVED, THE RAIL DID NOT (#116 S2-a). Backend argv, the first-turn framing and
+ * the nonce now live in `fresh-call-composition.ts`, which knows nothing about tmux, so the herdr
+ * rail can reach them without importing this file and dragging placement behind it. They are
+ * re-exported here unchanged: every existing caller, gate and mutant anchor that reads them from
+ * this module keeps reading the same names.
+ *
+ * The two wrappers below are where this rail states what only it can state — the sentence that
+ * says a sibling was opened in the operator's tmux session, and the Codex socket path. Both are
+ * arguments to the leaf rather than knowledge inside it.
+ */
+export { buildOmpBootstrapPayload, FRESH_CALL_BACKENDS, FRESH_CALL_CALLBACK_TOOL, isSafeFreshCallModel, MODEL_MAX_CHARS, mintNonce, OMP_BOOTSTRAP_FLAG, OMP_BOOTSTRAP_VERSION, TASK_MAX_CHARS, };
+/** What the tmux rail tells a sibling about where it woke up. The resume verb has no equivalent
+ * because it composes no first turn at all; a herdr rail will pass its own sentence here. */
+export const TMUX_FRESH_CALL_OPENING_LINE = "You are a fresh visible citizen that entwurf opened in the operator's tmux session.";
+/** Backend argv for THIS rail: the neutral dialect, with the two Codex facts only a rail can
+ * state — the socket resolved from the caller's env, and the directory this launch chose.
+ *
+ * `launchCwd` defaults to THIS process's own directory, which is what tmux gives a window opened
+ * with no `-c` (`[측정 ×2]`, module header). The default is that inherited fact rather than a
+ * convenience, so a caller that omits it still names the truth to codex. Both facts reach the
+ * leaf lazily, because a host with no Codex home must still be able to open pi and claude
+ * siblings — see `composeBackendArgs`. */
+export function buildBackendArgs(backend, composition, model, env = process.env, launchCwd = process.cwd()) {
+    return composeBackendArgs(backend, composition, model, () => resolveCodexDefaultSocketPath(env), () => launchCwd);
+}
+/** The first turn for THIS rail: the neutral framing under this rail's placement sentence. */
+export function buildFreshCallPrompt(params) {
+    return composeFreshCallPrompt({ ...params, openingLine: TMUX_FRESH_CALL_OPENING_LINE });
+}
 /**
  * The fixed runtime each backend resolves on PATH. Same reason `mux-launch` uses PATH rather
  * than a compiled-in location: the official binary is whatever the operator's environment gives
@@ -130,240 +154,6 @@ export const FRESH_CALL_RUNTIME = {
     omp: "omp",
     codex: "codex",
 };
-/**
- * The callback tool NAME differs per backend and that is not cosmetic: native pi exposes the
- * capability directly (`entwurf_v2`), while an MCP-hosted session reaches it under whatever
- * name that harness composes. Naming the wrong one costs the whole first turn.
- *
- * `[측정]` Copilot CLI 1.0.80 composes `<mcpServerName>-<mcpToolName>` — NOT Claude Code's
- * `mcp__<server>__<tool>`. Read from two independent sessions' own event logs
- * (`~/.copilot/session-state/<id>/events.jsonl`): `assistant.message.toolRequests[].name` and
- * `tool.execution_start.toolName` both carry `entwurf-bridge-entwurf_v2`, with
- * `mcpServerName`/`mcpToolName` beside them as the parts. Derive-and-measure, never copy a
- * sibling's spelling (`docs/adding-a-harness.md` step 5).
- *
- * `[측정]` omp 18.0.0 is the sharpest case for that rule: it mints
- * `mcp__${sanitizedServerName}_${normalizedToolName}` with a sanitizer whose charset is
- * `[a-z_]` (`mcp/tool-bridge.ts:351-357`, `:396`), so the DIGIT IN `entwurf_v2` IS EATEN and the
- * hyphen in the server key becomes an underscore — the model-facing name is
- * `mcp__entwurf_bridge_entwurf_v`, not `..._entwurf_v2` and not Claude's double-underscore form.
- * Confirmed against a live tool dump of all seven bridge tools and a real session transcript
- * (`scripts/raw-omp-measure/README.md` "Tool-name dialect"). Unlike Copilot there is no second
- * permission dialect: omp's approval layer consults the same minted string (`source-audit.md`).
- */
-export const FRESH_CALL_CALLBACK_TOOL = {
-    pi: "entwurf_v2",
-    "claude-code": "mcp__entwurf-bridge__entwurf_v2",
-    copilot: "entwurf-bridge-entwurf_v2",
-    omp: "mcp__entwurf_bridge_entwurf_v",
-    codex: "mcp__entwurf_bridge__entwurf_v2",
-};
-/** Mirrors the `entwurf_v2` message bound. This is an INTERFACE cap for symmetry with the
- * delivery surface, not a claim that a task of this size was measured through tmux. An argv
- * that the OS refuses is a launch failure and fails loud — it never reads as a delivered task. */
-export const TASK_MAX_CHARS = 16000;
-export const MODEL_MAX_CHARS = 200;
-const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/:[\]-]*$/;
-/** A model is an explicit launch input, not ambient process state. The grammar admits canonical
- * pi provider/model ids, Claude model ids/aliases, and bracketed context variants, while refusing
- * whitespace and tmux control syntax. It is passed without a shell using each runtime's measured
- * CLI dialect: Pi takes `--model`, value; Claude Code takes `--model=value`. */
-export function isSafeFreshCallModel(model) {
-    return model.length > 0 && model.length <= MODEL_MAX_CHARS && MODEL_PATTERN.test(model);
-}
-/**
- * Backend argv AFTER the runtime path. Both orders are MEASURED, and both were measured by
- * getting them wrong first (rail §6-a):
- *
- *   pi          — prompt BEFORE `--entwurf-control`, then `--model`, value as TWO tokens.
- *                 Flag-first submitted no message; Pi rejects the equals form for `--model`.
- *   claude-code — prompt, then `--allowedTools=` and `--model=` as ONE token each. The space form
- *                 for allowedTools is variadic and eats the prompt as an option value.
- *   copilot     — the managed VERB first, then the prompt as the value of `-i/--interactive`,
- *                 `--model`, value as two tokens, and the policy as the explicit `--yolo`
- *                 token. Measured from `copilot --help` (1.0.80).
- *   omp         — NO positional prompt at all. The task rides `--entwurf-bootstrap`, a fixed
- *                 flag the installed birth extension registers, then `--model`, value as two
- *                 tokens, then the policy as `--approval-mode`, `yolo`. `-p/--print` remains
- *                 the flag this argv must never carry — it processes a prompt and EXITS,
- *                 closing the window on a sibling that has to stay open to be delivered to.
- *
- * Both pi/claude failures looked identical from outside: window open, record and socket minted,
- * no turn.
- *
- * For pi and claude-code the equals form is NOT a permission guarantee — on the measured host
- * the tool was already permitted, so the option's effect was unobservable. What was observed is
- * that it does no harm to the argv. Permission stays a documented host precondition there.
- *
- * Copilot is the backend where the policy IS carried explicitly (step 9 clause 2), and three of
- * its argv facts are load-bearing:
- *
- *   - `copilot` is argv[0] of the RUNTIME `entwurf`, i.e. the managed verb — see
- *     `FRESH_CALL_RUNTIME`. Everything after it is forwarded byte-identical by
- *     `scripts/copilot-launch.sh`.
- *   - the prompt rides `--interactive`, never `-p/--prompt`: `-p` runs the prompt and EXITS,
- *     which would close the window on a sibling that is supposed to stay open and be delivered
- *     to. `--interactive <prompt>` is non-variadic, so the space form is safe here.
- *   - the policy token is `--yolo`, STATED HERE rather than left to the launcher: the launcher
- *     injects `--yolo` only when the argv names no policy, and step 9 clause 2 requires the
- *     fresh composition to state its model and permission policy explicitly, never to rely
- *     invisibly on someone else's default.
- *
- * `--yolo` is a GLG operator decision, not a drifted default. The first cut passed a
- * callback-only `--allow-tool=entwurf-bridge(entwurf_v2)` grant, and GLG's 2026-08-25 operator
- * LIVE measured the consequence: the fresh sibling's footer showed no `YOLO`, and every tool
- * its task needed stopped on a confirmation prompt, which made the sibling impractical to work
- * with. GLG then set the policy explicitly: a fresh Copilot sibling carries the same managed
- * `--yolo` profile a human-typed `entwurf copilot` gets. (Copilot 1.0.80 help: `--yolo` = all
- * tools + all paths + all URLs.) The permission GRAMMAR lesson from that first cut — Copilot's
- * `--allow-tool` takes `<mcp-server-name>(tool-name?)`, a different dialect from the
- * model-facing tool name — stays recorded in `docs/adding-a-harness.md` step 9's worked
- * example; it is a measured vendor fact even though this argv no longer uses it.
- *
- * OMP'S POLICY TOKEN IS THE ONE MOST EASILY ARGUED AWAY, SO READ THIS BEFORE DELETING IT.
- * `[측정]` omp 18.0.0's schema default for `tools.approvalMode` IS ALREADY `yolo`
- * (vendor doc `omp://approval-mode.md`; `omp config get tools.approvalMode` → `yolo` on the
- * acceptance host). So dropping `--approval-mode yolo` changes NOTHING observable: the callback
- * still fires, the LIVE smoke still passes, and the argv silently starts depending on a vendor
- * default and on whatever the operator's config happens to say. That is exactly the drift step 9
- * clause 2 forbids — "carry the chosen width as an explicit argv token rather than relying on a
- * launcher's injected default" — and the reason the width is stated here even though the host
- * would have granted it anyway. The width itself (task-wide, not callback-only) is a GLG
- * operator decision of 2026-08-30, taken with the Copilot measurement in hand: a callback-only
- * sibling names itself and then stops at the first tool its TASK needs. omp offers no argv
- * grammar for a narrower grant at all — `tools.approval.<tool>` is a config axis, not a flag —
- * so the honest choice was between `write` and `yolo`, and `yolo` matches what a human-typed
- * `omp` gets on this host. `--approval-mode` takes both the space and equals form (measured);
- * the space form is used for symmetry with `--model`.
- *
- * WHY OMP ALONE CARRIES NO PROMPT, AND WHY THAT IS A MEASUREMENT RATHER THAN A PREFERENCE.
- * `[LIVE 2026-08-30]` the first public fresh call at omp DID pass the full framing as a bare
- * positional. The window opened, the record minted (garden `20260830T181342-452167`), the
- * prompt arrived byte-identical as a user message at `09:13:42.413Z` — and the model answered
- * the literal text `ACK` with ZERO tool calls, because the callback tool did not exist yet.
- * `[source]` the interactive UI defers MCP discovery and only refreshes the tool list once
- * `discoverAndConnect()` settles (`sdk.ts:1847-1855`, `:1881-1905`), while the positional
- * `initialMessage` prompts immediately after `await mode.init()` (`main.ts:540-565`,
- * `595-610`). `[측정]` a `/tmp` observer on the same runtime: `turn_start` at +654ms with the
- * entwurf tools ABSENT, callback tool present only at +1484ms — the turn began ~830ms before
- * the tool it was told to call existed. No argv can close that gap, because the gap is a race
- * inside the host. So the composition hands omp a PAYLOAD instead of a turn, and the
- * in-process birth extension — which can see when the tool becomes callable — owns the first
- * two messages (`pi-extensions/meta-bridge-omp.ts`, "THE TWO-STAGE FRESH BOOTSTRAP").
- *
- * The flag is fixed and one-purpose ON PURPOSE. `[측정 2026-08-30]` a normal discovered
- * extension that registers a flag receives the operator's argv value byte-identical — quotes,
- * `$VAR`, backticks and a semicolon all survived a 137-byte JSON payload — because extensions
- * load before argv classification and the reparse writes the registered map
- * (`main.ts:1799-1810`, `cli/extension-flags.ts:36-43`). An env carrier or a temp file would
- * have needed its own quoting, its own lifetime and its own refusal rules; argv already owns
- * all three. This is deliberately NOT a general `--flag value` passthrough — an arbitrary
- * carrier would hand callers the launch-shaping power this rail exists to refuse.
- *
- * CODEX ALONE CARRIES A DIRECTORY IN ITS ARGV, AND OMITTING IT IS A WRONG ANSWER RATHER THAN A
- * NEUTRAL ONE. `[source rust-v0.153.4]` an explicit `--remote <endpoint>` — which this argv
- * always passes — resolves to `AppServerTarget::Remote` (`codex-rs/tui/src/lib.rs:875-876`;
- * `LocalDaemon` is only the IMPLICIT no-flag reuse path), and a Remote target takes its new
- * thread's directory from `remote_cwd_override` ALONE: `thread_cwd_from_config`
- * (`codex-rs/tui/src/app_server_session.rs:2022-2033`) answers `None` without it, and the
- * app-server then opens the thread in ITS OWN directory. That override is exactly `-C/--cd`,
- * retained only for a remote target (`codex-rs/tui/src/startup_orchestration.rs:191-194`), and
- * the flag lives on the shared interactive options this argv already uses for
- * `--dangerously-bypass-approvals-and-sandbox` (`codex-rs/utils/cli/src/shared_options.rs:53-68`)
- * — not only on the `agents` subcommand that also spells it (`codex-rs/cli/src/main.rs:334`).
- *
- * `[측정 2026-09-16]` with the flag absent, three citizens of one chain (pi → Codex → Claude
- * Code) all recorded the app-server's `~/repos/gh/entwurf` while the panes themselves sat in
- * `~/repos/gh/agent-config`, and the birth hook wrote that vendor-supplied cwd into each record
- * honestly (#95 lane C §1). So the token is ALWAYS present for codex: ONE directory, TWO
- * CARRIERS — tmux `-c` places the PANE, codex `-C` places the THREAD, and `launchCwd` is the
- * single value both receive. It is not a new input axis: the value is chosen by the cwd rules
- * this module already has, one layer up.
- */
-export function buildBackendArgs(backend, composition, model, env = process.env, 
-/** Where the sibling will actually start: the directory `freshCall` chose when it chose one,
- * and otherwise THIS process's own — which is what tmux gives a window opened with no `-c`
- * (`[측정 ×2]`, module header). The default is that inherited fact rather than a
- * convenience, so a caller that omits it still names the truth to codex. */
-launchCwd = process.cwd()) {
-    switch (backend) {
-        case "pi":
-            return [composition.prompt, "--entwurf-control", "--model", model];
-        case "claude-code":
-            return [composition.prompt, `--allowedTools=${FRESH_CALL_CALLBACK_TOOL["claude-code"]}`, `--model=${model}`];
-        case "copilot":
-            return ["copilot", "--interactive", composition.prompt, "--model", model, "--yolo"];
-        case "omp":
-            return [`--${OMP_BOOTSTRAP_FLAG}`, composition.bootstrapPayload, "--model", model, "--approval-mode", "yolo"];
-        case "codex":
-            return [
-                "--remote",
-                `unix://${resolveCodexDefaultSocketPath(env)}`,
-                "-C",
-                launchCwd,
-                "--model",
-                model,
-                "--dangerously-bypass-approvals-and-sandbox",
-                composition.prompt,
-            ];
-    }
-}
-/**
- * The omp bootstrap flag, spelled WITHOUT dashes — the vendor's flag map is keyed by bare
- * name (`extensions/loader.ts:221-228`) and this composition adds the `--` itself.
- *
- * Held equal to the installed extension's own constant by
- * `test/omp-fresh-bootstrap.contract.test.ts`. The two copies exist because the extension
- * ships INSIDE the omp agent dir carrying only its own small closure and cannot import this
- * module; the gate is what keeps the duplication from becoming drift.
- */
-export const OMP_BOOTSTRAP_FLAG = "entwurf-bootstrap";
-/** Payload grammar version, matched exactly by the decoder. A bump means a stale installed
- * unit, which is the one thing `doctor-omp-bridge` exists to say out loud. */
-export const OMP_BOOTSTRAP_VERSION = 1;
-/**
- * The whole of what a fresh omp sibling is launched with.
- *
- * THREE FIELDS, CLOSED. The decoder refuses an unknown key, so this object is the entire
- * contract: who to call back, the nonce that proves it is this call, and the task that is
- * released only after that callback succeeds. There is no command here, no path, no env name
- * and no model — the model is already an explicit argv token, and a second copy of it inside
- * a payload would be a second place for it to disagree with the launch.
- */
-export function buildOmpBootstrapPayload(params) {
-    return JSON.stringify({
-        v: OMP_BOOTSTRAP_VERSION,
-        target: params.callerGardenId,
-        nonce: params.nonce,
-        task: params.task,
-    });
-}
-/**
- * The first-turn framing. Order is the contract: the callback is the FIRST action and the task
- * follows it, so a sibling that gets stuck in the task has already told the caller who it is.
- *
- * The three prohibitions are not politeness. Each names a detour that was measured to produce a
- * confidently wrong answer or a wasted turn.
- */
-export function buildFreshCallPrompt(params) {
-    const tool = FRESH_CALL_CALLBACK_TOOL[params.backend];
-    return [
-        "You are a fresh visible citizen that entwurf opened in the operator's tmux session.",
-        "",
-        `FIRST ACTION, before reading files or anything else: call ${tool} with ` +
-            `target=${params.callerGardenId}, intent=fire-and-forget, wants_reply=false, and ` +
-            `message set to exactly ${params.nonce} — that string alone, nothing added.`,
-        "That call is how the agent that opened you learns your address. Do not skip it, do not",
-        "defer it until the task is done, and do not reword the message.",
-        "",
-        "Do not inspect environment variables, do not call entwurf_self, and do not start an MCP",
-        "server yourself. Your own report of your identity is not the address anyone needs.",
-        "",
-        "After the tool receipt, carry out this task:",
-        "",
-        params.task,
-    ].join("\n");
-}
 /**
  * WHICH RULE PICKS THE TARGET SESSION. Three in strict order, and the order is the contract:
  *
@@ -390,14 +180,6 @@ export function selectFreshCallSeat(placement) {
         return { tmuxSession: placement.tmuxSession, source: "requested" };
     return null;
 }
-/** Correlation tag only. Random, never derived from time, cwd or a peer listing — a nonce that
- * encoded any of those would invite exactly the guessing this rail exists to refuse. */
-export function mintNonce(randomHex = defaultRandomHex) {
-    return `mux-fresh-call-${randomHex()}`;
-}
-function defaultRandomHex() {
-    return randomBytes(12).toString("hex");
-}
 /**
  * The pi identity carrier, scrubbed at the launch seam for EVERY backend (#87 Bundle C).
  *
@@ -481,28 +263,19 @@ export function buildFreshCallArgs(targetSessionId, runtimePath, backendArgs, cw
  * from a seat, a workspace map or a project name.
  */
 export function freshCall(params, env = process.env, nonce = mintNonce()) {
-    if (typeof params.callerGardenId !== "string" || params.callerGardenId.length === 0) {
-        return { ok: false, reason: "caller-identity-unavailable" };
-    }
-    const model = params.model.trim();
-    if (model.length === 0)
-        return { ok: false, reason: "model-empty" };
-    if (!isSafeFreshCallModel(model))
-        return { ok: false, reason: "model-invalid" };
-    const task = params.task.trim();
-    if (task.length === 0)
-        return { ok: false, reason: "task-empty" };
-    if (task.length > TASK_MAX_CHARS)
-        return { ok: false, reason: "task-too-long" };
-    // ONLY `undefined` and the exact empty string mean "no cwd". Everything else is the literal
-    // value — deliberately untrimmed, so a whitespace-mangled path is refused loudly by the
-    // classification below instead of being silently repaired into a different directory. The
-    // caller's own record directory answers the SAME two-value emptiness rule and is consulted
-    // ONLY second: an explicit request always wins, and a caller that supplies neither leaves the
-    // pane to inherit this process's directory exactly as before — a pi caller's argv is
-    // byte-identical, because its process directory IS its own and a `-c` token would change
-    // nothing about where that window lands.
-    const requestedCwd = params.cwd === undefined || params.cwd === "" ? undefined : params.cwd;
+    // The caller-facing input contract lives in the composition leaf so BOTH rails answer a
+    // mistyped model or an oversized task with the same words. Order, trimming and the
+    // cwd-omission rule (`undefined` and the exact empty string, and nothing else, mean "no
+    // cwd") are unchanged from when they lived here.
+    const normalized = normalizeFreshCallInputs(params);
+    if (!normalized.ok)
+        return { ok: false, reason: normalized.reason };
+    const { callerGardenId, model, task, cwd: requestedCwd } = normalized.inputs;
+    // The caller's own record directory answers the SAME two-value emptiness rule the leaf
+    // applies to a requested cwd, and is consulted ONLY second: an explicit request always wins,
+    // and a caller that supplies neither leaves the pane to inherit this process's directory
+    // exactly as before — a pi caller's argv is byte-identical, because its process directory IS
+    // its own and a `-c` token would change nothing about where that window lands.
     const callerCwd = params.callerCwd === undefined || params.callerCwd === "" ? undefined : params.callerCwd;
     const chosenCwd = requestedCwd !== undefined
         ? { value: requestedCwd, source: "requested" }
@@ -596,10 +369,10 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
         prompt: buildFreshCallPrompt({
             backend: params.backend,
             task,
-            callerGardenId: params.callerGardenId,
+            callerGardenId,
             nonce,
         }),
-        bootstrapPayload: buildOmpBootstrapPayload({ callerGardenId: params.callerGardenId, nonce, task }),
+        bootstrapPayload: buildOmpBootstrapPayload({ callerGardenId, nonce, task }),
     };
     const backendArgs = buildBackendArgs(params.backend, composition, model, env, cwd);
     // THE LAUNCH-DIRECTORY NOTE, AND IT IS A DIAGNOSTIC RATHER THAN A GATE. `[측정 2026-09-16]` a