@junghanacs/entwurf 0.40.0 → 0.41.0

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

@@ -31,16 +31,18 @@
  *                       seat, #105; nothing is ever created), optionally at ONE literal requested
  *                       cwd (cross-repo fresh, #73); 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.
+ *   - entwurf_resume_call — reopen ONE DORMANT pi or Claude Code citizen under its OWN garden id
+ *                       in a visible window; target-only, submits no prompt, LAUNCH and OBSERVATION
+ *                       receipts stay apart, the caller is attributed but grants nothing.
+ *   - entwurf_retire_call — one operator-requested target, one retirement attempt; actor is not
+ *                       permission, and action / append-record / lock-release receipts stay separate.
  *   - entwurf_callback — ZERO-ARGUMENT fresh-sibling callback. Reads ENTWURF_CALLBACK_TARGET +
  *                       ENTWURF_CALLBACK_NONCE from this process env (launcher-injected), validates
  *                       grammar, and dispatches through the existing v2 runner. Refuses by name
  *                       when env is absent/malformed or this process is a Codex-provenance bridge.
  *                       No model-supplied target fallback.
  *
- * That list is the WHOLE public surface — eight verbs — and `check-entwurf-bridge-boot`
+ * That list is the WHOLE public surface — nine 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.
  *
@@ -78,6 +80,8 @@ import { ENTWURF_PEERS_RENDER_LIMIT, renderEntwurfPeers } from "../../../pi-exte
 import { computeSelfAddressability, type MetaDeliveryDomain } from "../../../pi-extensions/lib/entwurf-self-address.ts";
 import { nativePushSupported } from "../../../pi-extensions/lib/entwurf-v2-contract.ts";
 import { resolveMailboxWakeModeCapability } from "../../../pi-extensions/lib/entwurf-v2-decider.ts";
+import { retireCitizen } from "../../../pi-extensions/lib/entwurf-v2-retire.ts";
+import { makeProductionRetireDeps } from "../../../pi-extensions/lib/entwurf-v2-retire-production.ts";
 import { runAndRenderEntwurfV2FromSurface } from "../../../pi-extensions/lib/entwurf-v2-surface.ts";
 import {
 	makeVisibleResumeDeps,
@@ -818,7 +822,7 @@ server.tool(
 			// 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, provider/<exact catalog model id> for pi-durable, a Claude Code model id/alias, or a Copilot/OMP/Codex model name.",
+				"Required runtime model: canonical provider/model for pi (a bare alias is refused), provider/<exact catalog model id> for pi-durable, a Claude Code model id/alias, or a Copilot/OMP/Codex model name. Neither pi nor pi-durable may name the openrouter provider.",
 			),
 		task: z
 			.string()
@@ -904,7 +908,7 @@ server.tool(
 // 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: VisibleResumeDeps["launch"] = (input) => {
-	const launched = resumeCall({ cwd: input.cwd, runtimeArgs: input.runtimeArgs });
+	const launched = resumeCall({ backend: input.backend, 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] };
@@ -912,27 +916,45 @@ const visibleResumeLaunch: VisibleResumeDeps["launch"] = (input) => {
 
 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.",
+	"Reopen ONE DORMANT pi or Claude Code citizen under its OWN garden id, in a visible window in the operator's " +
+		"own tmux session. The record supplies everything — which session, which cwd, and for pi which transcript, " +
+		"model and provider — so the only input is the target id: there is no model override, no task, and no " +
+		"prompt, and a Claude Code session comes back as `claude --resume <its session id>` with none of the model " +
+		"or permission flags it was once started with. This verb submits NO prompt; what the runtime itself does " +
+		"after it comes back (for Claude Code, its hook re-arms the doorbell and unread mail may then wake a turn) " +
+		"is not measured, and talking to it is still entwurf_v2 fire-and-forget. You get TWO receipts and they mean " +
+		"different things: a LAUNCH receipt (tmux made a window and was asked to start the runtime) and an " +
+		"OBSERVATION receipt (pi: the control socket answered under the same id; Claude Code: a NEW live process in " +
+		"the window this call opened re-armed its receiver marker for the same session with a fresh arm binding the " +
+		"record also carries; or resume-unobserved; or record-unreadable with its cause). 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. A Claude Code citizen is reopened only when the last validated " +
+		"owner the Entwurf hook armed for its session is proven gone AND that arm is still the record's last one; " +
+		"no marker, an unreadable or mismatched one, an inconclusive owner or an unbound one is refused, and a " +
+		"process holding the session without a committed hook attach is invisible to that proof. Other backends " +
+		"have no same-id resume. Requires that this agent itself runs inside tmux (inside herdr it is refused).",
 	{
 		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)."),
+			.describe("Garden id of the DORMANT pi or Claude Code citizen to reopen (discover with entwurf_peers)."),
 	},
-	async ({ target }) => {
+	async ({ target }, extra) => {
+		// Who asked, from the same authoritative caller identity fresh_call reads. Attribution only:
+		// an anonymous caller is reported as unattributed, never refused, and a record-backed one is
+		// granted nothing the target's record and live facts do not already decide.
+		let actor: string | null = null;
+		try {
+			actor = (await buildAuthoritativeSelfEnvelope({ requestMeta: extra._meta })).envelope.sessionId;
+		} catch (err) {
+			if (!(err instanceof EntwurfEnvelopeWiringError)) {
+				return textErr(`entwurf_resume_call error: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}
 		try {
 			const result = await visibleResume(target, makeVisibleResumeDeps(visibleResumeLaunch));
-			const rendered = renderVisibleResume(result);
+			const rendered = renderVisibleResume(result, { actor });
 			return rendered.isError ? textErr(rendered.text) : textOk(rendered.text);
 		} catch (err) {
 			return textErr(`entwurf_resume_call error: ${err instanceof Error ? err.message : String(err)}`);
@@ -940,6 +962,58 @@ server.tool(
 	},
 );
 
+server.tool(
+	"entwurf_retire_call",
+	"Only when the human operator explicitly requested this particular target/work: make ONE retirement attempt for that request. " +
+		"Development work, a role or a record-backed actor is NOT a grant. Use host approval where provided/configured; " +
+		"Pi and pi-durable have no built-in per-call approval prompt by default. An explicit operator request and " +
+		"agent operating policy are required; attribution and MCP annotations are hints, not grants or proof of approval. " +
+		"Never use for autonomous cleanup or timers. Never automatically retry an unknown, cancelled or lost result. " +
+		"Target must be an existing Pi or Claude Code garden id; self retirement refuses. Pi shutdown-requested is " +
+		"only an ACK, not process exit, flush or model silence. Claude Code exited means that fd-pinned process only, " +
+		"not conversation end, children or flush. Do not manually /resume or /clear the target during the request. " +
+		"The JSON receipt preserves outcome, record and release separately; returning a receipt does not mean the " +
+		"target exited. Cancellation can suppress the wire response without undoing an action. For plural explicit " +
+		"requests, invoke once for each named target; never infer a roster or expand the request.",
+	{
+		target: z
+			.string()
+			.min(1)
+			.regex(/^\d{8}T\d{6}-[0-9a-f]{6}$/)
+			.describe("Exact garden id of the Pi or Claude Code target the human operator explicitly requested to retire."),
+	},
+	{ readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+	async ({ target }, extra) => {
+		try {
+			const receipt = await retireCitizen(
+				target,
+				makeProductionRetireDeps({
+					resolveCaller: async () => (await resolveAuthoritativeSender({ requestMeta: extra._meta }))?.envelope ?? null,
+					signal: extra.signal,
+				}),
+			);
+			// isError reports uncertainty/faults, NOT a common Pi-ACK/CC-exit success boundary.
+			// Named refusals are completed decisions. Always preserve the full three-axis JSON.
+			const outcome = receipt.outcome;
+			const uncertain =
+				outcome.kind === "unknown" ||
+				outcome.kind === "preflight-error" ||
+				(outcome.kind === "pi" && outcome.result.boundary === "unknown") ||
+				(outcome.kind === "claude-code" && outcome.result.outcome === "unknown");
+			const recordFault =
+				receipt.record.status === "requested-append-error" || receipt.record.status === "outcome-append-error";
+			const releaseFault = receipt.release.status !== "released" && receipt.release.status !== "not-acquired";
+			const json = JSON.stringify(receipt);
+			return uncertain || recordFault || releaseFault ? textErr(json) : textOk(json);
+		} catch (err) {
+			return textErr(
+				`entwurf_retire_call error: ${err instanceof Error ? err.message : String(err)}. ` +
+					"The outcome may be unknown; this does not prove no action. Do not automatically retry.",
+			);
+		}
+	},
+);
+
 server.tool(
 	"entwurf_callback",
 	"ZERO-ARGUMENT callback for a fresh sibling this process was launched as. Reads " +

package/mcp/entwurf-bridge/test.sh

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

package/mcp/entwurf-bridge/tsconfig.build.json

@@ -147,6 +147,12 @@
 	// remote-pair-send, entwurf-v2-surface, meta-session) are ALREADY emitted for the bridge's own
 	// entwurf_v2 handler, so this adds ONE leaf JS and ZERO new deps. It is never in index.ts's boot
 	// closure.
+	// WHY cc-retire-request rides THIS build (#147 G3): the core-side Claude Code retire adapter
+	// must run from the compiled bridge as well as from source. It was first supplied as a private
+	// entry; the #147 public retirement factory now reaches it too. Keep the named entry for the
+	// standalone compiled adapter consumer proof. Its helper is not TS: the
+	// build script byte-copies pi-extensions/lib/cc-retire-pidfd.py beside the emitted adapter.
+	// Its repo imports (meta-session, entwurf-v2-visible-resume) are ALREADY emitted for the bridge.
 	"include": [
 		"./src/index.ts",
 		"../../protocol.js",
@@ -168,6 +174,9 @@
 		"../../pi-extensions/meta-bridge-hook-codex.ts",
 		"../../pi-extensions/meta-bridge-omp.ts",
 		"../../pi-extensions/meta-bridge-receive-omp.ts",
-		"../../pi-extensions/meta-bridge-pi-durable.ts"
+		"../../pi-extensions/meta-bridge-pi-durable.ts",
+		"../../pi-extensions/lib/cc-retire-request.ts",
+		// Keep the standalone Pi adapter consumer entry; the public factory also reaches it now.
+		"../../pi-extensions/lib/pi-retire-request.ts"
 	]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.40.0",
-	"description": "Visible sibling sessions across independent agent harnesses: launch in Herdr or tmux, reopen pi in tmux, and deliver messages by garden id; native bridges and Claude/Cortex ACP adapters.",
+	"version": "0.41.0",
+	"description": "Visible sibling sessions across independent agent harnesses: launch in Herdr or tmux, retire on request and reopen pi or Claude Code in tmux, and deliver messages by garden id; native bridges and Claude/Cortex ACP adapters.",
 	"license": "MIT",
 	"author": {
 		"name": "Junghan Kim",
@@ -95,7 +95,7 @@
 		"node": ">=24.0.0"
 	},
 	"entwurf": {
-		"claudeCodeFloor": ">=2.1.217"
+		"claudeCodeFloor": ">=2.1.306"
 	},
 	"dependencies": {
 		"@agentclientprotocol/claude-agent-acp": "0.90.0",
@@ -196,7 +196,7 @@
 		"check:core": "pnpm run check:toolchain && pnpm run check:vitest && pnpm run check:contracts",
 		"check:toolchain": "pnpm lint && pnpm typecheck",
 		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-pi-queue-oracle && ./run.sh check-tests-beside-behavior && ./run.sh check-remote-pair-installed-audit",
-		"check:contracts": "./run.sh check-demo-reproducibility && ./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-runner && ./run.sh check-control-send-receipt && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-win32-preview && ./run.sh check-pack-win32-carrier && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-acp-foreground-only && ./run.sh check-acp-set-model-readback && ./run.sh check-acp-vendor-rejection && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push && ./run.sh check-pi-durable-beside && ./run.sh check-pi-durable-carrier && ./run.sh check-pi-durable-native-module",
+		"check:contracts": "./run.sh check-demo-reproducibility && ./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-runner && ./run.sh check-control-send-receipt && ./run.sh check-control-retire && ./run.sh check-pi-retire-request && ./run.sh check-cc-retire-pidfd && ./run.sh check-cc-retire-request && ./run.sh check-retirement-event && ./run.sh check-entwurf-v2-retire && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-win32-preview && ./run.sh check-pack-win32-carrier && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-fresh-call-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-acp-foreground-only && ./run.sh check-acp-set-model-readback && ./run.sh check-acp-vendor-rejection && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push && ./run.sh check-pi-durable-beside && ./run.sh check-pi-durable-carrier && ./run.sh check-pi-durable-native-module",
 		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-meta-hook-session-switch && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-pi-launch && ./run.sh check-codex-app-server-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-birth-hook && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-peer-facts && ./run.sh check-herdr-plugin && ./run.sh check-herdr-plugin-profile && ./run.sh check-herdr-plugin-build && ./run.sh check-herdr-runtime-bootstrap && ./run.sh check-herdr-activation && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-usage-accounting && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-typing-call-fence && ./run.sh check-gate-manifests && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex && ./run.sh check-codex-bridge-identity && ./run.sh check-pi-bridge-sender && ./run.sh check-pi-mcp-register && ./run.sh check-pi-mcp-bridge && ./run.sh check-codex-birth-hook && ./run.sh smoke-codex-config-state && ./run.sh smoke-codex-birth && ./run.sh check-herdr-sandbox",
 		"check:package": "./run.sh check-install-surface && ./run.sh smoke-meta-install-state && ./run.sh smoke-agy-install-state && ./run.sh smoke-setup-verdict && ./run.sh check-pack-pin-matcher && ./run.sh check-pack-consumer-roots && ./run.sh check-package-source-routing && ./run.sh check-install-preflight && ./run.sh check-pack"
 	},

package/pi/meta-bridge/entwurf-meta-receive/scripts/hook-launch.sh

@@ -3,7 +3,7 @@
 #
 # WHY THIS EXISTS (measured, #51 B/B2, 2026-07-22 — not inferred)
 #
-# Claude Code >= 2.1.217 supports the shell-less EXEC form: `command` is the
+# Claude Code 2.1.217 and later support the shell-less EXEC form: `command` is the
 # executable and `args` is argv, each element substituted as a plain string, with
 # no shell anywhere on the path. Measured at 2.1.217: a hook declared that way
 # receives every `args` element verbatim (a literal `${HOME}` arrives LITERAL —
@@ -47,8 +47,8 @@ if [ "$#" -eq 0 ]; then
 		still reports the hook as `exit_code: 0, outcome: success` (measured on 2.1.138),
 		so nothing upstream will ever tell you.
 
-		entwurf supports Claude Code >= 2.1.217 — the version whose runtime behavior was
-		actually verified end to end. There is no shell-form fallback.
+		entwurf supports Claude Code >= 2.1.306 (the exec form was verified end to end at
+		2.1.217; same-id resume needs the newer CLI). There is no shell-form fallback.
 
 		Fix: update Claude Code, then re-run
 		    ./run.sh install-meta-bridge && ./run.sh doctor-meta-bridge

package/pi-extensions/entwurf-control.ts

@@ -59,6 +59,7 @@
  *   - { type: "get_info" }
  *   - { type: "clear", summarize?: boolean }
  *   - { type: "abort" }
+ *   - { type: "retire", gardenId: "...", nativeSessionId: "..." } (internal, idle TUI only)
  *   Responses are JSON objects with { type: "response", command, success, data?, error? }
  *   (No event channel — the turn_end subscribe surface was removed with the
  *    Send-is-throw cleanup; see note above.)
@@ -79,6 +80,16 @@ import {
 	noteCompactionBefore,
 	noteCompactionTerminal,
 } from "./lib/compaction-send-guard.js";
+import {
+	acceptControlConnection,
+	type ControlBinding,
+	closeControlConnections,
+	endRetireResponse,
+	invalidateControlBinding,
+	requestControlRetire,
+	retireResponseEnvelope,
+	startOrRebindControlServer,
+} from "./lib/control-retire.js";
 import { sendReceiptBoundary } from "./lib/control-send-receipt.js";
 import { CONTROL_SOCKET_SUFFIX, defaultControlSocketDir } from "./lib/control-socket-path.js";
 import {
@@ -121,6 +132,10 @@ interface SocketState {
 	server: net.Server | null;
 	socketPath: string | null;
 	context: ExtensionContext | null;
+	binding: ControlBinding | null;
+	closing: boolean;
+	retireRequested: boolean;
+	connections: Set<net.Socket>;
 	compaction: CompactionGuard;
 }
 
@@ -485,12 +500,27 @@ async function handleCommand(
 	state: SocketState,
 	command: RpcCommand,
 	socket: net.Socket,
+	serverBinding: ControlBinding | null,
 ): Promise<void> {
 	const id = "id" in command && typeof command.id === "string" ? command.id : undefined;
 	const respond = (success: boolean, commandName: string, data?: unknown, error?: string) => {
 		writeResponse(socket, { type: "response", command: commandName, success, data, error, id });
 	};
 
+	// The public core checks caller/self, freshness and target admission, not an operator grant.
+	// Attribution is not authorization: an explicit operator request and agent operating policy
+	// are required; use host approval where provided/configured. No async gap exists between
+	// the receiver's final same-session checks and the SDK void call.
+	if (command.type === "retire") {
+		const result = requestControlRetire(state, serverBinding, residentGardenId, command);
+		endRetireResponse(socket, retireResponseEnvelope(result, id));
+		return;
+	}
+
+	if (state.closing || state.retireRequested) {
+		respond(false, command.type, undefined, "target-closing");
+		return;
+	}
 	const ctx = state.context;
 	if (!ctx) {
 		respond(false, command.type, undefined, "Session not ready");
@@ -690,6 +720,7 @@ async function handleCommand(
 
 async function createServer(pi: ExtensionAPI, state: SocketState, socketPath: string): Promise<net.Server> {
 	const server = net.createServer((socket) => {
+		const serverBinding = acceptControlConnection(state, socket);
 		// FIRST — before setEncoding, before the data handler, and before any response can be
 		// written back. The policy itself (and why this process died without it) lives with the
 		// rest of the wire protocol in lib/entwurf-control-rpc.ts.
@@ -729,7 +760,7 @@ async function createServer(pi: ExtensionAPI, state: SocketState, socketPath: st
 				// here would serialize subsequent commands on the same socket and
 				// tangle teardown ordering during socket close.
 				const commandName = parsed.command?.type ?? "unknown";
-				void handleCommand(pi, state, parsed.command!, socket).catch((error) => {
+				void handleCommand(pi, state, parsed.command!, socket, serverBinding).catch((error) => {
 					const message = error instanceof Error ? error.message : String(error);
 					writeResponse(socket, {
 						type: "response",
@@ -762,24 +793,21 @@ async function startControlServer(
 	state: SocketState,
 	ctx: ExtensionContext,
 	socketPath: string,
+	gardenId: string,
 ): Promise<void> {
-	await ensureControlDir();
-	await gcStaleSockets();
-
-	if (state.socketPath === socketPath && state.server) {
-		state.context = ctx;
-		return;
-	}
-
-	await stopControlServer(state);
-	await removeSocket(socketPath);
-
-	state.context = ctx;
-	state.socketPath = socketPath;
-	state.server = await createServer(pi, state, socketPath);
+	await startOrRebindControlServer(state, ctx, socketPath, gardenId, {
+		prepare: async () => {
+			await ensureControlDir();
+			await gcStaleSockets();
+		},
+		stop: () => stopControlServer(state),
+		remove: removeSocket,
+		create: (address) => createServer(pi, state, address),
+	});
 }
 
 async function stopControlServer(state: SocketState): Promise<void> {
+	invalidateControlBinding(state);
 	if (!state.server) {
 		await removeSocket(state.socketPath);
 		state.socketPath = null;
@@ -788,7 +816,7 @@ async function stopControlServer(state: SocketState): Promise<void> {
 
 	const socketPath = state.socketPath;
 	state.socketPath = null;
-	await new Promise<void>((resolve) => state.server?.close(() => resolve()));
+	await closeControlConnections(state.server, state.connections);
 	state.server = null;
 	await removeSocket(socketPath);
 }
@@ -958,6 +986,11 @@ export default function (pi: ExtensionAPI) {
 		server: null,
 		socketPath: null,
 		context: null,
+		binding: null,
+		// Before session_start, commands refuse target-closing rather than Session not ready.
+		closing: true,
+		retireRequested: false,
+		connections: new Set(),
 		compaction: createCompactionGuard(),
 	};
 
@@ -1022,7 +1055,7 @@ export default function (pi: ExtensionAPI) {
 		// naming the fresh-cut command, control server refused. There is no mixed
 		// store to warn about; the store is either clean or this session has no
 		// address.
-		await startControlServer(pi, state, ctx, birth.socketPath);
+		await startControlServer(pi, state, ctx, birth.socketPath, birth.gardenId);
 		// Identity before UI (#125): the carrier env and the MCP registration that carries the
 		// born gardenId are both made before any status rendering, so a visual failure can never
 		// leave a born citizen without its identity carrier or its verbs.
@@ -1082,10 +1115,12 @@ export default function (pi: ExtensionAPI) {
 	// simply rebinds to the new address. There is no id to police at the pre-event.
 
 	pi.on("session_shutdown", async () => {
-		noteCompactionTerminal(state.compaction);
-		updateStatus(state.context, false, null);
-		updateSessionEnv(state.context, false, null);
+		const previousContext = state.context;
+		invalidateControlBinding(state);
 		residentGardenId = null;
+		noteCompactionTerminal(state.compaction);
+		updateStatus(previousContext, false, null);
+		updateSessionEnv(previousContext, false, null);
 		await stopControlServer(state);
 	});