@junghanacs/entwurf 0.13.0 → 0.14.0

package/mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js

@@ -11,7 +11,7 @@
  * Currently exposed tools (scope is deliberately narrow — anything that can live
  * as a local skill should live as a skill, not here):
  *   - entwurf_v2      — canonical delivery surface for existing garden citizens; the decider
- *                       chooses live control-socket send / dormant spawn-bg resume / meta-mailbox.
+ *                       chooses live control-socket send / meta-mailbox enqueue / native-push.
  *   - entwurf_peers   — entwurf fact surface: garden citizens (meta-records) with liveness +
  *                       diagnostics (#50 C4: record-less sockets surface THERE, never as identity).
  *                       Brain = pi-extensions/lib/entwurf-fact-provider (listEntwurfFacts) +
@@ -24,6 +24,18 @@
  *                       garden record may call this — so the surface is "drain the inbox you were
  *                       pointed at", not "drain your own". A rung doorbell is a wake attempt;
  *                       this read is the receipt.
+ *   - entwurf_register_native — explicit/manual fallback binding an ALREADY-RUNNING native
+ *                       conversation (antigravity) to a garden id. Never a spawn.
+ *   - entwurf_fresh_call — open ONE fresh visible sibling in the operator's own tmux session;
+ *                       returns a LAUNCH receipt only, and the new address arrives later as the
+ *                       sender envelope of the sibling's nonce callback.
+ *   - 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.
+ *
+ * That list is the WHOLE public surface — seven 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.
  *
  * Removed from this v2-only surface: legacy MCP `entwurf`, `entwurf_resume`, and
  * `entwurf_send`. Use `entwurf_v2` for delivery to existing garden citizens.
@@ -57,8 +69,11 @@ import { renderEntwurfPeers } from "../../../pi-extensions/lib/entwurf-peers-ren
 import { computeSelfAddressability } from "../../../pi-extensions/lib/entwurf-self-address.js";
 import { nativePushSupported } from "../../../pi-extensions/lib/entwurf-v2-contract.js";
 import { runAndRenderEntwurfV2FromSurface } from "../../../pi-extensions/lib/entwurf-v2-surface.js";
+import { makeVisibleResumeDeps, renderVisibleResume, visibleResume, } from "../../../pi-extensions/lib/entwurf-v2-visible-resume.js";
 import { probeNativeSenderAlive, resolveTrustedMetaSenderIdentity, } from "../../../pi-extensions/lib/meta-sender-identity.js";
 import { defaultMetaMailboxDir, defaultMetaSessionsDir, makeStoreRecordReader, readActiveStoreEntries, readMetaInbox, readMetaReceiverMarker, } from "../../../pi-extensions/lib/meta-session.js";
+import { freshCall, renderFreshCall } from "../../../pi-extensions/lib/mux-fresh-call.js";
+import { RESUME_CALL_REJECT_HINT, resumeCall } from "../../../pi-extensions/lib/mux-resume-call.js";
 import { registerNativeConversation } from "../../../pi-extensions/lib/native-push/register.js";
 const HOME = os.homedir();
 // Directory SOURCE is this adapter's own policy — the bridge honours an explicit
@@ -286,77 +301,49 @@ function abbreviateHomeMcp(cwd) {
 }
 // entwurf_v2 — the unified v2 dispatch verb (0.11 step 5d-3b). It hands the
 // target + intent to the 5b decider, which chooses the transport (live
-// control-socket send / spawn-bg resume / meta-mailbox enqueue / native-push
-// direct injection) and reports one outcome. The per-target lock is NOT taken by
-// every rail: the decider locks only a control-socket-domain dispatch, which
-// covers the live send AND the dormant cell's spawn-bg resume; the mailbox and
-// native-push branches carry `lock: null` (entwurf-v2-decider.ts). It runs
+// control-socket send / meta-mailbox enqueue / native-push direct injection) and
+// reports one outcome. The per-target lock is NOT taken by every rail: the decider
+// locks only a control-socket-domain dispatch; the mailbox and native-push branches
+// carry `lock: null` (entwurf-v2-decider.ts). It runs
 // IN-PROCESS here (the same production runner pi-native uses) — NOT a delegating
-// RPC — so control, mailbox, native-push, AND spawn-bg all flow through
+// RPC — so control, mailbox and native-push all flow through
 // `runEntwurfV2`. The sender envelope is
 // `buildSendSenderEnvelope()` verbatim (origin/replyable as resolved) — v2 does
 // NOT gate on replyability (a `wants_reply` from an external/non-replyable caller
 // is surfaced honestly, not rejected; the decider routes on target + intent, not
 // sender replyability).
-server.tool("entwurf_v2", "CANONICAL DELIVERY SURFACE for garden ids. When you have a garden id and want to reach " +
-    "whoever it names — message / reply / hand-off — use THIS verb. A garden id alone does " +
-    "not tell you which rail that citizen answers on — a live socket citizen, a dormant one, a " +
-    "mailbox-backed self-fetch session, or a native-push session — and entwurf_v2 is the one " +
-    'surface that reads that for you and routes correctly (so "when unsure which transport, use ' +
-    'entwurf_v2"). You give the target ' +
-    "garden id + your intent; the decider picks the transport from the target's liveness " +
-    "(live socket citizen → control-socket send; dormant socket citizen → spawn-bg resume; active " +
-    "deliverable self-fetch citizen → meta-bridge mailbox; probe-alive native-push citizen → direct " +
-    "injection into its live conversation) under the v2 lock policy, and reports ONE outcome " +
-    "(delivered / rejected / lock-retained / delivered-but-lock-dirty). LOCK POLICY (do not " +
-    "over-generalize it): the per-target lock is taken for a control-socket-DOMAIN dispatch, which is " +
-    "both the live send AND the dormant cell's spawn-bg resume — spawn-bg is a separate relaunch " +
-    "transport yet it still runs under that domain's lock. The mailbox and native-push rails are " +
-    "lock-free: the mailbox is guarded instead by active-receiver deliverability, and native-push by " +
-    "its adapter probe. The decider — not the " +
-    "caller — chooses the transport. Note: entwurf_v2 dispatches to EXISTING targets; " +
-    "brand-new sibling creation is deferred to a later v2 lane. " +
-    "CHOOSING INTENT (read this — picking wrong is rejected, never auto-fixed): to message / " +
-    "reply / hand off a peer that entwurf_peers shows as liveness=alive (a live socket citizen, " +
-    "currently backend pi) use intent: fire-and-forget — it routes to the live control-socket; set " +
-    "wants_reply:true if you need an answer (wants_reply is NOT owned-outcome). Replies to a citizen " +
-    "with NO socket liveness (liveness=unsupported) are ALSO fire-and-forget, and the decider picks " +
-    "that citizen's own rail: a self-fetch backend (e.g. Claude Code) gets the meta-bridge mailbox, " +
-    "while a native-push backend (e.g. Antigravity) gets direct injection into its live conversation " +
-    "and has NO mailbox at all — do not assume mailbox semantics for every unsupported citizen. A " +
-    "native-push target IS measured by its own adapter probe, and that probe is THREE-valued, so " +
-    "the send is never silently queued: alive → injected; dead → rejected as " +
-    "native-push-target-dead; indeterminate → rejected as native-push-probe-indeterminate. " +
-    "Those two rejects stay distinct because 'we could not establish it' is not 'it is gone' — " +
-    "collapsing them reports a guess as a fact. THERE IS A " +
-    "THIRD RESULT, so do not read liveness=unsupported as 'reachable by some rail': the mailbox path " +
-    "delivers only to a DELIVERABLE citizen (a self-fetch backend whose receiver is live and armed), " +
-    "so a terminated Claude Code session — and any record whose backend has no adapter on this lane, " +
-    "e.g. codex — is rejected as mailbox-undeliverable rather than queued into an inbox nobody drains. " +
-    "unsupported means only 'this backend has no control-socket probe'. " +
-    "owned-outcome is ONLY for waking a DORMANT socket-domain citizen (spawn-bg resume, currently " +
-    "backend pi); on a live target it is rejected as owned-live-no-autosend. Neither self-fetch nor " +
-    "native-push has resume authority, but they reject under DIFFERENT reasons — self-fetch as " +
-    "backend-liveness-unsupported, native-push as native-push-no-resume-authority. " +
-    "It is NEVER auto-converted — so pick the right intent up front. " +
-    "mode applies to a CONTROL-SOCKET send only — it is the injection style for a live pi turn, and " +
-    "the mailbox, native-push, and spawn-bg plans carry no mode at all, so setting it for those " +
-    "targets changes nothing (a native-push send IS live and still ignores it). wants_reply rides " +
-    "every rail. Use entwurf_peers to discover targets. " +
-    "Payload guidance: message hard cap 16000 chars. For larger reviews/logs, write an " +
-    "artifact and dispatch its path plus a short digest; avoid multi-part sends because " +
-    "mailbox doorbells may coalesce.", {
+server.tool("entwurf_v2", "CANONICAL DELIVERY SURFACE for garden ids: message, reply, or hand off to whoever an id names. The id " +
+    "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 " +
+    "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" — and the decider picks its own rail: a self-fetch backend (e.g. Claude Code) ' +
+    "gets the mailbox, a native-push backend (e.g. Antigravity) gets direct injection and has NO mailbox at " +
+    "all. THERE IS A THIRD RESULT: the mailbox delivers only to a DELIVERABLE citizen, so a terminated " +
+    "session, or a backend with no adapter here (e.g. codex), is mailbox-undeliverable, not queued for an " +
+    "inbox nobody drains. The native-push probe is 3-valued: alive → injected; dead → " +
+    "native-push-target-dead; indeterminate → native-push-probe-indeterminate (unestablished ≠ gone). " +
+    "DORMANT IS UNREACHABLE: a socket-domain citizen that is not running gets dormant-fire-forget-unsupported " +
+    "— same receiver rule as the mailbox, no active drainer means no delivery. " +
+    "The intent that used to answer there, owned-outcome, resumed it by launching a hidden background child " +
+    "and was withdrawn under the visible-first rule — re-open the session yourself, then dispatch again. " +
+    "LOCK: taken for a control-socket-DOMAIN dispatch. The " +
+    "mailbox and native-push rails are lock-free — deliverability and the adapter probe guard them. mode " +
+    "applies to a CONTROL-SOCKET send only; other plans carry no mode. wants_reply rides every rail. message " +
+    "caps at 16000 chars; send an artifact path + digest for more.", {
     target: z.string().min(1).describe("Target garden id (use entwurf_peers to discover)"),
     intent: z
-        .enum(["fire-and-forget", "owned-outcome"])
+        .enum(["fire-and-forget"])
         .describe("fire-and-forget = send/reply/hand-off to a LIVE socket target or to any citizen with no " +
         "socket liveness — the decider picks its rail, and a rail can also REJECT (self-fetch → " +
         "mailbox when deliverable, else mailbox-undeliverable; native-push → alive: direct injection, " +
         "dead: native-push-target-dead, indeterminate: native-push-probe-indeterminate); set " +
-        "wants_reply for an answer. owned-outcome = " +
-        "wake a DORMANT socket-domain citizen via spawn-bg resume ONLY — on a live target rejected " +
-        "as owned-live-no-autosend, on self-fetch as backend-liveness-unsupported, on native-push as " +
-        "native-push-no-resume-authority, and never auto-converted"),
+        "wants_reply for an answer. This is the ONLY intent: owned-outcome, which resumed a dormant " +
+        "citizen by launching a hidden background child, was withdrawn under the visible-first rule. " +
+        "It is not selectable, not deprecated-but-tolerated; a dormant citizen is currently " +
+        "unreachable by this verb and rejects as dormant-fire-forget-unsupported."),
     message: z
         .string()
         .min(1)
@@ -366,8 +353,8 @@ server.tool("entwurf_v2", "CANONICAL DELIVERY SURFACE for garden ids. When you h
         .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, native-push, and spawn-bg plans carry no mode, so it " +
-        "has no effect on those rails."),
+        "follow_up (queue after it). 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)"),
 }, async ({ target, intent, message, mode, wants_reply }) => {
     try {
@@ -375,8 +362,9 @@ server.tool("entwurf_v2", "CANONICAL DELIVERY SURFACE for garden ids. When you h
         // + the mailbox body sender share one envelope. No replyability gate (see above).
         const sender = await buildSendSenderEnvelope();
         const rendered = await runAndRenderEntwurfV2FromSurface({ target, intent, message, mode, wants_reply }, 
-        // agentDir / prefixRoots intentionally omitted: runAndRenderEntwurfV2FromSurface falls
-        // back to the ENTWURF_PREFIX_ROOTS env SSOT for prefixRoots (5d-4); agentDir stays undefined.
+        // No trust-preflight inputs are passed, and none exist to pass: the preflight on this
+        // path guarded the resume verdict and left with `owned-outcome`. `senderProvider` is
+        // the whole options surface now (see the pi-native surface for the same note).
         { senderProvider: () => sender });
         return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
     }
@@ -459,7 +447,9 @@ server.tool("entwurf_peers", "List the entwurf fact surface: garden citizens (fr
     "`unsupported` for a backend with no control-socket probe such as claude-code); the dispatch " +
     "decision (send vs resume) is computed LATER by the entwurf_v2 contract from that liveness, " +
     "not here — this surface carries no per-row routing field, so do not read a transport off a " +
-    "row. In particular `unsupported` does NOT mean mailbox: it means this backend has no " +
+    "row. A `dead` row is a REPORTED FACT and nothing more: that citizen is dormant and is " +
+    "currently unreachable by any verb, so listing it grants no action — appearing here is not " +
+    "an invitation to dispatch. In particular `unsupported` does NOT mean mailbox: it means this backend has no " +
     "control-socket probe. Which rail it answers on is a capability the decider resolves at dispatch " +
     "time, and there are THREE possible answers, not two — a self-fetch mailbox (only while that " +
     "mailbox is deliverable), native-push direct injection (only while its adapter probe is alive), " +
@@ -469,8 +459,8 @@ server.tool("entwurf_peers", "List the entwurf fact surface: garden citizens (fr
     "is not a departed host. So " +
     "`unsupported` does not promise reachability either: a record whose backend has no adapter on " +
     "this lane resolves to that reject. " +
-    "Note: this is the *active* world. It is NOT a fresh-sibling creation surface; pass an " +
-    "existing garden id to entwurf_v2.", {}, async () => {
+    "Note: this is the *active* world and it is facts-only — it creates nothing. Pass an " +
+    "existing garden id to entwurf_v2; to open a NEW sibling use entwurf_fresh_call.", {}, async () => {
     try {
         // Meta-store axis: entries WITH their kind (ENOENT = fresh install = empty; any
         // other readdir failure is a real error, not a silent empty). The name-only
@@ -562,6 +552,109 @@ server.tool("entwurf_register_native", "Register an ALREADY-RUNNING native conve
         return textErr(`entwurf_register_native error: ${err instanceof Error ? err.message : String(err)}`);
     }
 });
+// The caller identity for THIS surface comes from the same authoritative resolution
+// `entwurf_self` uses — BOTH of its certified paths: the pi carrier this child inherited
+// (PI_SESSION_ID + PI_AGENT_ID, which a record minted at birth), or a trusted meta-sender marker
+// the native host's own hook wrote. Neither is a guess and neither is deprecated here.
+//
+// What is refused is a caller-supplied id. The measured failure mode is exactly that: asked for
+// its own garden id, a fresh cell answered with its uuidv7 `PI_SESSION_ID` value read out of the
+// environment by an MCP server it had spawned itself — confidently, and wrong. A sibling launched
+// against that answer would call home to a garden id nobody holds.
+server.tool("entwurf_fresh_call", "Open ONE fresh visible sibling in the operator's own tmux session and hand it a first task. Two fixed " +
+    "backends only: pi, claude-code. The sibling's FIRST action is a callback to you carrying a nonce, and the " +
+    "sender envelope of that callback is its garden id — that is how you learn the address of something that " +
+    "did not exist a moment ago. This returns a LAUNCH receipt (tmux window/pane plus that nonce) and nothing " +
+    "else: it does NOT mean the runtime started, the first turn ran, or the task was delivered. Nothing polls " +
+    "for the callback; if it never arrives the window is visible and can be read directly. For EXISTING " +
+    "citizens use entwurf_v2 — this tool only creates, and entwurf_peers only reports. Model is REQUIRED and " +
+    "is passed to the chosen runtime CLI (`provider/model` for pi; model id/alias for Claude Code); there are no " +
+    "arbitrary command/cwd/env knobs. Do not put secrets in the task — model and task argv are visible to " +
+    "same-user processes on this host. Requires that this agent itself runs " +
+    "inside tmux: without a pane anchor there is no session to open a sibling beside.", {
+    backend: z
+        .enum(["pi", "claude-code"])
+        .describe("Which fixed runtime to open. Only these two; there is no arbitrary command."),
+    model: z
+        .string()
+        .min(1)
+        .max(200)
+        // The `\[` below is USELESS TO JS AND LOAD-BEARING TO THE HOST. zod emits this source
+        // text verbatim as the JSON Schema `pattern`, and the host's tool-schema validator is a
+        // Rust regex engine that rejects an unescaped `[` inside a character class as "unclosed
+        // character class" — a 400 on tools/list that stops EVERY Claude session from opening
+        // (7-M-fix). Biome's safe fix removes it; do not accept that fix. The suppression must
+        // stay on the line DIRECTLY above the expression, or it attaches to nothing and reads
+        // as an unused suppression while the escape goes back to being fixable.
+        // biome-ignore lint/complexity/noUselessEscapeInRegex: emitted to a Rust regex validator, see above
+        .regex(/^[A-Za-z0-9][A-Za-z0-9._/:\[\]-]*$/)
+        .describe("Required runtime model: canonical provider/model for pi, or a Claude Code model id/alias."),
+    task: z
+        .string()
+        .min(1)
+        .max(16000)
+        .describe("What the sibling should do after it calls you back. Plain instructions; no secrets (see the tool description)."),
+}, async ({ backend, model, task }) => {
+    let callerGardenId = null;
+    try {
+        const self = await buildAuthoritativeSelfEnvelope();
+        callerGardenId = self.envelope.sessionId;
+    }
+    catch (err) {
+        // ONE error is a legitimate answer here: this host has no authoritative identity at all
+        // (no pi carrier inherited, no trusted marker written), so the sibling would have nowhere
+        // to call home. That normalises to the named refusal.
+        //
+        // Everything else — a corrupt record, an unreadable store, a broken marker — keeps its
+        // own diagnosis and fails loud. Folding those into "you are anonymous" would relabel a
+        // store defect as a wiring choice, and the operator would go looking in the wrong place.
+        if (!(err instanceof EntwurfEnvelopeWiringError))
+            throw err;
+        callerGardenId = null;
+    }
+    try {
+        const rendered = renderFreshCall(freshCall({ backend, model, task, callerGardenId }));
+        return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
+    }
+    catch (err) {
+        return textErr(`entwurf_fresh_call error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// The composition root for a visible resume: this surface is the only layer that may know BOTH
+// halves, so it is where the mux launcher is handed to the v2 composition. `entwurf-v2-visible-
+// resume` cannot open a window on its own and `mux-resume-call` cannot read a record — that is
+// the import fence in docs/mux-launch-rail.md §11, expressed as a function argument.
+const visibleResumeLaunch = (input) => {
+    const launched = resumeCall({ cwd: input.cwd, runtimeArgs: input.runtimeArgs });
+    return launched.ok
+        ? { ok: true, handle: launched.receipt }
+        : { ok: false, reason: launched.reason, hint: RESUME_CALL_REJECT_HINT[launched.reason] };
+};
+server.tool("entwurf_resume_call", "Reopen ONE DORMANT pi citizen under its OWN garden id, in a visible window in the operator's own tmux " +
+    "session. The record supplies everything — which transcript, which model, which provider, which cwd — so " +
+    "the only input is the target id: there is no model override, no task, and no prompt. This runs NO turn: " +
+    "the window comes back with the conversation and waits, and talking to it is still entwurf_v2 " +
+    "fire-and-forget on the socket this call stands up. You get TWO receipts and they mean different things: a " +
+    "LAUNCH receipt (tmux made a window and was asked to start pi) and an OBSERVATION receipt (the control " +
+    "socket answered under the same id, or resume-unobserved). Unobserved is a real outcome, not an error to " +
+    "retry — the window is visible, so read it. A citizen that is already LIVE is refused: address it with " +
+    "entwurf_v2 instead. Only pi citizens have a same-id resume, because only they stand a control socket up. " +
+    "Requires that this agent itself runs inside tmux.", {
+    target: z
+        .string()
+        .min(1)
+        .regex(/^\d{8}T\d{6}-[0-9a-f]{6}$/)
+        .describe("Garden id of the DORMANT pi citizen to reopen (discover with entwurf_peers)."),
+}, async ({ target }) => {
+    try {
+        const result = await visibleResume(target, makeVisibleResumeDeps(visibleResumeLaunch));
+        const rendered = renderVisibleResume(result);
+        return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
+    }
+    catch (err) {
+        return textErr(`entwurf_resume_call error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
 // ============================================================================
 // Main
 // ============================================================================

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/acp-client.js

@@ -39,6 +39,18 @@ export function connectAcpClient(stream, handlers) {
         newSession: (params) => agent.request(AGENT_METHODS.session_new, params),
         prompt: (params) => agent.request(AGENT_METHODS.session_prompt, params),
         setSessionConfigOption: (params) => agent.request(AGENT_METHODS.session_set_config_option, params),
+        cancel: (params) => {
+            // Notification, not a request: nothing resolves it, and the connection
+            // may already be closing when the operator aborts. Swallow both the sync
+            // throw and the rejected send — the caller's abort path continues either
+            // way (it escalates to teardown after a bounded grace).
+            try {
+                void Promise.resolve(agent.notify(AGENT_METHODS.session_cancel, params)).catch(() => { });
+            }
+            catch {
+                // connection already closed — the abort path escalates on its own.
+            }
+        },
         close: (error) => {
             // Best-effort by contract (see AcpConnectionLike.close): a teardown-path
             // close that threw would mask the turn's real error and skip the child

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/backend-adapter.js

@@ -1,9 +1,10 @@
 // ACP backend adapter rail — the PRODUCT seam by which a curated model id selects
-// which ACP backend (claude / future backend / …) drives a turn. See docs/acp-backend-rail.md §9.
+// which ACP backend (claude / future backend / …) drives a turn. See the adapter contract in
+// docs/acp-backend-rail.md.
 //
 // This seam is DISTINCT from `AcpTurnDeps` (backend.ts), which is the test/runtime
-// seam (fake spawn/connection/clock for the gates). The two are kept apart on
-// purpose (GPT-agreed §9-2): merging them would make a fake-deps fixture look like
+// seam (fake spawn/connection/clock for the gates). Merging them would make a
+// fake-deps fixture look like
 // a fake backend and force the adapter to carry clock/sessionDir/createConnection.
 // The wiring is `defaultDeps(adapter)` — the turn loop in backend.ts stays
 // backend-invariant; only these per-backend functions change with `adapter`.
@@ -54,7 +55,7 @@ function resolveClaudeLaunch() {
 }
 export const claudeAdapter = {
     backend: "claude",
-    // Claude owns its UNPREFIXED curated ids only (GPT-agreed §9-1). The native id
+    // Claude owns its UNPREFIXED curated ids only (rail “Adapter contract”). The native id
     // equals the curated id — claude carries no curation prefix to strip.
     routeModel(modelId) {
         return SUPPORTED_CLAUDE_IDS.has(modelId) ? { nativeModelId: modelId } : undefined;
@@ -121,7 +122,7 @@ export const claudeAdapter = {
  *  adapters claim one id. */
 // ---------------------------------------------------------------------------
 // cortex adapter — Snowflake Cortex Code, the first non-claude backend on the
-// rail (docs/acp-backend-rail.md §4/§6). It adds ZERO to the common layer:
+// rail (docs/acp-backend-rail.md, “Shipped adapters”). It adds ZERO to the common layer:
 // everything cortex-specific lives here + models.ts + overlay.ts + the gates.
 // ---------------------------------------------------------------------------
 const SUPPORTED_CORTEX_IDS = new Set(SUPPORTED_CORTEX_MODEL_IDS);
@@ -131,7 +132,7 @@ const SUPPORTED_CORTEX_IDS = new Set(SUPPORTED_CORTEX_MODEL_IDS);
 export const CORTEX_CONNECTION_ENV = "ENTWURF_ACP_CORTEX_CONNECTION";
 export const cortexAdapter = {
     backend: "cortex",
-    // Cortex owns the reserved `cortex-` prefix (§9-1). routeModel strips it to the
+    // Cortex owns the reserved `cortex-` prefix (rail “Adapter contract”). routeModel strips it to the
     // native id: `cortex-auto` → "auto", `cortex-claude-sonnet-5` → "claude-sonnet-5".
     routeModel(modelId) {
         if (!SUPPORTED_CORTEX_IDS.has(modelId))
@@ -213,7 +214,7 @@ export const cortexAdapter = {
         });
         return { envOverrides: { HOME: overlay.home, SNOWFLAKE_HOME: overlay.snowflakeHome } };
     },
-    // System-prompt-carrier-less (§9-4/§11-8): Cortex ACP exposes no
+    // System-prompt-carrier-less (ACP rail “Cortex Code audit”): Cortex ACP exposes no
     // `_meta.systemPrompt` and has no developer_instructions / GEMINI_SYSTEM_MD
     // equivalent. (It does READ `_meta` — a caller-session-id seam, measured but
     // unexplored and deliberately not part of this contract.) loadCarrier returns
@@ -242,7 +243,7 @@ export const cortexAdapter = {
         }
         await setConfig.call(connection, { sessionId: acpSessionId, configId: "model", value: nativeModelId });
     },
-    // A connection change must invalidate a reused session (§4/§7). Flat,
+    // A connection change must invalidate a reused session (rail: Adapter contract). Flat,
     // sorted-stable primitive map; reads ONLY the opaque adapterSettings. `backend`
     // + `nativeModelId` are added by backend.ts.
     configSignatureFields(adapterSettings) {
@@ -254,7 +255,7 @@ const ADAPTERS = [claudeAdapter, cortexAdapter];
 /**
  * Resolve the backend adapter that owns `modelId`.
  *
- * GPT-agreed §9-1 fail-fast contract:
+ * Routing fail-fast contract (rail “Adapter contract”):
  *  - 0 matches  → throw (unknown model — no silent default).
  *  - 2+ matches → throw (prefix collision — a startup-visible registry bug).
  *
@@ -278,7 +279,7 @@ export function resolveAcpBackendAdapter(modelId) {
     return matches[0];
 }
 /** Every curated model row across all registered adapters — for provider registration.
- *  GPT-agreed §9-6 registration-time fail-fast: every curated id must route to EXACTLY
+ *  Registration-time fail-fast (rail “Adapter contract”): every curated id must route to EXACTLY
  *  one adapter and no id may be duplicated across adapters. Catching it here means a
  *  prefix-collision / duplicate surfaces at provider registration, not mid-turn. */
 export function allCuratedModels() {

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/config.js

@@ -23,7 +23,7 @@
 // the backend-invariant exclude-tools preflight and folds every one of them into
 // `bridgeConfigSignature` (so changing one still invalidates a reused cortex
 // session). Backend-OWNED settings never land here: they ride the opaque
-// `adapterSettings` seam (§10 B), which is what keeps a backend-named key like
+// `adapterSettings` seam (rail “Adapter contract”), which is what keeps a backend-named key like
 // `cortexConnection` off this common shape.
 //
 // PURITY / SIGNATURE contract (NEXT oracle C / 핀1 / GPT `…2f9325` boost):

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/engraving.js

@@ -35,11 +35,30 @@
 // incompatible and the next turn opens a fresh ACP session with the new carrier.
 // That per-turn rebuild is the accepted cost of the A/B opt-in surface, never the
 // shipped default (which stays cached precisely so a resident never rebuilds).
+//
+// A-JOIN (measured LIVE 2026-07-31, 0.64.0 adapter, fresh Claude ACP): the model's
+// system prompt arrived as
+//   `You are a Claude agent, built on Anthropic's Claude Agent SDK.# Engraving Here`
+// A string-form `_meta.systemPrompt` replaces the `claude_code` preset, but the
+// SDK still PREFIXES its own fixed identity sentence and joins the two with
+// NOTHING — so the operator's heading was swallowed into the tail of the SDK's
+// sentence. The boundary therefore belongs to the CARRIER, and it cannot be
+// delegated to engraving.md: the render is trimmed (below), so a leading blank
+// line in the markdown is eaten before it ever reaches the wire.
 import { readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ENGRAVING_PATH = join(HERE, "prompts", "engraving.md");
+/**
+ * The carrier's LEADING boundary — the one the Claude Agent SDK does not supply
+ * (see A-JOIN above). A constant, never derived from the template, so the render
+ * stays a pure function of (template, backend, mcpServerNames) and the operator's
+ * file whitespace can never drift `bridgeConfigSignature`. One blank line is the
+ * whole lever: it puts the carrier's first line at the start of its own block
+ * instead of at the end of the SDK's fixed sentence.
+ */
+export const CARRIER_LEAD_SEPARATOR = "\n\n";
 let cached = null;
 /** Point the loader at an alternate engraving file (A/B); bypasses the cache. */
 function resolveEngravingPath() {
@@ -65,6 +84,22 @@ function interpolate(template, params) {
     const mcpList = names.length > 0 ? names.join(", ") : "(none registered)";
     return template.replace(/\{\{backend\}\}/g, params.backend).replace(/\{\{mcp_servers\}\}/g, mcpList);
 }
+/**
+ * Render one template into a wire-ready carrier, or `""` when the template has no
+ * body (the caller turns that into the opt-out / fail-loud branches).
+ *
+ * The ORDER here is the A-join fix. Trim first: the operator template's own
+ * leading/trailing whitespace must not reach the wire (it would drift
+ * bridgeConfigSignature) and the emptiness test must see the BODY — a
+ * separator-only string is an opt-out, not a carrier. Then attach OUR boundary,
+ * which is what the SDK's fixed sentence has nothing of.
+ */
+function renderCarrier(source, params) {
+    const body = interpolate(source, params).trim();
+    if (body.length === 0)
+        return "";
+    return `${CARRIER_LEAD_SEPARATOR}${body}`;
+}
 /**
  * The rendered engraving carrier, or null when an ENV-OVERRIDE engraving file
  * (`ENTWURF_ACP_ENGRAVING_PATH`) is empty, whitespace-only, missing, or
@@ -77,6 +112,12 @@ function interpolate(template, params) {
  * Callers MUST treat null as "no carrier configured" and omit `_meta.systemPrompt`
  * entirely (passing "" as the `appendSystemPrompt` signature input) so
  * subscription billing is never reclassified.
+ *
+ * A non-null carrier always LEADS with `CARRIER_LEAD_SEPARATOR`, and callers must
+ * pass it on BYTE-FOR-BYTE: the same string feeds `bridgeConfigSignature`
+ * (`appendSystemPrompt`) and the wire (`_meta.systemPrompt`), so normalizing it at
+ * either hop both re-opens the A-join and makes reuse key on a string that was
+ * never sent.
  */
 export function loadEngraving(params) {
     const filePath = resolveEngravingPath();
@@ -92,7 +133,7 @@ export function loadEngraving(params) {
         }
         return null;
     }
-    const rendered = interpolate(source, params).trim();
+    const rendered = renderCarrier(source, params);
     if (rendered.length === 0) {
         if (isShippedDefault) {
             throw new Error(`entwurf: shipped engraving carrier at ${filePath} is empty — it is the auto-memory ` +

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/models.js

@@ -9,8 +9,8 @@
 // Two curated sets live here, one per adapter on the rail
 // (backend-adapter.ts): the unprefixed Claude ids (the reference backend) and
 // the `cortex-` prefixed Snowflake Cortex Code ids (the second backend, landed
-// 0.13.0 — docs/acp-backend-rail.md §6/§11-8). Codex is already a native garden
-// citizen and Gemini/major tools use native, so neither is an ACP backend here.
+// 0.13.0 — docs/acp-backend-rail.md “Cortex Code audit”). Codex has native
+// delivery-probe evidence but no managed citizen lane; neither it nor Gemini is an ACP backend here.
 // A third governed backend EXTENDS this file the same way — it does not change
 // the pattern.
 // pi 0.80 migration: the standalone root `getModels()` moved to the deprecated
@@ -77,9 +77,9 @@ function claudeContextWindow(model) {
 // ── Cortex (Snowflake Cortex Code) curated surface ──────────────────────────
 //
 // entwurf's ACP rail is backend-extensible: Cortex is the first NON-claude
-// backend to land through it (docs/acp-backend-rail.md §6). pi-ai carries no
+// backend to land through it (docs/acp-backend-rail.md, “Shipped adapters”). pi-ai carries no
 // snowflake/cortex model source, so this surface is HAND-CURATED. Every id
-// carries the reserved `cortex-` prefix (§9-1): the prefix is the SINGLE routing
+// carries the reserved `cortex-` prefix: the prefix is the SINGLE routing
 // authority (backend-adapter.ts `routeModel`) and keeps the ids off the Claude
 // native ids Cortex routes to (`cortex-claude-sonnet-5` vs the unprefixed
 // `claude-sonnet-5` the claude adapter owns). `routeModel` strips the prefix to

package/mcp/entwurf-bridge/dist/pi-extensions/lib/acp/overlay.js

@@ -2,8 +2,8 @@
 //
 // claude-agent-acp's SettingsManager loads the operator's `~/.claude/settings.json`
 // DIRECTLY (CLAUDE_CONFIG_DIR is the only knob that redirects that read). So the
-// operator's native `permissions.defaultMode` ("auto"), hooks, plugins, and
-// per-cwd memory/projects state would otherwise leak into entwurf ACP
+// operator's native `permissions.defaultMode` (whatever its current value), hooks,
+// plugins, and per-cwd memory/projects state would otherwise leak into entwurf ACP
 // sessions. The overlay redirects SettingsManager at a pi-owned directory whose
 // `settings.json` WE author (minimal, `hooks:{}`), while keeping exactly the
 // operator entries a backend needs (credentials, caches, built-in skills)
@@ -15,7 +15,7 @@
 // materializer, and cortex did: `ensureCortexDualHomeOverlay` (+ projectCortexMcpJson /
 // sweepDeadCortexOverlays / cortexOverlayScopeId) lives further down this file with its
 // own D-number rationale — an isolated HOME rather than a redirect knob, because cortex
-// has no CLAUDE_CONFIG_DIR equivalent (§11-8 D2). The two share the module, never the
+// has no CLAUDE_CONFIG_DIR equivalent (ACP rail Cortex audit D2). The two share the module, never the
 // strategy. Codex/Gemini overlays (CODEX_HOME / admin.toml) remain behavior-oracle
 // territory and are out of scope here.
 //
@@ -86,9 +86,11 @@ export const OVERLAY_EMPTY_DIRS = new Set(["projects", "sessions"]);
 export const OVERLAY_BINARY_OWNED = new Set([".claude.json", "backups", "settings.json"]);
 /**
  * Minimal overlay settings.json. Only fields with a reason to pin:
- *   - `permissions.defaultMode: "default"` neutralizes the operator's native
- *     "auto"; combined with the explicit `tools`/`permissionAllow` surface,
- *     "default" auto-passes every tool we expose without prompts.
+ *   - `permissions.defaultMode: "bypassPermissions"` is deliberate unattended
+ *     ACP operation: a tool call must never suspend a model turn on an interactive
+ *     permission prompt. This does not widen the callable surface — explicit
+ *     `tools`/`disallowedTools` still shape it, and `permissionAllow` still rides
+ *     the inline Claude settings — or bypass backend authentication.
  *   - `autoMemoryEnabled: false` — SDK opt-out for auto-memory (defense in
  *     depth; the tiny non-empty engraving/preset replacement is the primary
  *     write-containment lever for Claude ACP).
@@ -97,7 +99,7 @@ export const OVERLAY_BINARY_OWNED = new Set([".claude.json", "backups", "setting
  */
 export function overlaySettingsJson() {
     return `${JSON.stringify({
-        permissions: { defaultMode: "default" },
+        permissions: { defaultMode: "bypassPermissions" },
         autoMemoryEnabled: false,
         hooks: {},
     }, null, 2)}\n`;
@@ -201,11 +203,11 @@ export function ensureClaudeConfigOverlay(realDir = CLAUDE_REAL_CONFIG_DIR, over
 }
 // ============================================================================
 // Cortex dual-HOME overlay — the as-measured containment for `cortex acp serve`
-// (CP0 audit 2026-07-29, Cortex Code v1.1.52; docs/acp-backend-rail.md §4/§11-8).
+// (CP0 audit 2026-07-29, Cortex Code v1.1.52; docs/acp-backend-rail.md “Cortex Code audit”).
 // ============================================================================
 //
 // Why this is NOT the claude-shaped `SNOWFLAKE_HOME`-only overlay PR #40 shipped
-// (each point is a measured defect, not a preference — §11-8 D-numbers):
+// (each point is a measured defect, not a preference — Cortex audit D-numbers):
 //
 //   - D2: cortex reads `CONFIG_DIRS = [".claude", ".cortex"]` at `homedir()` and
 //     `~/.claude/skills` — a SNOWFLAKE_HOME redirect cannot move that axis. An

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-control-rpc.js

@@ -16,12 +16,14 @@
 import * as net from "node:net";
 /**
  * THE `<sender_info>` synthesis — the one place the sender envelope becomes
- * message text. Two consumers, one shape (#50 C3):
+ * message text. ONE consumer since the visible-first cut (#50 C3):
  *   - the live socket rail's RECEIVER (entwurf-control handleCommand("send")
- *     appends it to the delivered customMessage);
- *   - the dormant spawn-resume rail's SENDER (entwurf-v2-production appends it
- *     to the resume prompt, so a resumed citizen wakes knowing who called in
- *     exactly the shape a live delivery would have rendered).
+ *     appends it to the delivered customMessage).
+ *
+ * The second consumer was the dormant spawn-resume rail's SENDER, which appended
+ * the same shape to a resume prompt so a resumed citizen woke knowing who called.
+ * That rail is gone. The shape stays single-sourced here so a future VISIBLE
+ * resume renders an identical envelope rather than inventing a second one.
  * `wants_reply` is emitted only when explicitly true — an unset/false marker
  * renders nothing (etiquette marker, not transport contract).
  */