@junghanacs/entwurf 0.13.0 → 0.14.0

package/pi-extensions/entwurf-control.ts

@@ -25,14 +25,14 @@
  * - Register the canonical `entwurf_v2` dispatch tool for existing garden citizens.
  * - Expose `entwurf_peers` facts for operator inspection (#50 C4: the socket-scan
  *   `/entwurf-sessions` command is gone — the record listing is the only surface).
- * - Maintain the resident control socket used by v2 live-send / spawn-bg paths.
+ * - Maintain the resident control socket used by the v2 live-send path.
  * - Attach this pi session to its meta-record at session_start (#50 C2) and key
  *   the control socket on the record's gardenId.
  *
  * Send-is-throw still applies at the control-socket protocol layer: a `send` RPC
  * ack confirms the receiver enqueued the message (`message_processed` semantics)
  * and does not wait for a peer turn result. Public v1 send surfaces were removed;
- * callers use `entwurf_v2`, whose decider chooses send / spawn-bg / mailbox.
+ * callers use `entwurf_v2`, whose decider chooses control-socket send / mailbox / native-push.
  *
  * Usage:
  *   pi --entwurf-control      (no id injection: pi owns its id, the record owns
@@ -758,8 +758,9 @@ async function handleCommand(
 		// (entwurf-bridge entwurf_v2, the pi-native entwurf_v2 senderProvider via buildLocalSenderEnvelope)
 		// pass the envelope structurally and never touch the message body — the
 		// canonical XML-style payload is the shared formatSenderInfoBlock SSOT
-		// (#50 C3: the dormant spawn-resume rail appends the same block to its
-		// prompt, so both rails render one shape).
+		// (#50 C3: this is the ONE renderer since the visible-first cut removed the
+		// dormant spawn-resume rail that used to append the same block to a resume
+		// prompt — a future VISIBLE resume must render through it, not beside it).
 		const senderInfoBlock = sender ? formatSenderInfoBlock(sender, wantsReply) : "";
 
 		const mode = command.mode ?? "steer";
@@ -938,7 +939,8 @@ function updateStatus(ctx: ExtensionContext | null, enabled: boolean, gardenId:
 // is GONE with the id it mirrored. A name was a second place the address lived; the
 // record is the only one now, so there is nothing left to keep in sync and nothing
 // to crash over. (The dormant-resume authorization that leaned on the `entwurf` tag
-// moved to record existence — see entwurf-v2-spawn-production.)
+// moved to record existence, and that resume rail has since been withdrawn entirely;
+// the record-authoritative remainder lives in resume-launch-identity.ts.)
 
 function updateSessionEnv(ctx: ExtensionContext | null, enabled: boolean, gardenId: string | null): void {
 	if (!enabled || !gardenId) {
@@ -985,7 +987,7 @@ function getStringFlagFromArgv(flagName: string): string | undefined {
 }
 
 // `--emacs-agent-socket <name>` exports PI_EMACS_AGENT_SOCKET so this session's
-// own Bash/emacsclient calls (and any spawn-bg child that inherits this env)
+// own Bash/emacsclient calls (and any child process that inherits this env)
 // target the right Emacs server socket — e.g. `emacsclient -s "$PI_EMACS_AGENT_SOCKET"`.
 // v2-only revival: the original ACP path injected this into the ACP child's spawn
 // env (acp-bridge.ts); with no ACP child on this branch, the consumer IS this pi
@@ -1042,6 +1044,8 @@ export default function (pi: ExtensionAPI) {
 	if (shouldRegisterControlTools(pi)) {
 		registerListSessionsTool(pi);
 		registerEntwurfV2Tool(pi);
+		registerFreshCallTool(pi);
+		registerResumeCallTool(pi);
 	}
 
 	// The in-process mint refusals (`/new`, `/fork`, `/clone`, RPC new_session) are
@@ -1258,23 +1262,19 @@ interface EntwurfV2SurfaceModule {
 	runAndRenderEntwurfV2FromSurface(
 		params: {
 			target: string;
-			intent: "fire-and-forget" | "owned-outcome";
+			intent: "fire-and-forget";
 			mode?: "steer" | "follow_up";
 			wants_reply?: boolean;
 			message: string;
 		},
-		opts: {
-			senderProvider: () => SenderEnvelope | undefined;
-			agentDir?: string;
-			prefixRoots?: readonly string[];
-		},
+		opts: { senderProvider: () => SenderEnvelope | undefined },
 	): Promise<{ text: string; isError: boolean }>;
 }
 
 function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 	const entwurfV2Parameters = Type.Object({
 		target: Type.String({ description: "Target garden id (use entwurf_peers to discover)" }),
-		intent: StringEnum(["fire-and-forget", "owned-outcome"] as const, {
+		intent: StringEnum(["fire-and-forget"] as const, {
 			description:
 				"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 " +
@@ -1284,10 +1284,10 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 				"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",
+				"This is the ONLY intent. The second one, owned-outcome, resumed a dormant citizen by launching " +
+				"a hidden background child and was withdrawn under the visible-first rule; it is not selectable, " +
+				"not deprecated-but-tolerated, and a dormant citizen is currently unreachable by this verb and " +
+				"rejects as dormant-fire-forget-unsupported.",
 		}),
 		message: Type.String({
 			description:
@@ -1298,7 +1298,7 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 			StringEnum(["steer", "follow_up"] as const, {
 				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.",
+					"The mailbox and native-push 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)" })),
@@ -1306,7 +1306,7 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 
 	type EntwurfV2Params = {
 		target: string;
-		intent: "fire-and-forget" | "owned-outcome";
+		intent: "fire-and-forget";
 		message: string;
 		mode?: "steer" | "follow_up";
 		wants_reply?: boolean;
@@ -1322,55 +1322,26 @@ function registerEntwurfV2Tool(pi: ExtensionAPI): void {
 	registerTool({
 		name: "entwurf_v2",
 		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 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 / 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 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 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.`,
+		description: `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; it was withdrawn under the visible-first rule, so re-open the session
+yourself and 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.`,
 		parameters: entwurfV2Parameters,
 		async execute(
 			_toolCallId: string,
@@ -1410,8 +1381,10 @@ The decider — not this surface — chooses the transport.`,
 						mode: params.mode,
 						wants_reply: params.wants_reply,
 					},
-					// agentDir / prefixRoots intentionally omitted here: the surface adapter 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, so it left with `owned-outcome`. `senderProvider`
+					// is the whole options surface now — do NOT re-add an `ENTWURF_PREFIX_ROOTS` fallback
+					// here without a verdict that reads it (nothing on the dispatch path does).
 					{ senderProvider },
 				);
 				return {
@@ -1482,7 +1455,7 @@ function registerListSessionsTool(pi: ExtensionAPI): void {
 		name: "entwurf_peers",
 		label: "List Garden Citizens",
 		description:
-			"List the entwurf fact surface: garden citizens from meta-records (including active self-fetch meta receivers such as claude-code) with liveness, plus diagnostics. The record is the sole address axis (#50 C4) — a control socket no record claims surfaces as a record-less-socket diagnostic, never a peer row. Pair with entwurf_v2 to address a peer by garden id; this surface reports facts, never per-row routing verbs.",
+			"List the entwurf fact surface: garden citizens from meta-records (including active self-fetch meta receivers such as claude-code) with liveness, plus diagnostics. The record is the sole address axis (#50 C4) — a control socket no record claims surfaces as a record-less-socket diagnostic, never a peer row. Pair with entwurf_v2 to address a peer by garden id; this surface reports facts, never per-row routing verbs. 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. It is facts-only and creates nothing: to open a NEW sibling use entwurf_fresh_call.",
 		parameters: Type.Object({}),
 		async execute(
 			_toolCallId: string,
@@ -1507,3 +1480,179 @@ function registerListSessionsTool(pi: ExtensionAPI): void {
 		},
 	});
 }
+
+// ============================================================================
+// Tool: entwurf_fresh_call
+// ============================================================================
+
+const MUX_FRESH_CALL_MODULE = "./lib/mux-fresh-call.ts";
+
+interface MuxFreshCallModule {
+	freshCall(
+		params: { backend: "pi" | "claude-code"; model: string; task: string; callerGardenId: string | null },
+		env?: NodeJS.ProcessEnv,
+	): { ok: boolean };
+	renderFreshCall(result: { ok: boolean }): { text: string; isError: boolean };
+}
+
+/**
+ * The caller identity for this surface is the RESIDENT's garden address — the one the record
+ * minted at session start and keyed the control socket on. It is read from this extension's own
+ * closure, never from a tool parameter and never from `process.env`.
+ *
+ * A caller that could pass an id could pass a WRONG one, and that value would become the address
+ * the sibling calls back to — docs/mux-launch-rail.md §6-b keeps the measured incident. So there
+ * is no parameter to be wrong with.
+ *
+ * A null resident id refuses LOUDLY rather than falling back: without an address to call back to,
+ * the launch would be a window with no way home.
+ */
+function registerFreshCallTool(pi: ExtensionAPI): void {
+	// Same TS2589 workaround as registerEntwurfV2Tool — see the comment block there.
+	const registerTool = pi.registerTool as (def: any) => void;
+	registerTool({
+		name: "entwurf_fresh_call",
+		label: "Open Fresh Sibling",
+		description: `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 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.`,
+		parameters: Type.Object({
+			backend: StringEnum(["pi", "claude-code"], {
+				description: "Which fixed runtime to open. Only these two; there is no arbitrary command.",
+			}),
+			model: Type.String({
+				minLength: 1,
+				maxLength: 200,
+				pattern: "^[A-Za-z0-9][A-Za-z0-9._/:\\[\\]-]*$",
+				description: "Required runtime model: canonical provider/model for pi, or a Claude Code model id/alias.",
+			}),
+			task: Type.String({
+				minLength: 1,
+				maxLength: 16000,
+				description:
+					"What the sibling should do after it calls you back. Plain instructions; no secrets (see the tool description).",
+			}),
+		}),
+		async execute(
+			_toolCallId: string,
+			params: { backend: "pi" | "claude-code"; model: string; task: string },
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			_ctx: ExtensionContext,
+		) {
+			try {
+				const mux = (await import(MUX_FRESH_CALL_MODULE)) as unknown as MuxFreshCallModule;
+				const result = mux.freshCall({
+					backend: params.backend,
+					model: params.model,
+					task: params.task,
+					callerGardenId: residentGardenId,
+				});
+				const rendered = mux.renderFreshCall(result);
+				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_fresh_call error: ${msg}` }],
+					isError: true,
+					details: { error: msg },
+				};
+			}
+		},
+	});
+}
+
+// ============================================================================
+// Tool: entwurf_resume_call
+// ============================================================================
+
+const MUX_RESUME_CALL_MODULE = "./lib/mux-resume-call.ts";
+const V2_VISIBLE_RESUME_MODULE = "./lib/entwurf-v2-visible-resume.ts";
+
+interface MuxResumeCallModule {
+	resumeCall(
+		params: { cwd: string; runtimeArgs: readonly string[] },
+		env?: NodeJS.ProcessEnv,
+	): { ok: true; receipt: Record<string, string> } | { ok: false; reason: string };
+	RESUME_CALL_REJECT_HINT: Record<string, string>;
+}
+
+interface VisibleResumeModule {
+	visibleResume(target: string, deps: unknown): Promise<{ ok: boolean }>;
+	makeVisibleResumeDeps(launch: unknown): unknown;
+	renderVisibleResume(result: { ok: boolean }): { text: string; isError: boolean };
+}
+
+/**
+ * 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.
+ * What it needs instead is the per-gid lock, which is why the composition lives on the v2 side of
+ * the fence and only the LAUNCH is handed across (docs/mux-launch-rail.md §11).
+ */
+function registerResumeCallTool(pi: ExtensionAPI): void {
+	// Same TS2589 workaround as registerEntwurfV2Tool — see the comment block there.
+	const registerTool = pi.registerTool as (def: any) => void;
+	registerTool({
+		name: "entwurf_resume_call",
+		label: "Resume Dormant Citizen",
+		description: `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.`,
+		parameters: Type.Object({
+			target: Type.String({
+				minLength: 1,
+				pattern: "^\\d{8}T\\d{6}-[0-9a-f]{6}$",
+				description: "Garden id of the DORMANT pi citizen to reopen (discover with entwurf_peers).",
+			}),
+		}),
+		async execute(
+			_toolCallId: string,
+			params: { target: string },
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			_ctx: ExtensionContext,
+		) {
+			try {
+				const mux = (await import(MUX_RESUME_CALL_MODULE)) as unknown as MuxResumeCallModule;
+				const v2 = (await import(V2_VISIBLE_RESUME_MODULE)) as unknown as VisibleResumeModule;
+				const launch = (input: { cwd: string; runtimeArgs: readonly string[] }) => {
+					const launched = mux.resumeCall(input);
+					return launched.ok
+						? { ok: true, handle: launched.receipt }
+						: { ok: false, reason: launched.reason, hint: mux.RESUME_CALL_REJECT_HINT[launched.reason] };
+				};
+				const result = await v2.visibleResume(params.target, v2.makeVisibleResumeDeps(launch));
+				const rendered = v2.renderVisibleResume(result);
+				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_resume_call error: ${msg}` }],
+					isError: true,
+					details: { error: msg },
+				};
+			}
+		},
+	});
+}

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

@@ -26,6 +26,17 @@ export interface AcpConnectionLike {
 	newSession(params: unknown): Promise<{ sessionId?: string }>;
 	prompt(params: { sessionId: string; prompt: AcpTextBlock[] }): Promise<{ stopReason?: string }>;
 	setSessionConfigOption?(params: unknown): Promise<unknown>;
+	/**
+	 * ACP `session/cancel` — the PROTOCOL way to end an in-flight prompt turn.
+	 *
+	 * The spec requires the agent to answer the pending `session/prompt` with
+	 * `stopReason: "cancelled"` after this notification, so a user abort ends the
+	 * turn as a protocol event (backend.ts maps cancelled → aborted) instead of a
+	 * signal race. Fire-and-forget by contract: it is a JSON-RPC notification, so
+	 * there is nothing to await and a send failure on an already-closed connection
+	 * must not mask the abort the caller is executing.
+	 */
+	cancel?(params: { sessionId: string }): void;
 	/**
 	 * Closes the underlying SDK connection before child process teardown. With
 	 * the fluent SDK connection this is load-bearing: otherwise a successful
@@ -76,6 +87,17 @@ export function connectAcpClient(stream: Stream, handlers: AcpClientHandlers): A
 		prompt: (params) =>
 			agent.request(AGENT_METHODS.session_prompt, params as never) as Promise<{ stopReason?: string }>,
 		setSessionConfigOption: (params) => agent.request(AGENT_METHODS.session_set_config_option, params as never),
+		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 as never)).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/pi-extensions/lib/acp/augment.ts

@@ -36,10 +36,10 @@ import type { AcpTextBlock } from "./context.js";
 
 const MAX_AUGMENT_BYTES = 50 * 1024;
 
-// Carrier-less backends expose no `_meta.systemPrompt` (docs/acp-backend-rail.md
-// §9-4). claude folds the operator engraving into that carrier; a carrier-less
+// Carrier-less backends expose no `_meta.systemPrompt` (docs/acp-backend-rail.md,
+// “Cortex Code audit”). claude folds the operator engraving into that carrier; a carrier-less
 // backend (cortex, the first — precisely: SYSTEM-PROMPT-carrier-less, since
-// cortex does read `_meta` for an unpromoted caller-session-id seam, §11-8)
+// cortex does read `_meta` for an unpromoted caller-session-id seam)
 // has nowhere to put it — so its operator engraving
 // rides HERE, prepended as the LEADING section of the first-user augment. It
 // travels on the WIRE only (new-only, never the config signature), so an
@@ -48,6 +48,13 @@ const MAX_AUGMENT_BYTES = 50 * 1024;
 // carrier feeds bridgeConfigSignature.
 const CARRIER_LESS_BACKENDS: ReadonlySet<string> = new Set(["cortex"]);
 
+// The one sentence both rails owe the model: WHAT this block is and what it is
+// NOT. Shared so neither rail's frame can quietly lose it (and so the gate has a
+// single anchor to mutate). Everything after it is rail-specific, because the
+// rails really do differ — see the frame in buildPiContextAugment.
+const PROVENANCE_LEAD =
+	"This block is prepended to the FIRST USER MESSAGE of this session. It is not your system prompt.";
+
 // The env var an operator points at a personal engraving file. Shared surface
 // with the claude carrier (engraving.ts) BY NAME, but read INLINE here (not
 // imported): augment.ts is loaded raw by the strip-types carrier-augment gate,
@@ -116,6 +123,38 @@ export function buildPiContextAugment(params: PiContextAugmentParams): string {
 		if (engraving) sections.push(engraving);
 	}
 
+	// PROVENANCE FRAME — leads the bridge narrative, and it is not decoration.
+	//
+	// Measured 2026-07-30: asked where its instructions came from, the Claude ACP
+	// model asserted that the two paragraphs below were its system prompt. They
+	// are not — they are text prepended to its FIRST USER MESSAGE. Nothing in the
+	// block said otherwise, and a model has no other way to tell: on the wire a
+	// long first user message and a system prompt read the same. So the block now
+	// states its own provenance, per rail, because the rails genuinely differ
+	// (backend-adapter.ts: claude's buildSessionMeta carries `_meta.systemPrompt`,
+	// cortex's returns undefined so no `_meta` key is sent at all).
+	//
+	// Honest about scope: this makes the boundary STATEABLE, not enforced. It
+	// tells the model what it cannot otherwise observe; it does not stop a model
+	// from guessing anyway.
+	sections.push(
+		CARRIER_LESS_BACKENDS.has(params.backend)
+			? [
+					"# entwurf: where this text comes from",
+					"",
+					PROVENANCE_LEAD,
+					`The ${params.backend} rail carries no system-prompt carrier at all — entwurf sends no \`_meta.systemPrompt\`, so everything entwurf tells you, including any operator engraving above, arrives here as user-message text.`,
+					"If you are asked what your system prompt says, do not quote this block as one.",
+				].join("\n")
+			: [
+					"# entwurf: where this text comes from",
+					"",
+					PROVENANCE_LEAD,
+					`The ${params.backend} rail does have a system-prompt carrier (\`_meta.systemPrompt\`), and entwurf keeps it deliberately tiny: it carries the operator engraving only — never this narrative, never AGENTS.md.`,
+					"So: system prompt = the short engraving; everything below = first-user-message text. If you are asked what your system prompt says, do not quote this block as one.",
+				].join("\n"),
+	);
+
 	// Bridge identity + caller-side sibling stance. The closing line is a
 	// caller-perspective statement: when THIS session throws an entwurf, the peer
 	// on the other end is a sibling, not a worker.

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

@@ -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`.
@@ -217,7 +218,7 @@ function resolveClaudeLaunch(): AcpLaunchSpec {
 export const claudeAdapter: AcpBackendAdapter = {
 	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;
@@ -298,13 +299,13 @@ export const claudeAdapter: AcpBackendAdapter = {
  *  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: ReadonlySet<string> = new Set(SUPPORTED_CORTEX_MODEL_IDS);
 
-/** Cortex's OWN settings (§10 B): a Snowflake connection name, or null. Opaque to
+/** Cortex's OWN settings: a Snowflake connection name, or null. Opaque to
  *  config.ts / backend.ts — only cortexAdapter reads it (casting back). */
 export interface CortexAdapterSettings {
 	cortexConnection: string | null;
@@ -318,7 +319,7 @@ export const CORTEX_CONNECTION_ENV = "ENTWURF_ACP_CORTEX_CONNECTION";
 export const cortexAdapter: AcpBackendAdapter = {
 	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)) return undefined;
@@ -406,7 +407,7 @@ export const cortexAdapter: AcpBackendAdapter = {
 		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
@@ -438,7 +439,7 @@ export const cortexAdapter: AcpBackendAdapter = {
 		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) {
@@ -452,7 +453,7 @@ const ADAPTERS: readonly AcpBackendAdapter[] = [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).
  *
@@ -476,7 +477,7 @@ export function resolveAcpBackendAdapter(modelId: string): { adapter: AcpBackend
 }
 
 /** 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(): AcpModelRow[] {