@junghanacs/entwurf 0.23.0 → 0.24.0

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

@@ -21,7 +21,7 @@
  * 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"
+ * pi 0.86.0 — 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`).
@@ -65,14 +65,23 @@ const OFFICIAL_REPORTS = {
     "herdr:pi": { agent: "pi", kind: "path", backend: "pi" },
 };
 /**
- * A pi session filename, measured 2026-09-14 on pi 0.85.1:
+ * A pi session filename, measured 2026-09-20 on pi 0.86.0:
  *
- *   2026-09-14T05-17-03-979Z_01a09e58-f06a-70e8-b14a-1f0f0c7f7c7d.jsonl
+ *   2026-09-20T00-35-44-197Z_01a0bc3d-87c4-738e-b391-265c8ba5a1b0.jsonl
  *   └────────── start stamp ─────────┘ └──────── nativeSessionId ────────┘
  *
+ * `[측정 2026-09-20]` that is a REAL file a sandboxed pi 0.86.0 wrote, and its own
+ * `{"type":"session"}` header carries `id: 01a0bc3d-87c4-738e-b391-265c8ba5a1b0` —
+ * the exact string `piNativeSessionIdFromPath` recovers from the name. The layout was
+ * re-measured rather than carried: pi 0.86.0 rewrote session-manager.ts (+269 −141
+ * over v0.85.1), but every line that BUILDS a name is byte-unchanged
+ * (`${fileTimestamp}_${this.sessionId}.jsonl`, session-manager.ts:991/1527/1703); the
+ * only diff in that file's `.jsonl` lines is a lambda parameter rename on the READER
+ * side. A source read alone would not have settled it, so the real file is the receipt.
+ *
  * 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
+ * pi changed it. **Vendor floor: pi 0.86.0, measured 2026-09-20** — 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

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/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";
@@ -877,6 +883,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.0",
+	"version": "0.24.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,13 +67,15 @@
 		"pi/skill-plugin-example/",
 		"run.sh",
 		"AGENTS.md",
+		"FAQ.md",
 		"BASELINE.md",
 		"VERIFY.md",
 		"DELIVERY.md",
 		"CONTRIBUTING.md",
 		"CHANGELOG.md",
 		"!**/__pycache__",
-		"!**/*.pyc"
+		"!**/*.pyc",
+		"!pi-extensions/**/*.test.ts"
 	],
 	"engines": {
 		"node": ">=24.0.0"
@@ -82,7 +84,7 @@
 		"claudeCodeFloor": ">=2.1.217"
 	},
 	"dependencies": {
-		"@agentclientprotocol/claude-agent-acp": "0.76.0",
+		"@agentclientprotocol/claude-agent-acp": "0.79.0",
 		"@agentclientprotocol/sdk": "1.4.0",
 		"@anthropic-ai/sdk": "0.100.1",
 		"@modelcontextprotocol/sdk": "^1.12.1",
@@ -90,16 +92,16 @@
 		"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.86.0 <0.87",
+		"@earendil-works/pi-coding-agent": ">=0.86.0 <0.87",
+		"@earendil-works/pi-tui": ">=0.86.0 <0.87",
 		"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-ai": "0.86.0",
+		"@earendil-works/pi-coding-agent": "0.86.0",
+		"@earendil-works/pi-tui": "0.86.0",
 		"@types/node": "^24.3.0",
 		"husky": "^9.1.7",
 		"rregex": "1.13.1",
@@ -127,7 +129,6 @@
 		"check-meta-capability-source": "./run.sh check-meta-capability-source",
 		"check-socket-probe": "./run.sh check-socket-probe",
 		"check-project-trust-handler": "./run.sh check-project-trust-handler",
-		"check-entwurf-v2-lock": "./run.sh check-entwurf-v2-lock",
 		"check-model-lock": "./run.sh check-model-lock",
 		"check-dep-versions": "./run.sh check-dep-versions",
 		"check-node-floor-coherence": "./run.sh check-node-floor-coherence",
@@ -135,6 +136,7 @@
 		"check-copilot-birth-hook": "./run.sh check-copilot-birth-hook",
 		"check-copilot-statusline": "./run.sh check-copilot-statusline",
 		"check-copilot-launch": "./run.sh check-copilot-launch",
+		"check-pi-launch": "./run.sh check-pi-launch",
 		"smoke-copilot-statusline-state": "./run.sh smoke-copilot-statusline-state",
 		"smoke-copilot-mcp-state": "./run.sh smoke-copilot-mcp-state",
 		"smoke-omp-bridge-state": "./run.sh smoke-omp-bridge-state",
@@ -173,9 +175,9 @@
 		"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",
-		"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-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-resume-args && ./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-entwurf-facts && ./run.sh check-control-socket-path && ./run.sh check-socket-discovery && ./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-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: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: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"
 	},
 	"pi": {

package/pi-extensions/entwurf-control.ts

@@ -81,6 +81,7 @@ import type {
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import { Box, type Component, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { ENTWURF_SENT_MESSAGE_TYPE } from "../protocol.js";
+import { readCallbackEnv } from "./lib/callback-env.js";
 import {
 	type CompactionGuard,
 	compactionSendReject,
@@ -1118,6 +1119,7 @@ export default function (pi: ExtensionAPI) {
 	if (shouldRegisterControlTools(pi)) {
 		registerListSessionsTool(pi);
 		registerEntwurfV2Tool(pi);
+		registerCallbackTool(pi);
 		registerFreshCallTool(pi);
 		registerResumeCallTool(pi);
 	}
@@ -1740,6 +1742,60 @@ interface VisibleResumeModule {
 	renderVisibleResume(result: { ok: boolean }): { text: string; isError: boolean };
 }
 
+function registerCallbackTool(pi: ExtensionAPI): void {
+	const registerTool = pi.registerTool as (def: any) => void;
+	registerTool({
+		name: "entwurf_callback",
+		label: "Fresh Callback",
+		description: `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. REFUSES BY NAME when the pair is absent, malformed, or this process is a Codex-provenance bridge. No arguments, no fallback to a model-supplied target.`,
+		parameters: Type.Object({}),
+		async execute(
+			_toolCallId: string,
+			_params: Record<string, never>,
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: ExtensionContext,
+		) {
+			const read = readCallbackEnv(process.env);
+			if (!read.ok) {
+				return {
+					content: [{ type: "text", text: `entwurf_callback: ${read.reason}` }],
+					isError: true,
+				};
+			}
+			try {
+				const selfMod = (await import(ENTWURF_SELF_ADDRESS_MODULE)) as unknown as EntwurfSelfAddressModule;
+				const senderProvider = (): SenderEnvelope | undefined => {
+					const s = buildLocalSenderEnvelope(ctx);
+					return s ? decoratePiSenderAddressability(s, selfMod.computeSelfAddressability) : undefined;
+				};
+				const mod = (await import(ENTWURF_V2_SURFACE_MODULE)) as unknown as EntwurfV2SurfaceModule;
+				const rendered = await mod.runAndRenderEntwurfV2FromSurface(
+					{
+						target: read.target,
+						intent: "fire-and-forget",
+						message: read.nonce,
+						wants_reply: false,
+					},
+					{ senderProvider },
+				);
+				return {
+					content: [{ type: "text", text: rendered.text }],
+					isError: rendered.isError,
+					details: { isError: rendered.isError },
+				};
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return {
+					content: [{ type: "text", text: `entwurf_callback error: ${msg}` }],
+					isError: true,
+					details: { error: msg },
+				};
+			}
+		},
+	});
+}
+
 /**
  * Unlike `entwurf_fresh_call`, this tool needs NO caller identity: a resume names an existing
  * citizen, so the address is the parameter rather than something the sibling has to report back.

package/pi-extensions/lib/acp/acp-client.ts

@@ -46,8 +46,8 @@ import type { AcpTextBlock } from "./context.js";
  * shape) and never onto those four. A field rename upstream fails the typecheck
  * here rather than silently zeroing the operator's cache-effect badge.
  */
-/** One `_meta.quota.token_count` row (claude-agent-acp 0.76.0
- *  `dist/acp-agent.js:6566-6575`). `cachedInputTokens` is cache READS — the name
+/** One `_meta.quota.token_count` row (claude-agent-acp 0.79.0
+ *  `dist/acp-agent.js:6579-6588`). `cachedInputTokens` is cache READS — the name
  *  differs from `usage.cachedReadTokens` because the shape is shared with
  *  codex-acp; `cachedWriteTokens` is Claude's extra sibling. */
 export type AcpQuotaTokenCount = {
@@ -64,7 +64,7 @@ export type AcpPromptResponse = {
 	/** Vendor-private, version-pinned. `_meta` is a standard ACP extension slot
 	 *  whose values a client may not assume, and `quota` is NOT in
 	 *  claude-agent-acp's exported types — it is produced by the private
-	 *  `turnQuotaMeta()` (read at 0.76.0 `dist/acp-agent.js:6549-6558`). Read
+	 *  `turnQuotaMeta()` (read at 0.79.0 `dist/acp-agent.js:6562-6571`). Read
 	 *  defensively, never structurally required, and re-measure on a pin move. */
 	_meta?: {
 		quota?: {

package/pi-extensions/lib/acp/backend-adapter.ts

@@ -150,7 +150,7 @@ export interface AcpAdapterSettingsParams {
  *
  * During stream handling the vendor keeps a per-message snapshot in
  * `lastAssistantUsage`, but its `usage_update` publishes only the scalar `used`
- * value (read at claude-agent-acp 0.76.0 `dist/acp-agent.js:3857-3882`). Until
+ * value (read at claude-agent-acp 0.79.0 `dist/acp-agent.js:3920-3945`). Until
  * that partition is carried on the wire, NOTHING honest can go in pi's four
  * fields, so entwurf writes none of them.
  */
@@ -342,8 +342,8 @@ export const claudeAdapter: AcpBackendAdapter = {
 
 	// MEASURED (2026-09-02, #93): claude-agent-acp's `usage_update` carries a
 	// session-cumulative ESTIMATED cost (`cost.amount = message.total_cost_usd`)
-	// and a context-occupancy scalar (`used`; both read at 0.76.0
-	// `dist/acp-agent.js:3471-3486`). Both are measured, so backend.ts seals them.
+	// and a context-occupancy scalar (`used`; both read at 0.79.0
+	// `dist/acp-agent.js:3504-3519`). Both are measured, so backend.ts seals them.
 	// The token partition is NOT declared here: ACP's only token carrier is a
 	// per-turn round-trip aggregate, which is not what pi's four fields mean.
 	sealsTurnAccounting: true,