@junghanacs/entwurf 0.12.9 → 0.12.10

package/pi-extensions/entwurf-control.ts

@@ -108,9 +108,10 @@ const SESSION_MESSAGE_TYPE = "entwurf-message";
 // with the receive-side [entwurf received ⟵] box. The provider-level context
 // filter in index.ts drops this customType before the LLM sees it — colocated
 // with the emitter so sessions without --entwurf-control are still protected.
-// Layer A (native path) reuses the same Box builder via renderSentMessage() but
-// does NOT emit a CustomMessage; the native tool result already lives in the
-// toolResult role and never enters LLM context as a user message.
+// There is no second emitter: the v1 native send path ("Layer A") that also drew
+// this box through renderSentMessage() was removed in the 0.12 cutover, and
+// renderSentMessage is now registered for exactly one customType (see
+// registerMessageRenderer below). Do not describe a native sender-side box.
 const SENDER_INFO_PATTERN = /<sender_info>[\s\S]*?<\/sender_info>/g;
 
 // ============================================================================
@@ -509,8 +510,8 @@ const renderSessionMessage: MessageRenderer = (message, { expanded }, theme) =>
 };
 
 // Sender-side payload — what renderSentMessage needs to draw the [entwurf sent →]
-// box. Carried verbatim by both Layer A (native renderResult) and Layer B
-// (CustomMessage details for ACP path). All four envelope fields are intentionally
+// box. Carried by the ACP path's CustomMessage `details` — the ONLY carrier since
+// the v1 native renderResult path was removed (0.12 cutover). All four envelope fields are intentionally
 // echoed in the box even though the sender is "this same session" — operators
 // reading a busy multi-session transcript should be able to verify at a glance
 // which 담당자 is on the wire (cwd) and which model identity (agentId) actually
@@ -520,9 +521,10 @@ const renderSessionMessage: MessageRenderer = (message, { expanded }, theme) =>
 // re-renders (resize, expand toggle) keep showing the moment the message was
 // actually delivered rather than drifting forward to "now".
 //
-// wants_reply mirrors the receive-side etiquette badge. Native schema does not
-// yet expose it (see registerSessionTool's entwurfSendParameters); leave undefined
-// from the native call site until the schema grows the field.
+// wants_reply mirrors the receive-side etiquette badge. It stays optional because
+// the box is drawn from a CustomMessage whose `details` may predate the field; the
+// v1 `registerSessionTool` / `entwurfSendParameters` schema this note used to point
+// at is gone (0.12 cutover), so there is no native call site left to grow.
 interface SentBoxData {
 	to: string; // target sessionId
 	from?: string; // sender agentId, e.g. "entwurf/claude-opus-5"
@@ -1274,9 +1276,18 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		target: Type.String({ description: "Target garden id (use entwurf_peers to discover)" }),
 		intent: StringEnum(["fire-and-forget", "owned-outcome"] as const, {
 			description:
-				"fire-and-forget = send/reply/hand-off to a LIVE or meta-session target (set wants_reply for an answer); " +
-				"owned-outcome = wake a DORMANT pi via spawn-bg resume ONLY — on a live target it is rejected " +
-				"(owned-live-no-autosend) and never auto-converted",
+				"fire-and-forget = send/reply/hand-off to a LIVE socket target (currently backend pi) or to any " +
+				"citizen with no socket liveness — the decider picks that citizen's rail, and a rail can also " +
+				"REJECT: self-fetch (e.g. Claude Code) → meta-bridge mailbox while that mailbox is DELIVERABLE, " +
+				"else rejected as mailbox-undeliverable; native-push (e.g. Antigravity) → direct injection into " +
+				"its live conversation, which has NO mailbox, and its probe is three-valued — alive: injected, " +
+				"dead: native-push-target-dead, indeterminate: native-push-probe-indeterminate (two rejects, " +
+				"not one). " +
+				"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 (both lack resume authority, but the reasons " +
+				"differ because native-push IS probe-measured), and never auto-converted",
 		}),
 		message: Type.String({
 			description:
@@ -1285,7 +1296,9 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		}),
 		mode: Type.Optional(
 			StringEnum(["steer", "follow_up"] as const, {
-				description: "Delivery mode for a live send: steer (immediate) or follow_up (after task)",
+				description:
+					"Injection style for a CONTROL-SOCKET send only: steer (immediate) or follow_up (after task). " +
+					"The mailbox, native-push, and spawn-bg plans carry no mode, so it has no effect on those rails.",
 			}),
 		),
 		wants_reply: Type.Optional(Type.Boolean({ description: "Human-conversation reply hint (default false)" })),
@@ -1299,6 +1312,11 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		wants_reply?: boolean;
 	};
 
+	// TS2589 ("type instantiation is excessively deep") workaround: pi's registerTool
+	// generic infers the handler signature from the TypeBox schema, and this schema is
+	// deep enough to blow the instantiation budget. Casting the FUNCTION (not the
+	// argument) keeps the schema itself typed while stopping the inference walk.
+	// Revisit when pi's registerTool takes an explicit params type parameter.
 	const registerTool = pi.registerTool as (def: any) => void;
 
 	registerTool({
@@ -1306,28 +1324,51 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 		label: "Dispatch (v2)",
 		description: `CANONICAL delivery surface for a garden id. 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
-reveal whether the target is a live pi session, a dormant pi session, or a Claude Code meta-session,
+reveal which rail that citizen answers on — a live socket session, a dormant one, a mailbox-backed
+self-fetch session, or a native-push session —
 and entwurf_v2 is the one surface that reads that and routes correctly (so "when unsure which
 transport, use entwurf_v2"). It dispatches to EXISTING targets; brand-new sibling creation is deferred
 to a later v2 lane. Dispatch to a garden citizen through the unified entwurf_v2 verb: the 5b decider
-picks the transport (live control-socket send / spawn-bg resume / meta-mailbox enqueue) from the
-target's liveness + your intent, runs it under the v2 lock policy (pi paths take a per-target lock;
-the mailbox path is lock-free, guarded by active-receiver deliverability), and reports one outcome
-(delivered / rejected / lock-retained / delivered-but-lock-dirty).
+picks the transport (live control-socket send / spawn-bg resume / meta-mailbox enqueue / native-push
+direct injection) from the target's liveness + your intent, runs it 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.
 
 - target: the garden id of the citizen to reach (required).
 - intent: fire-and-forget (a send with no owned result) or owned-outcome (you own the result).
 - message: the message/prompt to dispatch (required).
-- mode: steer or follow_up for a live send (optional).
-- wants_reply: reply hint for a live send (optional, default false).
+- mode: steer or follow_up for a CONTROL-SOCKET send (optional). The mailbox, native-push, and
+  spawn-bg plans carry no mode, so it has no effect on those rails — a native-push send IS live and
+  still ignores it.
+- wants_reply: reply hint; it rides every rail (optional, default false).
 
 CHOOSING INTENT (picking wrong is rejected, never auto-fixed): to message / reply / hand off a peer
-that entwurf_peers shows as liveness=alive (a live pi citizen), 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). For a meta-session (liveness=unsupported, e.g. Claude Code), replies are ALSO
-fire-and-forget (→ mailbox). owned-outcome is ONLY for waking a DORMANT pi citizen (spawn-bg resume);
-on a live target it is rejected as owned-live-no-autosend, on an unsupported backend as
-backend-liveness-unsupported, and is NEVER auto-converted — so pick the right intent up front.
+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 last two stay separate on purpose — "we could not establish
+it" is not "it is gone". 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.
 
 The decider — not this surface — chooses the transport.`,
 		parameters: entwurfV2Parameters,
@@ -1433,8 +1474,9 @@ async function renderEntwurfPeersForSurface(): Promise<{ text: string; payload:
 }
 
 function registerListSessionsTool(pi: ExtensionAPI): void {
-	// Same TS2589 workaround as registerSessionTool — see the comment block
-	// in that function for the revisit conditions.
+	// Same TS2589 workaround as registerEntwurfV2Tool — see the comment block there
+	// for the revisit conditions. (It used to point at registerSessionTool, which was
+	// removed in the 0.12 cutover, so the pointer dangled.)
 	const registerTool = pi.registerTool as (def: any) => void;
 	registerTool({
 		name: "entwurf_peers",

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

@@ -9,9 +9,11 @@
 // operator entries a backend needs (credentials, caches, built-in skills)
 // reachable through a TIGHT symlink whitelist — nothing else.
 //
-// Scope (NEXT §스코프 / §S2-scout 핀3): Claude-only on this lane. Codex/Gemini
-// overlays (CODEX_HOME / admin.toml) are 0.11.0 behavior-oracle territory and
-// out of scope — the bridge backends are not in v2 yet.
+// Scope (NEXT §스코프 / §S2-scout 핀3): Claude-only on this lane. Claude is the one
+// shipped ACP backend, so this materializer is written for its config surface alone.
+// Codex/Gemini overlays (CODEX_HOME / admin.toml) are behavior-oracle territory and
+// out of scope here; a SECOND ACP backend enters only once the entry conditions in
+// docs/acp-backend-rail.md are met, and it brings its own overlay.
 //
 // Two deliberate divergences from the literal 0.11.0 illustrative comment block
 // (the 0.11.0 CODE already does both — only its top doc-comment drew projects/

package/pi-extensions/lib/entwurf-core.ts

@@ -1,14 +1,29 @@
 /**
  * entwurf-core — sync entwurf execution, host-agnostic.
  *
- * Single implementation shared by:
- *   - pi-extensions/entwurf.ts (pi native tool surface)
- *   - mcp/entwurf-bridge/src/index.ts (MCP tool surface for ACP hosts)
+ * DIRECT importers, MEASURED from the import graph (2026-07-27) — not from memory:
+ *   - pi-extensions/entwurf-control.ts (the pi adapter)
+ *   - pi-extensions/lib/entwurf-v2-spawn-production.ts (v2 spawn-bg launch identity)
+ *   - pi-extensions/lib/project-trust-handler.ts · lib/acp/augment.ts ·
+ *     lib/native-push/adapter.ts
+ *   - plus gates/smokes (check-shell-quote, check-package-source-routing, …)
+ *
+ * The MCP bridge is a TRANSITIVE consumer, not a direct one, and the distinction is the
+ * whole point: `mcp/entwurf-bridge/src/index.ts → entwurf-v2-surface.ts →
+ * entwurf-v2-production.ts → entwurf-v2-spawn-production.ts → entwurf-core.ts`. So the old
+ * header's claim — that the bridge imports this shared implementation the way a v1 tool
+ * surface did — was false, but so is "the bridge does not reach it": it reaches it at
+ * runtime, only for spawn-bg production.
+ *
+ * NOT consumers on any path: `pi-extensions/entwurf.ts` (the v1 pi native tool surface) and
+ * `pi-extensions/lib/entwurf-async.ts` were REMOVED in the 0.12 cutover. Do not reintroduce
+ * either as a live consumer.
  *
  * This module MUST NOT import anything from @earendil-works/pi-coding-agent or any
- * other pi runtime API. It is pure Node + @sinclair/typebox-free.  Anything that
- * requires pi's ExtensionAPI (sendMessage, appendEntry, sessionManager) belongs
- * in the async entwurf path, which stays in pi-extensions/entwurf.ts for now.
+ * other pi runtime API. It is pure Node + @sinclair/typebox-free. Anything that
+ * requires pi's ExtensionAPI (sendMessage, appendEntry, sessionManager) belongs to a
+ * pi-adapter surface, never here — the v1 async entwurf path that used to hold that
+ * work went away with `pi-extensions/entwurf.ts`.
  *
  * Scope:
  *   - sync execution (spawn pi, collect message_end events, return summary)
@@ -67,9 +82,11 @@ const PI_SETTINGS_PATH = process.env.PI_SETTINGS_PATH
 	: path.join(AGENT_DIR, "settings.json");
 export const ENTWURF_CODEX_ACP_ENV = "ENTWURF_ACP_FOR_CODEX";
 
-// Currently unused: remote/SSH entwurf is fail-fast in 0.9.0 (garden-native
-// identity is local-FS only). Retained for #11 remote revival; parity-gated by
-// scripts/check-shell-quote.ts across entwurf.ts / entwurf-core.ts / entwurf-async.ts.
+// Currently unused: remote/SSH entwurf is fail-fast (garden-native identity is
+// local-FS only). Retained for #11 remote revival and pinned by
+// scripts/check-shell-quote.ts, whose SOURCE_SITES is now THIS FILE ALONE — the
+// entwurf.ts / entwurf-async.ts halves of that former parity check were removed
+// with those files, so there is no cross-file parity left to assert.
 // biome-ignore lint/correctness/noUnusedVariables: retained for #11 remote revival; parity-gated.
 function shellQuote(value: string): string {
 	return `'${value.replace(/'/g, `'\\''`)}'`;

package/pi-extensions/lib/entwurf-deliverability.ts

@@ -18,9 +18,10 @@
  *    drains its own inbox on wake. A DIRECT-INJECT backend (pi / codex / antigravity)
  *    has no mailbox drain at all — enqueuing for it is the SE-1 false success
  *    ("✓ delivered" into a void). So deliverable = wakeMode === "self-fetch" AND the
- *    receiver is active. This is the guard that the v1 fallback, MCP v1, pi-native v1,
- *    and the v2 decider/send-fallback enqueue sites must all pass before writing a
- *    .msg (slice 2d).
+ *    receiver is active. Every enqueue site must pass this guard before writing a .msg
+ *    (slice 2d). The shipped sites are the v2 decider and its send-fallback re-resolve;
+ *    the v1 fallback / MCP v1 / pi-native v1 sites this once also listed were removed in
+ *    the 0.12 cutover — do not read them as live.
  *
  *  - nativePushDeliverable(facts): the SEPARATE deliverability predicate for a
  *    NATIVE-PUSH backend (antigravity). A native-push citizen has no mailbox and no
@@ -89,9 +90,12 @@ export interface ReceiverIdentityFacts {
  * Does this presence marker actually belong to the target identity? A marker that is
  * absent, or whose garden id / backend / native session id has drifted from the record,
  * is NOT this receiver — fail-closed (a stale/foreign marker must never raise a dead
- * target to "active"). The single source of truth for "marker ↔ identity match" shared
- * by the v1 mailbox guard (gatherMailboxDeliverabilityFacts) and the v2 production
- * `mailboxDeliverabilityFor` seam, so the two paths cannot drift to different meanings.
+ * target to "active"). The single source of truth for "marker ↔ identity match". Its
+ * PRODUCTION consumers are the v2 `mailboxDeliverabilityFor` seam and the MCP bridge's
+ * `entwurf_self`. There is no second implementation: `entwurf-mailbox-guard.ts` used to
+ * wrap this atom with its own enqueue orchestration, had ZERO production importers (import
+ * graph measured 2026-07-27), and was DELETED rather than left as a green gate proving only
+ * retired behaviour. A new enqueue site consults this predicate through that seam.
  */
 export function receiverMarkerMatchesIdentity(
 	marker: ReceiverIdentityFacts | null | undefined,

package/pi-extensions/lib/entwurf-fact-provider.ts

@@ -5,8 +5,8 @@
  * (one-way: provider → facts / socket-discovery / meta-session) — no import cycle
  * with `entwurf-facts.ts` (which owns `SocketProbe`/`resolveFactList`).
  *
- *   listAllMetaIdentities → pi gid 추출 → scanSocketProbes(piGids)
- *     → pre-quarantine non-pi/socket conflicts → resolveFactList(clean)
+ *   listAllMetaIdentities → socket-domain gid extraction → scanSocketProbes
+ *     → pre-quarantine out-of-domain/socket conflicts → resolveFactList(clean)
  *     → { facts, diagnostics }
  *
  * Two throw-vs-diagnostics policies, kept distinct (GPT힣 C-원칙):
@@ -20,14 +20,14 @@
  *     — that is not a re-implementation of the collision rule, it is input
  *     sanitation that leaves the pure-core invariant intact.
  *
- * The non-pi+socket collision quarantines BOTH sides (the PeerFact AND the
- * socket): gardenId is the universal address and a send path reads the socket
+ * An out-of-socket-domain record/socket collision quarantines BOTH sides (the
+ * PeerFact AND the socket): gardenId is the universal address and a send path
  * first, so surfacing the record alone (as a clean `unsupported` PeerFact) while
  * a same-gid socket exists would be half a lie. Both leave the normal output;
  * one diagnostic carries the fact. (pi + same-gid socket = the normal merge.)
  */
 
-import { type FactList, isNonPiGardenIdSocketConflict, resolveFactList } from "./entwurf-facts.ts";
+import { type FactList, isOutOfSocketDomainGardenIdConflict, resolveFactList } from "./entwurf-facts.ts";
 import { isLivenessSupported } from "./entwurf-v2-contract.ts";
 import {
 	type ActiveStoreEntry,
@@ -130,8 +130,8 @@ export async function listEntwurfFacts(deps: EntwurfFactsDeps): Promise<EntwurfF
 	// 2. socket axis — probe (dir sockets) ∪ (in-domain citizen canonical paths).
 	//    Its three hazards (symlink forgery / malformed name / dir-read error) are
 	//    folded into diagnostics here so the listing survives but never lies.
-	const piGids = identities.filter((i) => isLivenessSupported(i.backend)).map((i) => i.gardenId);
-	const scan = await scanSocketProbes(piGids, deps.socket ?? {});
+	const socketDomainGids = identities.filter((i) => isLivenessSupported(i.backend)).map((i) => i.gardenId);
+	const scan = await scanSocketProbes(socketDomainGids, deps.socket ?? {});
 	const probes = scan.probes;
 	const socketGids = new Set(probes.map((p) => p.gardenId));
 	const symlinkedGids = new Set(scan.symlinkedGardenIds);
@@ -158,24 +158,22 @@ export async function listEntwurfFacts(deps: EntwurfFactsDeps): Promise<EntwurfF
 		});
 	}
 
-	// 3. pre-quarantine non-pi citizens that collide with a control socket. The
-	//    predicate is SHARED with the v2 decider (isNonPiGardenIdSocketConflict) so
-	//    listing and dispatch cannot drift, and it unions socketGids with the
-	//    symlinkedGids: a symlinked socket is never probed (absent from socketGids),
-	//    so the old socketGids-only check let a non-pi citizen with a forged
-	//    (symlinked) socket survive as a clean PeerFact while the legacy send path
-	//    still followed the symlink — the gap this closes.
+	// 3. Pre-quarantine citizens outside the control-socket capability domain that
+	//    collide with a control socket. The predicate is SHARED with v2 dispatch so
+	//    listing and dispatch cannot drift. It unions real and symlinked socket gids:
+	//    the earlier real-socket-only check let an out-of-domain record survive as a
+	//    clean PeerFact beside a forged symlink receiver.
 	const conflictGids = new Set<string>();
 	for (const id of identities) {
-		if (isNonPiGardenIdSocketConflict(id.backend, id.gardenId, socketGids, symlinkedGids)) {
+		if (isOutOfSocketDomainGardenIdConflict(id.backend, id.gardenId, socketGids, symlinkedGids)) {
 			conflictGids.add(id.gardenId);
 			diagnostics.push({
 				kind: "garden-id-socket-conflict",
 				gardenId: id.gardenId,
 				backend: id.backend,
 				message:
-					`non-pi citizen (${id.backend}) shares its gardenId with a control socket (real or symlinked) — address ` +
-					"ambiguity; both the citizen and the socket are quarantined from the listing.",
+					`out-of-socket-domain citizen (${id.backend}) shares its gardenId with a control socket ` +
+					"(real or symlinked) — address ambiguity; both sides are quarantined from the listing.",
 			});
 		}
 	}

package/pi-extensions/lib/entwurf-facts.ts

@@ -75,27 +75,27 @@ export function resolvePeerFact(identity: MetaIdentity, socket: SocketLiveness |
 }
 
 /**
- * A non-pi RECORD whose gardenId collides with a control socket — a real (probed)
- * one OR a symlinked/forged one. The gardenId is the universal address (동결결정3),
- * so a non-pi citizen sharing it with a socket means a send-path that reaches the
- * socket first hits a DIFFERENT receiver than the record names — an address split.
+ * An OUT-OF-SOCKET-DOMAIN record whose gardenId collides with a control socket —
+ * a real (probed) one OR a symlinked/forged one. The gardenId is the universal
+ * address, so a citizen without socket capability sharing it with a socket means
+ * the socket reaches a DIFFERENT receiver than the record names — an address split.
  * Both the citizen and the socket are quarantined from the facts listing.
  *
  * The union `socketGids ∪ symlinkedGardenIds` is load-bearing: `socketGids` are
  * gids with a real probed `*.sock`, but `symlinkedGardenIds` are NEVER probed (P1)
  * and so are absent from `socketGids`. Looking at `socketGids` alone (the
- * fact-provider:125 gap this closes) let a non-pi citizen with a *symlinked* socket
+ * fact-provider:125 gap this closes) let an out-of-domain citizen with a *symlinked* socket
  * survive as a clean PeerFact while the legacy send path still followed the symlink
  * to a forged receiver. Both axes claim the gid → both must quarantine it.
  *
- * SCOPE: this is the RECORD-side, non-pi conflict only — shared by the fact-provider
- * (listing) and the v2 decider (dispatch) so the two cannot drift (4c "재유도 금지"
- * 동형; only the observation-bit source is parameterized). A pi citizen whose own
- * canonical socket is a symlink is NOT this predicate's concern — that is a
+ * SCOPE: this is the record-side, out-of-socket-domain conflict only — shared by
+ * listing and dispatch so they cannot drift; only the observation-bit source is
+ * parameterized. A citizen IN the socket domain whose own canonical socket is a
+ * symlink is NOT this predicate's concern — that is a
  * target-specific lstat conflict the decider's `inspectTargetControlSocket` raises
  * as `address-conflict`, kept deliberately separate (GPT 1차 검수 C).
  */
-export function isNonPiGardenIdSocketConflict(
+export function isOutOfSocketDomainGardenIdConflict(
 	backend: string,
 	gardenId: string,
 	socketGids: ReadonlySet<string>,
@@ -163,8 +163,8 @@ export interface FactList {
  *     `indeterminate` and strand a dormant citizen as un-resumable); a dormant
  *     citizen's absent socket file is probed to `dead` (ENOENT) by the wiring and
  *     arrives here AS `dead` → dormant → resumable.
- *   - out-of-domain citizen WITH a control socket at its gardenId → fail-loud
- *     (address ambiguity; a non-pi citizen must not own a pi control socket).
+ *   - out-of-socket-domain citizen WITH a control socket at its gardenId → fail-loud
+ *     (address ambiguity; a backend without socket capability cannot own that rail).
  *   - out-of-domain citizen without a socket → `unsupported` (via resolvePeerFact).
  *   - a probed gardenId with NO citizen → `RecordLessSocketFact` (#50 C4: a
  *     diagnostic subject the provider folds into a `record-less-socket`
@@ -202,7 +202,7 @@ export function resolveFactList(identities: MetaIdentity[], socketProbes: Socket
 			if (probeMap.has(gid)) {
 				throw new Error(
 					`resolveFactList: out-of-domain citizen ${gid} (${identity.backend}) has a control socket — ` +
-						"address ambiguity (a non-pi citizen must not own a pi control socket)",
+						"address ambiguity (an out-of-socket-domain citizen cannot own a control socket)",
 				);
 			}
 			socket = null;

package/pi-extensions/lib/entwurf-resume-args.ts

@@ -1,40 +1,40 @@
 /**
  * entwurf-resume-args — the SINGLE source of truth for the `pi` argv a resume spawn is
- * launched with (0.11 Stage 0 step 5c-3b). Two variants share this builder so the legacy
- * async-entwurf worker and the v2 spawn-bg resident citizen can NEVER drift in their launch
- * shape — the one place the `--no-extensions` / `--entwurf-control` decision lives.
+ * launched with (0.11 Stage 0 step 5c-3b). One place owns the
+ * `--no-extensions` / `--entwurf-control` decision so the launch shape cannot drift.
  *
- * The load-bearing difference (A1):
- *   - legacy — a one-shot async worker. `pi -p <prompt>` runs the resume turn and EXITS;
- *     `proc.on('close')` then delivers the followUp. It is launched `--no-extensions` AND
- *     WITHOUT `--entwurf-control` precisely BECAUSE a control-socket server would keep
- *     `pi -p` from exiting (entwurf.ts:22 — that keep-alive was a bug for a one-shot worker).
- *   - v2-control — a RESIDENT, addressable garden citizen. The resume turn STILL runs via
- *     `-p <prompt>` (the prompt-as-turn authority is unchanged), but the child is launched
- *     WITH `--entwurf-control` and WITHOUT `--no-extensions`, so the very keep-alive legacy
- *     avoided is now the GOAL: the resumed session stands its control socket up and stays
- *     live. The 5c-3a watcher's `socket-alive` is exactly that "resumed citizen is up and
- *     addressable" observation (→ release the per-gid lock, child lives on); `child-exited`
- *     is the early-exit/failure observation. `plan.launchArgs` (`--approve` or empty, from
- *     the decider's preflight) rides along as pi flags before the prompt.
+ * The shipped posture (A1): a RESIDENT, addressable garden citizen. The resume turn runs via
+ * `-p <prompt>` (the prompt-as-turn authority), and the child is launched WITH
+ * `--entwurf-control` and WITHOUT `--no-extensions` — the keep-alive is the GOAL here: the
+ * resumed session stands its control socket up and stays addressable. The 5c-3a watcher's
+ * `socket-alive` is exactly that "resumed citizen is up" observation (→ release the per-gid
+ * lock, child lives on); `child-exited` is the early-exit/failure observation.
+ * `plan.launchArgs` (`--approve` or empty, from the decider's preflight) rides along as pi
+ * flags before the prompt.
+ *
+ * A second `legacy` one-shot posture (`--no-extensions`, no control socket, so `pi -p` could
+ * exit) lived here until 2026-07-27 and was removed with its launcher and the v1 verbs.
  *
  * Provider/model identity is the caller's existing authority (readSessionIdentity /
  * getEntwurfExplicitExtensions) — this builder only LAYS OUT argv, it never resolves
- * identity. `explicitExtensionArgs` is preserved verbatim in BOTH variants: a recorded
- * `provider=entwurf` resume needs the bridge re-injected to resolve the provider, and
- * dropping it when `--no-extensions` is removed would re-introduce the "Unknown provider"
- * footgun (#29). (A future slice may dedup against settings-loaded extensions; not here.)
+ * identity. `explicitExtensionArgs` is preserved verbatim: a recorded `provider=entwurf`
+ * resume needs the bridge re-injected to resolve the provider, and dropping it would
+ * re-introduce the "Unknown provider" footgun (#29). (A future slice may dedup against
+ * settings-loaded extensions; not here.)
  *
- * This module is import-free on purpose: the legacy launcher (entwurf-async.ts) is
- * root-typechecked and imports it as `./entwurf-resume-args.js`, while the v2 adapter and
- * the gate import the same source — a self-contained string builder keeps both configs happy.
+ * This module is import-free on purpose: the v2 adapter and the gate import the same source,
+ * and a self-contained string builder keeps both tsconfigs happy.
  */
 
-export type ResumeArgsVariant = "legacy" | "v2-control";
+/** The one shipped launch posture: a resident citizen (`--entwurf-control`, extensions
+ * loaded). The `legacy` one-shot variant was removed with its launcher (2026-07-27) — an
+ * exported branch no product path took was what let this module's prose claim a second
+ * live consumer for months. Reviving a one-shot posture means adding it back deliberately,
+ * with a consumer, not un-deleting a dead enum member. */
+export type ResumeArgsVariant = "v2-control";
 
 export interface ResumePiArgsInput {
-	/** legacy = one-shot worker (`--no-extensions`, no control socket); v2-control =
-	 * resident citizen (`--entwurf-control`, extensions loaded). */
+	/** v2-control = resident citizen (`--entwurf-control`, extensions loaded). */
 	variant: ResumeArgsVariant;
 	/** ABSOLUTE path of the session JSONL to resume — pi's `--session <path>` (#50 C2).
 	 * It replaced `--session-id <gardenId>`, which did two jobs that are no longer the
@@ -46,7 +46,7 @@ export interface ResumePiArgsInput {
 	 * instead of resuming one. A path cannot do that. */
 	sessionFile: string;
 	/** The explicit `--extension …` re-injection (ACP bridge / provider resolution).
-	 * Preserved verbatim in BOTH variants — load-bearing for a entwurf resume. */
+	 * Preserved verbatim — load-bearing for a entwurf resume. */
 	explicitExtensionArgs: readonly string[];
 	/** Recorded provider (may be null/undefined — then no `--provider` flag is emitted). */
 	provider: string | null | undefined;
@@ -54,37 +54,31 @@ export interface ResumePiArgsInput {
 	model: string;
 	/** The resume prompt — the final positional, run as the model turn under `-p`. */
 	prompt: string;
-	/** v2-control ONLY: the decider's `plan.launchArgs` (`["--approve"]` or `[]`). Ignored
-	 * for legacy (the legacy path computes its own preflight elsewhere). */
+	/** The decider's `plan.launchArgs` (`["--approve"]` or `[]`). */
 	launchArgs?: readonly string[];
 }
 
 /**
- * Build the `pi` argv for a resume spawn. The SHARED prefix is `--mode json -p` (headless
- * JSON child, prompt-as-turn); the variant then chooses the extension/socket posture; the
- * SHARED suffix is `[…ext args] --session <file> [--provider <p>] --model <m> <prompt>`.
+ * Build the `pi` argv for a resume spawn. The prefix is `--mode json -p` (headless JSON
+ * child, prompt-as-turn); then the resident posture; then
+ * `[…ext args] --session <file> [--provider <p>] --model <m> <prompt>`.
  *
  * Invariants the gate pins:
- *   - legacy  carries `--no-extensions` and NO `--entwurf-control`.
  *   - v2-control carries `--entwurf-control` and NO `--no-extensions`, plus `-p` + prompt.
- *   - `explicitExtensionArgs` appears exactly once in both.
- *   - `launchArgs` is included for v2-control (before the suffix) and ignored for legacy.
- *   - provider/model/prompt identity is laid out identically in both.
+ *   - `explicitExtensionArgs` appears exactly once.
+ *   - `launchArgs` is included before the suffix.
+ *   - provider/model/prompt identity layout is fixed.
  */
 export function buildResumePiArgs(input: ResumePiArgsInput): string[] {
 	const args: string[] = ["--mode", "json", "-p"];
 
-	if (input.variant === "legacy") {
-		// One-shot worker: no extensions, no control socket (so `pi -p` can exit).
-		args.push("--no-extensions");
-	} else {
-		// Resident citizen: stand the control socket up (A1) and keep extensions loaded.
-		// The keep-alive legacy avoided is the goal here. `--approve`/launchArgs ride along.
-		args.push("--entwurf-control");
-		args.push(...(input.launchArgs ?? []));
-	}
+	// Resident citizen: stand the control socket up (A1) and keep extensions loaded. The
+	// keep-alive the removed one-shot launcher had to avoid is precisely the goal here —
+	// the resumed session must stay addressable. `--approve`/launchArgs ride along.
+	args.push("--entwurf-control");
+	args.push(...(input.launchArgs ?? []));
 
-	// Shared suffix — identical identity layout in both variants.
+	// Suffix — the fixed identity layout.
 	args.push(...input.explicitExtensionArgs);
 	args.push("--session", input.sessionFile);
 	if (input.provider) args.push("--provider", input.provider);

package/pi-extensions/lib/entwurf-self-address.ts

@@ -3,14 +3,13 @@
  *
  * "Can a reply to THIS session actually land where its model will see it?"
  *
- * Today both the MCP bridge (buildStrictPiSenderEnvelope /
- * buildTrustedMetaSenderEnvelope / entwurf_self) and pi-native answer that from env
- * presence alone and hardcode `replyable: true`: a pi session with no
- * --entwurf-control socket, or a meta citizen whose owner has exited / whose
- * idle-watch was never armed, all claim replyable while delivery silently fails
- * (SE-1: "all layers say yes, only delivery says no" = a Crash-Don't-Warn
- * violation). This module is the single truth-table both surfaces compute from,
- * with every fact INJECTED (no IO) so the gate can pin each row.
+ * This module closed the former split where the MCP and native pi surfaces inferred
+ * `replyable: true` from identity-carrier presence alone. Identity and reachability
+ * are separate: pi's env carries the garden id established by record birth, while
+ * replyability requires its control socket; a native marker must be record-backed,
+ * while replyability additionally requires its own rail's live facts. This is the
+ * single truth-table both surfaces compute from, with every fact INJECTED (no IO) so
+ * the gate can pin each row.
  *
  * Axes by origin:
  *  - pi-session:  replyable ⟺ a live control socket exists at the canonical path.
@@ -33,7 +32,7 @@
  *                 — which never arms a watch — would report replyable:false forever.
  *  - external-mcp: never replyable — no authoritative reply address.
  *
- * `origin` stays identity PROVENANCE (where the sender identity came from), never a rail.
+ * `origin` stays sender-carrier PROVENANCE, never the citizen identity authority and never a rail.
  * Which rail a meta citizen's reply rides is a SECOND axis — `metaDeliveryDomain`, derived
  * by the caller from `nativePushSupported(backend)`, not from `wakeMode` (direct-inject also
  * covers codex/pi, which have no native-push adapter). Fail-closed: an unsupplied domain is

package/pi-extensions/lib/entwurf-v2-contract-schema.ts

@@ -9,7 +9,12 @@
  * from the bridge boot closure would re-couple the harness-neutral meta-bridge to
  * pi (the `check-entwurf-bridge-pi-free` gate fails if it does). The bridge needs
  * the contract CONSTANTS + `resolveDispatch` (pi-free core), never these schemas.
- * Consumers: the pi MCP-tool param surface and `check-entwurf-v2-contract`.
+ * Consumer: `check-entwurf-v2-contract` ONLY. This is a gate-side REPRESENTATION of the
+ * frozen contract, not a shipped tool schema — measured 2026-07-27, nothing else in the
+ * import graph reaches it. The two surfaces a model actually reads build their own:
+ * `pi-extensions/entwurf-control.ts` (TypeBox `entwurfV2Parameters` + tool description) and
+ * `mcp/entwurf-bridge/src/index.ts` (Zod). Change a model-facing description THERE; changing
+ * it here reaches no model, and `check-entwurf-v2-surface` is what pins those two.
  *
  * StringEnum (typebox 1.x) inside Type.Object (typebox 0.34) — the same mix the
  * existing entwurf tools use. The logic types in the core are hand-written unions,
@@ -37,7 +42,7 @@ export const EntwurfV2InputSchema = Type.Object(
 		target: Type.String({
 			pattern: SESSION_ID_RE.source,
 			description:
-				"garden-id of an EXISTING citizen (pattern-enforced). spawn-new is out of v2 scope (legacy entwurf keeps it); a malformed/typo gid is bad-target.",
+				"garden-id of an EXISTING citizen (pattern-enforced). Fresh sibling creation is out of scope on every current surface — there is no fallback verb that still spawns. A malformed/typo gid is bad-target, never a new spawn.",
 		}),
 		intent: StringEnum(ENTWURF_INTENTS, {
 			description: