@junghanacs/entwurf 0.23.1 → 0.25.0

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

@@ -85,11 +85,12 @@
  *     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 { callbackEnvAssignments } from "./callback-env.js";
 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 { buildOmpBootstrapPayload, composeBackendArgs, composeFreshCallPrompt, FRESH_CALL_BACKENDS, FRESH_CALL_CALLBACK_TOOL, FRESH_CALL_DELIVERY_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";
@@ -106,7 +107,7 @@ import { classifyTmuxSessionName, resolveTmuxSessionId } from "./resolve-tmux-se
  * 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, };
+export { buildOmpBootstrapPayload, FRESH_CALL_BACKENDS, FRESH_CALL_CALLBACK_TOOL, FRESH_CALL_DELIVERY_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.";
@@ -200,9 +201,11 @@ export function selectFreshCallSeat(placement) {
  * scrub only on the backend whose measurement surfaced it would encode the claim that the other
  * four are immune, which is false. It costs the legitimate case nothing: a carrier is only ever
  * authoritative when the process that owns it exported it ITSELF, and a fresh `pi` sibling does
- * exactly that after this argv has run. This is a fixed two-variable seam and deliberately NOT a
- * general env carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping
- * power this rail exists to refuse.
+ * exactly that after this argv has run. This is a fixed seam and deliberately NOT a general env
+ * carrier — an arbitrary `-e` passthrough would hand callers the environment-shaping power this
+ * rail exists to refuse. Two more `-e` assignments ride beside the scrub: the callback pair
+ * (`callback-env.ts`), launcher-computed, so the sibling's first action does not retype an
+ * address out of prose.
  */
 const SCRUBBED_INHERITED_ENV = ["PI_SESSION_ID=", "PI_AGENT_ID="];
 /** Launch argv: the leaf's detached-append shape, the identity scrub, optionally `-c` at the
@@ -215,7 +218,7 @@ const SCRUBBED_INHERITED_ENV = ["PI_SESSION_ID=", "PI_AGENT_ID="];
  * name never reaches this function — the seat is resolved to a native `$id` before it is
  * called, and `assertSelector` refuses anything that is not one. `-d` is not optional: without
  * it a window opened into another session steals that session's focus (measured). */
-export function buildFreshCallArgs(targetSessionId, runtimePath, backendArgs, cwd) {
+export function buildFreshCallArgs(targetSessionId, runtimePath, backendArgs, cwd, callback) {
     assertSelector("session", targetSessionId);
     assertLaunchTarget(runtimePath);
     if (cwd !== undefined) {
@@ -228,6 +231,7 @@ export function buildFreshCallArgs(targetSessionId, runtimePath, backendArgs, cw
         "-d",
         "-a",
         ...SCRUBBED_INHERITED_ENV.flatMap((assignment) => ["-e", assignment]),
+        ...callbackEnvAssignments(callback).flatMap((assignment) => ["-e", assignment]),
         "-t",
         `${targetSessionId}:{end}`,
         ...(cwd === undefined ? [] : ["-c", cwd]),
@@ -403,7 +407,10 @@ export function freshCall(params, env = process.env, nonce = mintNonce()) {
             console.error(`[fresh-call] ${unanswered}: ${launchCwd}\n` + `            ${CODEX_LAUNCH_CWD_PREFLIGHT_HINT[unanswered]}`);
         }
     }
-    const run = runTmux(buildFreshCallArgs(targetSessionId, runtimePath, backendArgs, cwd), env);
+    const run = runTmux(buildFreshCallArgs(targetSessionId, runtimePath, backendArgs, cwd, {
+        target: callerGardenId,
+        nonce,
+    }), env);
     assertTmuxOk("new-window", run);
     let fields;
     try {
@@ -503,9 +510,11 @@ export function renderFreshCall(result) {
             `\n` +
             `This is a LAUNCH receipt: tmux created that window and was asked to start the runtime with the model above. It does ` +
             `NOT mean the sibling is running, that its first turn ran, or that the task was delivered.\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 window is visible and can be read directly.`,
+            `The sibling's garden id arrives separately — its first action is the zero-argument callback verb ` +
+            `(codex is the one arm that still sends the nonce as arguments), and the sender envelope of THAT ` +
+            `message is the address. The nonce above is the correlation tag it carries; the sibling reads it ` +
+            `from its own launch env, never from this receipt. Nothing is polling for it; if it never comes, ` +
+            `the window is visible and can be read directly.`,
         isError: false,
     };
 }

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

@@ -77,7 +77,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { isPlausibleOwnerPid, ompMetaRootBase, ompMetaRoots, requireGardenId, upsertMetaSession, writeMetaSenderMarker, } from "./lib/meta-session.js";
+import { isPlausibleOwnerPid, ompMetaRootBase, ompMetaRoots, upsertMetaSession, writeMetaSenderMarker, } from "./lib/meta-session.js";
 /**
  * The §3.5 host discriminator. THE one new predicate this whole lane is allowed to
  * introduce, and it is the vendor's own top-level mode — not a heuristic over cwd,
@@ -147,7 +147,7 @@ export const OMP_BOOTSTRAP_FLAG = "entwurf-bootstrap";
 /** Payload grammar version. A payload that does not say exactly this is refused rather than
  * best-guessed: the launcher and this unit ship in the same package, so a mismatch means a
  * STALE installed unit — the one condition `doctor-omp-bridge` exists to name out loud. */
-export const OMP_BOOTSTRAP_VERSION = 1;
+export const OMP_BOOTSTRAP_VERSION = 2;
 /**
  * The model-facing callback tool, spelled for omp. `[측정]` the vendor's minter sanitises to
  * `[a-z_]` and EATS the digit in `entwurf_v2` (`mcp/tool-bridge.ts:384-396`;
@@ -161,7 +161,7 @@ export const OMP_BOOTSTRAP_VERSION = 1;
  * spellings are held equal by `test/omp-fresh-bootstrap.contract.test.ts`, the same shape
  * `check-omp-fresh-preflight` already uses for the preflight's reproduced oracles.
  */
-export const OMP_BOOTSTRAP_CALLBACK_TOOL = "mcp__entwurf_bridge_entwurf_v";
+export const OMP_BOOTSTRAP_CALLBACK_TOOL = "mcp__entwurf_bridge_entwurf_callback";
 /** Task ceiling, held equal to the launcher's `TASK_MAX_CHARS` by the same contract test. */
 export const OMP_BOOTSTRAP_TASK_MAX_CHARS = 16000;
 /** How long readiness may take before this bootstrap FAILS and the task is never sent.
@@ -175,12 +175,10 @@ export const OMP_BOOTSTRAP_READY_TIMEOUT_MS = 60_000;
  * MCP ones (`runner.ts:907-978`). Polling the two public snapshots is the smallest honest
  * primitive; a FIXED DELAY is forbidden because the gap is a race, not a constant. */
 export const OMP_BOOTSTRAP_POLL_MS = 100;
-/** The nonce the launcher mints (`mintNonce`: `mux-fresh-call-` + 12 random bytes as hex). */
-const BOOTSTRAP_NONCE_RE = /^mux-fresh-call-[0-9a-f]{24}$/;
 /** The wire keys, closed. An unknown key is a REFUSAL rather than an ignored extra: this
  * flag is the one thing a caller can put arbitrary bytes into, so the decoder's job is to
  * make "what the launcher meant" and "what this unit will act on" the same set. */
-const BOOTSTRAP_KEYS = new Set(["v", "target", "nonce", "task"]);
+const BOOTSTRAP_KEYS = new Set(["v", "task"]);
 /**
  * Read the flag value into a payload, or name why not.
  *
@@ -212,22 +210,12 @@ export function decodeOmpBootstrapPayload(raw) {
         if (!BOOTSTRAP_KEYS.has(key))
             return { ok: false, reason: "payload-unknown-key" };
     }
-    let target;
-    try {
-        target = requireGardenId(obj.target);
-    }
-    catch {
-        return { ok: false, reason: "target-invalid" };
-    }
-    const nonce = obj.nonce;
-    if (typeof nonce !== "string" || !BOOTSTRAP_NONCE_RE.test(nonce))
-        return { ok: false, reason: "nonce-invalid" };
     const task = obj.task;
     if (typeof task !== "string" || task.trim().length === 0)
         return { ok: false, reason: "task-empty" };
     if (task.length > OMP_BOOTSTRAP_TASK_MAX_CHARS)
         return { ok: false, reason: "task-too-long" };
-    return { ok: true, value: { target, nonce, task } };
+    return { ok: true, value: { task } };
 }
 /**
  * Stage one's whole message: call back, and nothing else.
@@ -238,18 +226,13 @@ export function decodeOmpBootstrapPayload(raw) {
  * no competing goal at all. Stage two exists so this message never has to compete with the
  * work; adding "then do X" back into it would rebuild exactly the prompt that failed.
  */
-export function buildOmpCallbackOnlyPrompt(params) {
+export function buildOmpCallbackOnlyPrompt() {
     return [
         "You are a fresh visible citizen that entwurf opened in the operator's tmux session.",
         "",
-        `FIRST AND ONLY ACTION RIGHT NOW: call ${OMP_BOOTSTRAP_CALLBACK_TOOL} with ` +
-            `target=${params.target}, intent=fire-and-forget, wants_reply=false, and ` +
-            `message set to exactly ${params.nonce} — that string alone, nothing added.`,
+        `FIRST AND ONLY ACTION RIGHT NOW: call ${OMP_BOOTSTRAP_CALLBACK_TOOL} with no arguments.`,
         "That call is how the agent that opened you learns your address. Make the call before",
-        "reading files, before planning, and before answering in prose. 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.",
+        "reading files, before planning, and before answering in prose. There are no parameters.",
         "",
         "Your actual task arrives as the NEXT user message, immediately after that call succeeds.",
         "Do not ask for it and do not guess at it.",
@@ -521,22 +504,32 @@ export function ompCallbackToolReady(pi) {
     return registered && active.includes(OMP_BOOTSTRAP_CALLBACK_TOOL);
 }
 /**
- * Does this tool event name OUR callback, with OUR target and OUR nonce?
+ * Does this tool event name OUR callback?
  *
  * The event carries no server name, no session id and no original MCP tool name
- * (`extensions/types.ts:916-1017`), so the match is built from what IS there: the canonical
- * minted tool name plus the two argument values this rail already owns as contract. Exact
- * string equality on both — a prefix or `includes` here would let a sibling's nonce release
- * this session's task.
+ * (`extensions/types.ts:916-1017`), so the match is built from what IS there: exact string
+ * equality on the canonical minted tool name — a prefix or `includes` here would let a
+ * neighbouring tool release this session's task.
+ *
+ * The target/nonce half of this predicate is GONE, and that is the point of the out-of-band
+ * callback: the address rides the sibling's process env, so the verb takes no arguments and
+ * there are no argument values left to compare. What replaces the comparison is the ABSENCE
+ * of arguments — a call carrying a target or a message is a model supplying an address, which
+ * is the second address axis Hard Rule 2 refuses, and it must not release the task. Correlation
+ * to THIS bootstrap is not weakened by the removal: it is carried by the stored `toolCallId`
+ * (one session, one live tool call) plus the fact that only this session's env named the caller.
  */
-function matchesCallback(event, payload) {
+function matchesCallback(event, _payload) {
     if (event?.toolName !== OMP_BOOTSTRAP_CALLBACK_TOOL)
         return false;
     const input = event?.input;
-    if (typeof input !== "object" || input === null || Array.isArray(input))
+    if (input === undefined || input === null)
+        return true;
+    if (typeof input !== "object" || Array.isArray(input))
         return false;
     const args = input;
-    return args.target === payload.target && args.message === payload.nonce;
+    // No-arg verb: a supplied target/message is a second address axis — not our callback.
+    return args.target === undefined && args.message === undefined;
 }
 /**
  * Create one bootstrap for one minted session.
@@ -580,7 +573,7 @@ export function createOmpBootstrap(opts) {
         if (isFinal())
             return;
         phase = "failed";
-        log("WARN", `bootstrap-failed nonce=${payload.nonce}: ${why}; the task was NOT sent`);
+        log("WARN", `bootstrap-failed: ${why}; the task was NOT sent`);
     }
     /**
      * Both stages send the SAME way: `pi.sendUserMessage(content)` with NO delivery option.
@@ -616,8 +609,8 @@ export function createOmpBootstrap(opts) {
             // two callback prompts for one bootstrap.
             phase = "callback-sent";
             stopTimer();
-            log("INFO", `bootstrap-ready nonce=${payload.nonce}: callback tool live, sending callback-only prompt`);
-            send(buildOmpCallbackOnlyPrompt({ target: payload.target, nonce: payload.nonce }));
+            log("INFO", "bootstrap-ready: callback tool live, sending callback-only prompt");
+            send(buildOmpCallbackOnlyPrompt());
             return;
         }
         if (timers.now() >= deadline) {
@@ -654,7 +647,7 @@ export function createOmpBootstrap(opts) {
             if (typeof id !== "string" || id.length === 0)
                 return;
             callId = id;
-            log("INFO", `bootstrap-callback-observed nonce=${payload.nonce} toolCallId=${id}`);
+            log("INFO", `bootstrap-callback-observed toolCallId=${id}`);
         },
         onToolResult(event) {
             if (phase !== "callback-sent" || callId === null)
@@ -664,7 +657,7 @@ export function createOmpBootstrap(opts) {
             if (!matchesCallback(event, payload))
                 return;
             if (event?.isError !== false) {
-                log("WARN", `bootstrap-callback-errored nonce=${payload.nonce} toolCallId=${callId}; the task was NOT sent`);
+                log("WARN", `bootstrap-callback-errored toolCallId=${callId}; the task was NOT sent`);
                 return;
             }
             // RELEASED, AND THE TASK IS NOT SENT HERE. This handler runs inside the callback
@@ -673,7 +666,7 @@ export function createOmpBootstrap(opts) {
             // record that the callback provably succeeded; `onTurnEnd` owns the send.
             phase = "released";
             stopTimer();
-            log("INFO", `bootstrap-released nonce=${payload.nonce} toolCallId=${callId}: task armed for the next turn_end`);
+            log("INFO", `bootstrap-released toolCallId=${callId}: task armed for the next turn_end`);
         },
         /**
          * The stage-two boundary: the callback turn is over, so the session is at the edge
@@ -695,7 +688,7 @@ export function createOmpBootstrap(opts) {
             if (phase !== "released")
                 return;
             phase = "task-sent";
-            log("INFO", `bootstrap-task-sent nonce=${payload.nonce}: delivering the task at the turn_end boundary`);
+            log("INFO", "bootstrap-task-sent: delivering the task at the turn_end boundary");
             send(payload.task);
         },
         invalidate(why) {
@@ -706,7 +699,7 @@ export function createOmpBootstrap(opts) {
             if (isFinal())
                 return;
             phase = "failed";
-            log("INFO", `bootstrap-invalidated nonce=${payload.nonce}: ${why}; the task was NOT sent`);
+            log("INFO", `bootstrap-invalidated: ${why}; the task was NOT sent`);
         },
     };
 }
@@ -869,7 +862,7 @@ export function startOmpBootstrap(opts) {
     const handle = createOmpBootstrap({ payload: decoded.value, pi, timers, log });
     activeBootstrap = { sessionId: envelope.nativeSessionId, handle };
     bootstrapConsumed = true;
-    log("INFO", `bootstrap-armed nonce=${decoded.value.nonce} target=${decoded.value.target}`);
+    log("INFO", "bootstrap-armed: payload admitted, waiting for callback tool");
     handle.start();
 }
 /**

package/mcp/entwurf-bridge/dist/protocol.js

@@ -20,10 +20,3 @@
  * AGENTS.md section from its own pi-context augment.
  */
 export const ENTWURF_PROJECT_CONTEXT_OPEN_TAG = "<project-context";
-/**
- * Sender-side UI echo custom message type for successful entwurf_v2 send calls.
- * The bridge emits it, the control renderer draws it, and the provider-level
- * context filter removes it before LLM conversion. Keep as one SSOT: a typo
- * here otherwise becomes a silent UI/context split.
- */
-export const ENTWURF_SENT_MESSAGE_TYPE = "entwurf-sent";

package/mcp/entwurf-bridge/dist/scripts/doctor-pi-provider.js

@@ -143,11 +143,24 @@ log(`  project      ${projectPath}: ${projScopeDesc}`);
 log(`  EFFECTIVE (${effectiveScope}): ${effectiveDesc}`);
 // install-state ownership (user scope). absent state on a configured effective is either a
 // pre-Task-2 install or a user-override we deliberately did not own.
+//
+// `command` is read beside it because it — not the bare name — is the CANONICAL managed command
+// (#116 M3-b2). `register-pi-provider.py` writes the same string into the settings entry and into
+// this record (:332-342, :368-369), and in plugin mode that string is an absolute bridge under the
+// certified stable runtime, because a Herdr-plugin host has nothing entwurf on PATH. Reading it
+// here is what lets this doctor judge drift without re-deriving the stable runtime root: the root
+// is the writer's business, and a second derivation in this file would be a second address axis.
+//
+// `ownership` is the PREIMAGE classification — what stood at the key BEFORE that install — so
+// `absent` means "we created it", not "nobody owns it". Treating it as an ownership verdict is what
+// made every plugin-mode host red while its bridge booted and served all eight verbs.
 let ownership;
+let stateCommand;
 if (existsSync(statePath)) {
     try {
         const st = JSON.parse(readFileSync(statePath, "utf8"));
         ownership = typeof st.ownership === "string" ? st.ownership : undefined;
+        stateCommand = typeof st.command === "string" ? st.command : undefined;
         log(`  state: install-state present (ownership=${ownership}).`);
     }
     catch {
@@ -200,9 +213,33 @@ else {
             hardFail = 1;
         }
     }
-    if (!isBare) {
-        // Ownership classification never rounds a broken runtime up to green. It only says who may
-        // repair the non-canonical entry after the independent boot verdict above.
+    // Ownership classification never rounds a broken runtime up to green. It only says who may
+    // repair the entry after the independent boot verdict above.
+    //
+    // A MANAGED record is the pair (known preimage ownership, recorded command). For that pair the
+    // recorded command is canonical and the comparison runs REGARDLESS of whether the effective
+    // command happens to be the bare name. Keeping this decision inside a `!isBare` branch is how
+    // real drift escaped: a record naming the absolute plugin bridge, with the settings repointed to
+    // the bare `entwurf-bridge`, is drift — and a bare bridge that boots would otherwise carry it to
+    // green. "The effective command is spellable as our old default" is not evidence that it is the
+    // command this install wrote.
+    //
+    // Everything else — a record that names no command, or one whose ownership is a word this
+    // doctor does not know — falls through to the ORIGINAL logic below, unchanged. Repairing this
+    // defect is not a licence to migrate the state schema, to grant an amnesty to records written
+    // before `command` existed, or to let an unknown ownership word buy a managed green because a
+    // string happened to match. The state is rewritten by `./run.sh setup`, not by its reader.
+    const knownManagedOwnership = ownership === "absent" || ownership === "managed-current" || ownership === "managed-legacy";
+    if (knownManagedOwnership && stateCommand !== undefined) {
+        if (cmd !== stateCommand) {
+            log(`  FAIL: state records '${stateCommand}' as the managed command (ownership=${ownership}), but the effective command is '${cmd}' — the key drifted to something entwurf never wrote.`);
+            hardFail = 1;
+        }
+        else {
+            log(`  ok: effective command is the managed command this install recorded ('${stateCommand}', preimage ownership=${ownership}).`);
+        }
+    }
+    else if (!isBare) {
         if (ownership && ownership !== "user-override") {
             log(`  FAIL: state owns entwurf-bridge (ownership=${ownership}) but the effective command drifted to '${cmd}'.`);
             hardFail = 1;

package/mcp/entwurf-bridge/dist/scripts/herdr-rails.mjs

@@ -0,0 +1,72 @@
+/**
+ * herdr-rails — the ONE place the herdr rail's backend set and its per-backend model SYNTAX
+ * example are written down (#116 A7).
+ *
+ * WHY THIS FILE EXISTS. Three surfaces were about to say the same two things in three
+ * dialects: `herdr-fresh-call.ts` owned the closed backend tuple, `build.mjs` narrated one
+ * model id per harness at install time, and the status pane was about to print a RAILS block.
+ * Three copies of one fact is how a rail quietly grows a fourth backend in prose that no
+ * dispatch honours. So the fact lives here and the three read it.
+ *
+ * WHY `.mjs` AND NOT `.ts`. It is read by two runtimes that cannot agree on anything else:
+ * the Herdr plugin runs `node lib/status.mjs` with no loader flags at all, and the pi
+ * extension is typechecked by `tsc`. A `.ts` leaf would be unloadable by the first; a second
+ * copy would defeat the point. `protocol.js` set this precedent for exactly the same reason
+ * (root tsconfig.json `allowJs`), and this file keeps its shape: dependency-free, no imports,
+ * no environment, no IO, so importing it can never be a side effect.
+ *
+ * WHAT THIS FILE IS NOT, and each absence is load-bearing:
+ *   - NOT a model catalogue. One example per backend, chosen to show the SHAPE of the string
+ *     (`provider/model` vs a bare vendor id). Adding a second example starts a list, a list
+ *     invites completeness, and completeness is a catalogue Entwurf would then be expected to
+ *     keep current for every vendor. `entwurf_fresh_call` takes a model string with no default
+ *     and validates nothing; that is the contract, and an example must not imply otherwise.
+ *   - NOT a supported-model set, a recommendation, or a validator. Nothing reads MODEL_SYNTAX_EXAMPLE
+ *     to decide anything — it is display text on three surfaces.
+ *   - NOT a provider, billing or quota statement. No rail here names a provider, a subscription
+ *     or a cost. `#76` is about which rail a sibling may be launched on, and a syntax example
+ *     that mentioned a provider would read as an answer to it. It does not answer it.
+ *   - NOT a launcher, and not a claim that any binary exists. `HERDR_AGENT_KIND` (the herdr
+ *     `--kind` token) stays with the rail that spends it; this leaf carries no argv.
+ */
+/**
+ * The closed pilot set for the herdr launch rail. Herdr's own `--kind` enum is much larger and
+ * that is not evidence of support: every other backend is a named pre-mutation reject.
+ *
+ * The JSDoc cast is what keeps the TYPE half of this single source honest. Without it TypeScript
+ * infers `readonly string[]` from a `.mjs` file and `HerdrFreshCallBackend` silently widens to
+ * `string` — the tuple would still be one source at runtime while the compiler had stopped
+ * checking anything. A gate pins both halves.
+ *
+ * @type {readonly ["pi", "claude-code"]}
+ */
+export const HERDR_FRESH_CALL_BACKENDS = Object.freeze(["pi", "claude-code"]);
+/**
+ * ONE model string per backend, and it is an example of SYNTAX, never of choice.
+ *
+ * `[관측: GLG, 날것 PC, 2026-09-17]` "일단 정확한 모델명을 모른다" — after a green install the first
+ * thing missing is a call that works, and the two runtimes spell a model differently enough that
+ * guessing fails: pi wants a provider-qualified path, Claude Code wants the vendor id alone.
+ * That difference is the whole content of this map.
+ *
+ * @type {Readonly<Record<"pi" | "claude-code", string>>}
+ */
+export const MODEL_SYNTAX_EXAMPLE = Object.freeze({
+    pi: "openai-codex/gpt-5.6-terra",
+    "claude-code": "claude-sonnet-5",
+});
+/**
+ * How a citizen on each backend is REACHED once it exists, in the operator's words. This is the
+ * rail fact the status pane's RAILS block renders and the install narration states — the same
+ * sentence, so a host cannot be told two different things about one backend.
+ *
+ * `[관측: GLG, 날것 PC, 2026-09-17]` from the operator's chair a plain `pi` looks identical to a
+ * citizen pi: the install says green, `pi` starts, and nothing is there. Citizenship is argv-gated
+ * on purpose, and that gate is invisible unless something says it out loud.
+ *
+ * @type {Readonly<Record<"pi" | "claude-code", string>>}
+ */
+export const RAIL_ENTRY_NOTE = Object.freeze({
+    pi: "start it as `pi --entwurf-control` to be a garden citizen — a plain `pi` loads the extension but has no garden id, no control socket and no entwurf tools",
+    "claude-code": "nothing to add — an ordinary `claude` picks up the entwurf tools through MCP",
+});

package/mcp/entwurf-bridge/dist/scripts/probe-bridge-command.js

@@ -42,6 +42,7 @@ export const EXPECTED_TOOLS = [
     "entwurf_register_native",
     "entwurf_fresh_call",
     "entwurf_resume_call",
+    "entwurf_callback",
 ];
 const DEFAULT_TIMEOUT_MS = 10_000;
 /** How long a probed child gets to die politely before it is killed outright. */

package/mcp/entwurf-bridge/src/index.ts

@@ -34,8 +34,13 @@
  *   - entwurf_resume_call — reopen ONE DORMANT pi citizen under its OWN garden id in a visible
  *                       window; target-only, runs no turn, LAUNCH and OBSERVATION receipts stay
  *                       apart.
+ *   - entwurf_callback — ZERO-ARGUMENT fresh-sibling callback. Reads ENTWURF_CALLBACK_TARGET +
+ *                       ENTWURF_CALLBACK_NONCE from this process env (launcher-injected), validates
+ *                       grammar, and dispatches through the existing v2 runner. Refuses by name
+ *                       when env is absent/malformed or this process is a Codex-provenance bridge.
+ *                       No model-supplied target fallback.
  *
- * That list is the WHOLE public surface — seven verbs — and `check-entwurf-bridge-boot`
+ * That list is the WHOLE public surface — eight verbs — and `check-entwurf-bridge-boot`
  * (G1f) holds it as an exact set on the runtime tools/list, so a verb added or dropped
  * here without a decision is red rather than merely undocumented.
  *
@@ -65,6 +70,7 @@ import * as process from "node:process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { readCallbackEnv } from "../../../pi-extensions/lib/callback-env.ts";
 import { controlSocketPathIn, defaultControlSocketDir } from "../../../pi-extensions/lib/control-socket-path.js";
 import { resolveMailboxReceiverFacts } from "../../../pi-extensions/lib/entwurf-deliverability.ts";
 import { listEntwurfFacts } from "../../../pi-extensions/lib/entwurf-fact-provider.ts";
@@ -425,7 +431,9 @@ server.tool(
 		"alone does not say which rail that citizen answers on. Give target + intent; the decider picks transport " +
 		"from liveness (live socket citizen → control-socket send; deliverable self-fetch citizen → meta-bridge " +
 		"mailbox; probe-alive native-push citizen → direct injection into its conversation) and reports ONE " +
-		"outcome (delivered / rejected / delivered-but-lock-dirty). EXISTING targets only; discover with " +
+		"outcome, named per rail: a control receiver's acceptance boundary (`sent` / `queued-steer` / " +
+		"`queued-follow-up` / `accepted-unknown-boundary` — those four only), a mailbox ENQUEUE receipt, a " +
+		"native-push INJECTION, a rejection, or lock-dirty. EXISTING targets only; discover with " +
 		"entwurf_peers. A peer entwurf_peers shows as liveness=alive → fire-and-forget. A " +
 		"citizen with NO socket liveness (liveness=unsupported) is ALSO fire-and-forget — unsupported means only " +
 		'"no control-socket probe." The decider resolves the actual rail at dispatch time: a self-fetch ' +
@@ -466,9 +474,8 @@ server.tool(
 			.enum(["steer", "follow_up"])
 			.optional()
 			.describe(
-				"Injection style for a CONTROL-SOCKET send only: steer (interrupt the current turn) or " +
-					"follow_up (queue after it). The mailbox and native-push plans carry no mode, so it has no " +
-					"effect on those rails.",
+				"Injection style for a CONTROL-SOCKET send only: steer (ask the receiver's steering queue) or follow_up (ask its follow-up queue). NEITHER is an interrupt: a busy receiver drains steering after each turn and follow-ups only when its inner loop ends, so a later steer overtakes every earlier follow_up and there is no order between the two. Both queues are volatile process memory — an abort drops what is in them. The receipt names which queue accepted the message (`queued-steer` / `queued-follow-up`); an idle receiver answers `sent`, meaning the turn was TRIGGERED, not that the model has seen the text. " +
+					"The mailbox and native-push plans carry no mode, so it has no effect on those rails.",
 			),
 		wants_reply: z.boolean().optional().describe("Human-conversation reply hint (default false)"),
 	},
@@ -877,6 +884,40 @@ server.tool(
 	},
 );
 
+server.tool(
+	"entwurf_callback",
+	"ZERO-ARGUMENT callback for a fresh sibling this process was launched as. Reads " +
+		"ENTWURF_CALLBACK_TARGET and ENTWURF_CALLBACK_NONCE from this process environment " +
+		"(injected by the launcher next to the identity scrub), validates garden-id and nonce " +
+		"grammar, and dispatches through the existing v2 runner with intent fire-and-forget, " +
+		"message=nonce, wants_reply=false. The target is re-resolved by record/decider — env " +
+		"names the id, it does not skip dispatch. REFUSES BY NAME when the pair is absent, " +
+		"malformed, or this process is a Codex-provenance bridge (window env never reaches that " +
+		"MCP child). No arguments, no fallback to a model-supplied target.",
+	{},
+	async (_args, extra) => {
+		const read = readCallbackEnv(process.env);
+		if (!read.ok) {
+			return textErr(`entwurf_callback: ${read.reason}`);
+		}
+		try {
+			const sender = await buildSendSenderEnvelope({ requestMeta: extra._meta });
+			const rendered = await runAndRenderEntwurfV2FromSurface(
+				{
+					target: read.target,
+					intent: "fire-and-forget",
+					message: read.nonce,
+					wants_reply: false,
+				},
+				{ senderProvider: () => sender },
+			);
+			return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
+		} catch (err) {
+			return textErr(`entwurf_callback error: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	},
+);
+
 // ============================================================================
 // Main
 // ============================================================================

package/mcp/entwurf-bridge/test.sh

@@ -55,7 +55,7 @@ names=set(raw)
 # was an artifact-surface hole: a bundle missing entwurf_fresh_call / entwurf_resume_call
 # answered tools/list and passed. Equality also refuses an undecided extra verb; the
 # duplicate arm catches a name registered twice, which set membership cannot see.
-expected={'entwurf_v2','entwurf_self','entwurf_peers','entwurf_inbox_read','entwurf_register_native','entwurf_fresh_call','entwurf_resume_call'}
+expected={'entwurf_v2','entwurf_self','entwurf_peers','entwurf_inbox_read','entwurf_register_native','entwurf_fresh_call','entwurf_resume_call','entwurf_callback'}
 legacy={'entwurf','entwurf_resume','entwurf_send'} & names
 if len(raw)!=len(names):
     raise SystemExit(f"duplicate tool registrations: {sorted(raw)}")
@@ -66,7 +66,7 @@ if legacy:
 if names!=expected:
     raise SystemExit(f"tool set MISMATCH — missing {sorted(expected-names)}, unexpected {sorted(names-expected)}")
 PY
-ok "public tool surface is EXACTLY the seven garden verbs (no v1 verb, no undecided extra, no duplicate)"
+ok "public tool surface is EXACTLY the eight garden verbs (no v1 verb, no undecided extra, no duplicate)"
 
 SELF_JSON="$(printf '%s\n' "$OUT" | grep '"id":3' | tail -1)"
 [[ "$SELF_JSON" == *"isError"* ]] || fail "entwurf_self without identity should be an error: $SELF_JSON"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.23.1",
+	"version": "0.25.0",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for pi, Claude Code, Copilot CLI, OMP, Antigravity, and Codex CLI; Claude and Snowflake Cortex Code ACP backends.",
 	"license": "MIT",
 	"author": {
@@ -67,6 +67,7 @@
 		"pi/skill-plugin-example/",
 		"run.sh",
 		"AGENTS.md",
+		"FAQ.md",
 		"BASELINE.md",
 		"VERIFY.md",
 		"DELIVERY.md",
@@ -91,16 +92,17 @@
 		"zod": "^3.25.0 || ^4.0.0"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-ai": ">=0.85.1 <0.86",
-		"@earendil-works/pi-coding-agent": ">=0.85.1 <0.86",
-		"@earendil-works/pi-tui": ">=0.85.1 <0.86",
+		"@earendil-works/pi-ai": ">=0.87.1 <0.88",
+		"@earendil-works/pi-coding-agent": ">=0.87.1 <0.88",
+		"@earendil-works/pi-tui": ">=0.87.1 <0.88",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.13",
-		"@earendil-works/pi-ai": "0.85.1",
-		"@earendil-works/pi-coding-agent": "0.85.1",
-		"@earendil-works/pi-tui": "0.85.1",
+		"@earendil-works/pi-agent-core": "0.87.1",
+		"@earendil-works/pi-ai": "0.87.1",
+		"@earendil-works/pi-coding-agent": "0.87.1",
+		"@earendil-works/pi-tui": "0.87.1",
 		"@types/node": "^24.3.0",
 		"husky": "^9.1.7",
 		"rregex": "1.13.1",
@@ -174,8 +176,8 @@
 		"check:full": "bash scripts/check-elapsed.sh check:full check:core check:hermetic check:package",
 		"check:core": "pnpm run check:toolchain && pnpm run check:vitest && pnpm run check:contracts",
 		"check:toolchain": "pnpm lint && pnpm typecheck",
-		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-tests-beside-behavior",
-		"check:contracts": "./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push",
+		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-pi-queue-oracle && ./run.sh check-tests-beside-behavior",
+		"check:contracts": "./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-runner && ./run.sh check-control-send-receipt && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push",
 		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-meta-hook-session-switch && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-pi-launch && ./run.sh check-codex-app-server-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-birth-hook && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-peer-facts && ./run.sh check-herdr-plugin && ./run.sh check-herdr-plugin-profile && ./run.sh check-herdr-plugin-build && ./run.sh check-herdr-runtime-bootstrap && ./run.sh check-herdr-activation && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-usage-accounting && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-typing-call-fence && ./run.sh check-gate-manifests && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex && ./run.sh check-codex-bridge-identity && ./run.sh check-codex-birth-hook && ./run.sh smoke-codex-config-state && ./run.sh smoke-codex-birth && ./run.sh check-herdr-sandbox",
 		"check:package": "./run.sh check-install-surface && ./run.sh smoke-meta-install-state && ./run.sh smoke-agy-install-state && ./run.sh smoke-setup-verdict && ./run.sh check-pack-pin-matcher && ./run.sh check-package-source-routing && ./run.sh check-install-preflight && ./run.sh check-pack"
 	},