@junghanacs/entwurf 0.12.0

package/pi-extensions/lib/entwurf-v2-runner.ts

@@ -0,0 +1,196 @@
+/**
+ * entwurf-v2-runner — the pure EXECUTE-router (5d-1, `executeDispatch`) AND the top-level
+ * decide→execute join (5d-2a, `runEntwurfV2`) for the unified `entwurf_v2` verb, both in
+ * this one file because they share the `EntwurfV2RunResult` vocabulary and neither does IO.
+ * `executeDispatch` takes a `DispatchDecision` the 5b decider ALREADY produced and routes it
+ * to the right 5c transport hand, returning ONE outcome-rich `EntwurfV2RunResult`. It performs
+ * ZERO IO of its own and makes ZERO routing decisions — `decideDispatch` chose the plan,
+ * this only DISPATCHES it. Each hand is an injected dep (the gate fakes them; 5d-2 wires
+ * the production `executeControlSocketSend` / `executeSpawnBgResume` / production
+ * `sendViaMailbox`), so the routing + result mapping is gate-provable without a socket,
+ * spawn, or timer — the same pure-before-IO, IO-via-dep discipline 5b/5c kept.
+ *
+ * Why a result type richer than the receipt: the carry-over contracts from 5c demand it.
+ *   - N3 (5c-2b): a dead-path re-resolve `rejected` carries the resolver's `rejectReason`
+ *     (dormant-fire-forget-unsupported / mailbox-undeliverable / …). The runner carries it
+ *     verbatim so the surface distinguishes "in-band refusal" from "no live route".
+ *   - N1 (5c-2a): a non-`failed` outcome whose `releaseLock` then threw is a
+ *     `SendDeliveredReleaseFailedError` — the delivery HAPPENED, the lock is dirty, a
+ *     re-send would double-deliver. The runner surfaces this as `execution-failed` with
+ *     `finalizedOutcome` + `releaseFailed` so the surface renders "delivered, lock dirty,
+ *     do NOT retry", never "send failed".
+ *   - spawn-bg `lock-retained` is a RETURNED result (fail-closed, not a throw): it rides
+ *     the `executed` branch so 5d's surface can render the retained-lock diagnostic.
+ *
+ * `retrySafe` is conservatively `false` on EVERY `execution-failed`: a thrown send is
+ * never confidently retry-safe (an `indeterminate` connect may have delivered to an
+ * alive-but-stalled socket — the exact double-delivery hazard 5c-2a refuses to gamble on).
+ * The runner never re-judges the lock — it passes `decision.lock` to the hand verbatim and
+ * lets the hand's `decideReleasePolicy` fail loud on a mis-pairing.
+ */
+
+import type {
+	DispatchDecision,
+	DispatchInput,
+	ExecutionPlan,
+	RejectDiagnostic,
+	RejectReceipt,
+	SuccessReceipt,
+} from "./entwurf-v2-decider.ts";
+import type { LockClaim } from "./entwurf-v2-lock.ts";
+import {
+	type ControlSocketPlan,
+	type ControlSocketSendResult,
+	type MetaMailboxPlan,
+	type RpcSendResult,
+	SendDeliveredReleaseFailedError,
+	type SendFinalOutcome,
+} from "./entwurf-v2-send.ts";
+import type { SpawnBgPlan, SpawnBgResumeResult } from "./entwurf-v2-spawn.ts";
+
+/**
+ * The three transport hands, each PRE-BOUND with its own deps (production or fake). Lock
+ * is typed `LockClaim | null` to mirror the real hands EXACTLY — the runner passes
+ * `decision.lock` straight through and the hand fails loud on a null/mis-paired lock
+ * (control-socket / spawn-bg get a non-null claim; meta-mailbox gets null — ？7).
+ */
+export interface DispatchExecutorDeps {
+	sendControl: (plan: ControlSocketPlan, lock: LockClaim | null) => Promise<ControlSocketSendResult>;
+	resumeSpawnBg: (plan: SpawnBgPlan, lock: LockClaim | null) => Promise<SpawnBgResumeResult>;
+	sendMailbox: (plan: MetaMailboxPlan, lock: LockClaim | null) => Promise<RpcSendResult>;
+}
+
+/** The per-transport success outcome, discriminated by transport so the surface renders
+ * each without guessing. `control-socket` carries the optional N3 `rejectReason`;
+ * `spawn-bg` carries the whole `SpawnBgResumeResult` (incl. the `lock-retained`
+ * fail-closed diagnostic); `meta-mailbox` is always `success:true` (enqueue has no
+ * in-band refuse — a failure is a throw, handled as `execution-failed`). */
+export type ExecutedOutcome =
+	| { transport: "control-socket"; outcome: SendFinalOutcome; rejectReason?: string }
+	| { transport: "spawn-bg"; result: SpawnBgResumeResult }
+	| { transport: "meta-mailbox"; success: true };
+
+/** The single outcome-rich result the 5d surface renders. `rejected` = the decider
+ * refused (no execution). `executed` = a hand ran to a terminal result. `execution-failed`
+ * = a hand THREW (the lock-leak backstop / a transport failure / the N1 delivered+release
+ * failed error) — `finalizedOutcome`+`releaseFailed` mark the N1 "delivered, do not retry"
+ * case; `retrySafe` is always false (see module header). */
+export type EntwurfV2RunResult =
+	| { kind: "rejected"; receipt: RejectReceipt; diagnostic?: RejectDiagnostic }
+	| { kind: "executed"; receipt: SuccessReceipt; transport: ExecutionPlan["transport"]; outcome: ExecutedOutcome }
+	| {
+			kind: "execution-failed";
+			receipt: SuccessReceipt;
+			transport: ExecutionPlan["transport"];
+			error: string;
+			/** Present ONLY for the N1 case: the delivery/refusal reached a terminal outcome
+			 * but `releaseLock` then threw (lock dirty). A re-send would double-deliver. */
+			finalizedOutcome?: Exclude<SendFinalOutcome, "failed">;
+			releaseFailed?: true;
+			retrySafe: false;
+	  };
+
+function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Route an already-decided `DispatchDecision` to its transport hand. The decider owns the
+ * routing; this owns ONLY the dispatch + the outcome→result mapping (incl. the N1/N3
+ * carry-overs). A `reject` runs no hand. An `execute` switches on `plan.transport`.
+ */
+export async function executeDispatch(
+	decision: DispatchDecision,
+	deps: DispatchExecutorDeps,
+): Promise<EntwurfV2RunResult> {
+	if (decision.kind === "reject") {
+		return { kind: "rejected", receipt: decision.receipt, diagnostic: decision.diagnostic };
+	}
+
+	const { receipt, plan, lock } = decision;
+	const transport = plan.transport;
+
+	switch (plan.transport) {
+		case "control-socket": {
+			try {
+				const r = await deps.sendControl(plan, lock);
+				return {
+					kind: "executed",
+					receipt,
+					transport,
+					outcome: { transport: "control-socket", outcome: r.outcome, rejectReason: r.rejectReason },
+				};
+			} catch (err) {
+				// N1: a delivered/refused send whose release then threw — lock dirty, do NOT retry.
+				if (err instanceof SendDeliveredReleaseFailedError) {
+					return {
+						kind: "execution-failed",
+						receipt,
+						transport,
+						error: errorMessage(err),
+						finalizedOutcome: err.finalizedOutcome,
+						releaseFailed: true,
+						retrySafe: false,
+					};
+				}
+				// A `failed` send rethrows its original transport error (lock already released).
+				return { kind: "execution-failed", receipt, transport, error: errorMessage(err), retrySafe: false };
+			}
+		}
+		case "spawn-bg": {
+			try {
+				// `lock-retained` is a RETURNED result (fail-closed), not a throw — it rides `executed`.
+				const result = await deps.resumeSpawnBg(plan, lock);
+				return { kind: "executed", receipt, transport, outcome: { transport: "spawn-bg", result } };
+			} catch (err) {
+				return { kind: "execution-failed", receipt, transport, error: errorMessage(err), retrySafe: false };
+			}
+		}
+		case "meta-mailbox": {
+			try {
+				// lock is null here (？7) — passed verbatim; the production adapter ignores it.
+				const r = await deps.sendMailbox(plan, lock);
+				// 5c-4 contract: a mailbox enqueue is `{success:true}` OR a throw — there is NO
+				// in-band reject (no live receiver to refuse). A `success:false` is therefore a
+				// CONTRACT VIOLATION, not a soft failure: fail loud rather than silently render it
+				// as a success ("Never warn. Throw."). The catch below folds it to execution-failed.
+				if (r.success !== true) {
+					throw new Error(
+						"entwurf-v2-runner: meta-mailbox send returned success:false (contract violation; a mailbox has no in-band reject).",
+					);
+				}
+				return { kind: "executed", receipt, transport, outcome: { transport: "meta-mailbox", success: true } };
+			} catch (err) {
+				return { kind: "execution-failed", receipt, transport, error: errorMessage(err), retrySafe: false };
+			}
+		}
+	}
+}
+
+/**
+ * 5d-2a: the deps `runEntwurfV2` joins. `decide` is the WHOLE decider as ONE injected
+ * function — NOT `DispatchDeciderDeps`. The runner does not re-validate the 5b decider
+ * logic (that is `check-entwurf-v2-decider`'s job); it proves only the decide→execute
+ * COMPOSITION contract over a fake `decide`. Production wraps the real decider as
+ * `decide: (input) => decideDispatch(input, productionDeciderDeps)` (assembled in 5d-2b),
+ * so the runner stays gate-provable without any decider IO seam leaking in.
+ */
+export interface EntwurfV2RunDeps {
+	decide: (input: DispatchInput) => DispatchDecision | Promise<DispatchDecision>;
+	executor: DispatchExecutorDeps;
+}
+
+/**
+ * The top-level `entwurf_v2` runner: decide → execute, joined. It runs the injected
+ * decider to a `DispatchDecision`, then routes that decision through `executeDispatch`.
+ * That is the WHOLE body — there is no extra branching, lock re-judgement, or transport
+ * decision here (the decider owns routing, `executeDispatch` owns dispatch + the N1/N3
+ * result mapping). A `decide` THROW PROPAGATES untouched: a decision was never produced,
+ * so there is no receipt to wrap and no `EntwurfV2RunResult` to honestly return — the 5d-3
+ * surface top-level catch renders it. A reject/execute decision flows straight into
+ * `executeDispatch`, whose `EntwurfV2RunResult` is returned verbatim.
+ */
+export async function runEntwurfV2(input: DispatchInput, deps: EntwurfV2RunDeps): Promise<EntwurfV2RunResult> {
+	const decision = await deps.decide(input);
+	return executeDispatch(decision, deps.executor);
+}

package/pi-extensions/lib/entwurf-v2-send-fallback.ts

@@ -0,0 +1,166 @@
+/**
+ * entwurf-v2-send-fallback — the 5c-2b same-lock re-resolve RESOLVER (the brain the
+ * 5c-2a send hand calls as `deps.deadFallback` on a `dead` connect). The hand DECIDED
+ * nothing about routing; this resolver re-runs the 5b dispatch logic ONCE — minus the
+ * lock lifecycle — under the lock the hand still holds, and hands back a fresh plan to
+ * EXECUTE or a reject. It NEVER releases the lock (that is the hand's single
+ * responsibility) and NEVER calls decideDispatch whole (that would re-enter the
+ * acquire/release lifecycle the hand already owns).
+ *
+ * Why a re-resolve and not just "dead ⇒ reject": the original control-socket plan came
+ * from the 5b decider observing the target ALIVE; the send's `dead` connect is a TOCTOU
+ * fact about ONE socketPath at send time, not the gid's latest dispatch state. So we
+ * re-inspect + re-probe the canonical path under the held lock and let the SAME frozen
+ * table decide again.
+ *
+ * The intent is pinned to `fire-and-forget` (design lock, GPT 5c-2b): a control-socket
+ * send plan is ONLY ever produced by the `fire-and-forget + live` cell, so the re-resolve
+ * must read the same row. That pin is also what makes "no resume promotion" structural,
+ * not just a 5c-2a guard: the `fire-and-forget` row has NO resume cell —
+ *   live          → send / control-socket   (the retry)
+ *   dormant(dead) → reject (dormant-fire-forget-unsupported)  ← NOT resume/spawn-bg
+ *   indeterminate → reject (indeterminate-no-spawn)
+ * Only `owned-outcome + dormant` is resume/spawn-bg, and an owned-outcome dispatch never
+ * yields a control-socket send plan in the first place. So a dead re-resolve can only
+ * retry (alive), reject (dead/indeterminate pi), or — on an UNSUPPORTED backend, via the
+ * separate mailbox mini-table — enqueue to a deliverable citizen. It can never spawn.
+ *
+ * The N2 asymmetry (frozen in entwurf-v2-contract): in-domain `dormant` is a CONFIRMED
+ * not-running pi → reject (enqueuing would be a silent pileup; resume is the honest
+ * place, and resume is out of a SEND fallback's scope). `unsupported` is UNKNOWN liveness
+ * with no socket axis → the mailbox is its honest channel when deliverable.
+ */
+
+import type { MailboxDeliverabilityResult } from "./entwurf-deliverability.ts";
+import { isLivenessSupported, resolveDispatch } from "./entwurf-v2-contract.ts";
+import type { TargetResolution } from "./entwurf-v2-decider.ts";
+import type { LockClaim } from "./entwurf-v2-lock.ts";
+import type { ControlSocketPlan, DeadFallbackResolution } from "./entwurf-v2-send.ts";
+import { defaultMetaMailboxDir, defaultMetaSessionsDir, type MetaIdentity } from "./meta-session.ts";
+import { mapInspectionToLiveness, type TargetSocketInspection } from "./socket-discovery.ts";
+import type { SocketLiveness } from "./socket-probe.ts";
+
+/**
+ * The resolver's IO seams — the SAME shapes the 5b decider uses, MINUS acquireLock /
+ * releaseLock (the resolver runs under a lock it must not touch). Plan-planted dirs keep
+ * defaults; mailboxDeliverabilityFor is REQUIRED (SE-2 2d-3 — the same seam the decider
+ * takes, no wake-mode-only fallback), as are the IO seams (resolveTarget / inspectSocket /
+ * probeSocket), so the gate drives every branch without a filesystem.
+ */
+export interface DeadFallbackDeps {
+	resolveTarget: (gardenId: string) => TargetResolution | Promise<TargetResolution>;
+	inspectSocket: (gardenId: string) => Promise<TargetSocketInspection>;
+	probeSocket: (socketPath: string) => Promise<SocketLiveness>;
+	/** SE-2 slice 2d-3: the SAME required mailbox-deliverability seam the 5b decider takes
+	 * (wake-mode capability AND a live active-receiver marker matching the identity). Required
+	 * (no default) so the dead-control re-resolve can never fall back to wake-mode-only and
+	 * re-open the SE-2 gap on its own path. Production injects the SAME closure into both. */
+	mailboxDeliverabilityFor: (
+		identity: MetaIdentity,
+	) => MailboxDeliverabilityResult | Promise<MailboxDeliverabilityResult>;
+	mailboxDir?: string;
+	sessionsDir?: string;
+}
+
+/**
+ * Re-resolve a dead control-socket send ONCE under the held lock. Returns a plan to
+ * execute (control-socket retry on a re-observed-alive target, or a meta-mailbox enqueue
+ * on a deliverable unsupported citizen) or a reject (dead/indeterminate pi, undeliverable
+ * citizen, bad target, address conflict). The returned plan ALWAYS targets the same gid
+ * the lock is held for. Inspect/probe throws are left to PROPAGATE — the 5c-2a hand's
+ * lock-leak backstop converts them to failed+release; this resolver never releases.
+ */
+export async function resolveDeadControlSendFallback(
+	plan: ControlSocketPlan,
+	lock: LockClaim,
+	deps: DeadFallbackDeps,
+): Promise<DeadFallbackResolution> {
+	// Mis-wire fail-loud, same grade as the 5c-2a hand: a plan/lock for different gids
+	// would re-resolve B while holding A's lock. (The hand also asserts this on the
+	// returned plan; asserting on the INPUT here fails even earlier, before any IO.)
+	if (plan.targetGardenId !== lock.gardenId) {
+		throw new Error(
+			`entwurf-v2-send-fallback: plan target (${plan.targetGardenId}) does not match held lock (${lock.gardenId}) — mis-paired.`,
+		);
+	}
+	const gardenId = plan.targetGardenId;
+	const mailboxDir = deps.mailboxDir ?? defaultMetaMailboxDir();
+	const sessionsDir = deps.sessionsDir ?? defaultMetaSessionsDir();
+
+	// Probe-free target resolution first — a vanished target or a quarantined address
+	// short-circuits before any inspect/probe (mirrors decideDispatch steps 2). A1 narrow:
+	// a record-LESS but live pi control socket (socketOnlyPi, identity null) is NOT a
+	// bad-target — it is an in-domain pi endpoint that re-resolves through the inspect/probe
+	// path below (fire-and-forget: alive → retry control-send, dead → honest reject). Only a
+	// genuinely absent target (identity null AND not socket-only) is bad-target.
+	const resolution = await deps.resolveTarget(gardenId);
+	if (resolution.identity === null && resolution.socketOnlyPi !== true) {
+		return { kind: "reject", reason: "bad-target" };
+	}
+	if (resolution.preProbeAddressConflict) {
+		return { kind: "reject", reason: "target-address-conflict" };
+	}
+	const identity = resolution.identity;
+
+	// Unsupported backend (claude-code self-fetch, …) → the mailbox mini-table, keyed on
+	// intent alone. This is NOT an in-domain dormant (the N2 asymmetry) — a deliverable
+	// citizen's honest channel is its mailbox. No inspect/probe on this axis. A socket-only
+	// pi endpoint (identity null) is in-domain pi, so it NEVER takes this branch — only a
+	// record-backed unsupported identity does.
+	if (identity !== null && !isLivenessSupported(identity.backend)) {
+		const deliverability = await deps.mailboxDeliverabilityFor(identity);
+		const receipt = resolveDispatch("fire-and-forget", "unsupported", deliverability.deliverable);
+		if (!receipt.ok) {
+			return { kind: "reject", reason: receipt.reason };
+		}
+		// The only allow cell here is fire-and-forget → meta-mailbox send. Preserve the
+		// original message/wantsReply; mode is meaningless for the mailbox (not carried).
+		return {
+			kind: "execute",
+			plan: {
+				transport: "meta-mailbox",
+				action: "send",
+				targetGardenId: gardenId,
+				mailboxDir,
+				sessionsDir,
+				wantsReply: plan.wantsReply,
+				message: plan.message,
+			},
+		};
+	}
+
+	// In-domain (pi-like) → inspect + probe the canonical path UNDER the held lock. A
+	// re-observed `dead`/`indeterminate` is an honest reject (never forced to one or the
+	// other); `address-conflict` is a reject too (a symlink planted since dispatch).
+	const inspection = await deps.inspectSocket(gardenId);
+	const mapped = await mapInspectionToLiveness(inspection, deps.probeSocket);
+	if ("addressConflict" in mapped) {
+		return { kind: "reject", reason: "target-address-conflict" };
+	}
+	const { liveness, socketPath } = mapped;
+
+	const receipt = resolveDispatch("fire-and-forget", liveness, false);
+	if (!receipt.ok) {
+		return { kind: "reject", reason: receipt.reason };
+	}
+	// fire-and-forget + live is the ONLY in-domain allow cell → control-socket send. A
+	// resume/spawn-bg or meta-mailbox transport here would be a frozen-table drift, so
+	// fail loud rather than mis-route a SEND fallback into a child spawn.
+	if (receipt.transport !== "control-socket") {
+		throw new Error(
+			`entwurf-v2-send-fallback: in-domain fire-and-forget re-resolve yielded unexpected transport (${receipt.transport}) — table drift.`,
+		);
+	}
+	return {
+		kind: "execute",
+		plan: {
+			transport: "control-socket",
+			action: "send",
+			targetGardenId: gardenId,
+			socketPath,
+			mode: plan.mode,
+			wantsReply: plan.wantsReply,
+			message: plan.message,
+		},
+	};
+}

package/pi-extensions/lib/entwurf-v2-send.ts

@@ -0,0 +1,271 @@
+/**
+ * entwurf-v2-send — the 5c-2 control-socket SEND hand (0.11 Stage 0 step 5c-2a).
+ * It WIRES real transport IO onto the pure release reducer (5c-1): drive a
+ * control-socket send to a FINAL outcome, feed that outcome to `reduceRelease`, and
+ * release the held lock EXACTLY ONCE. Every IO seam is an injected dep (the gate
+ * fakes it, production wires the real fns), so the send→outcome→release ORDERING is
+ * gate-provable without a live socket — the same "pure-before-IO, IO-via-dep"
+ * discipline 5b used for the decider.
+ *
+ * Why a control hand that only EXECUTES, never DECIDES routing: the 5b decider
+ * already chose this in-domain control-socket plan AFTER observing the target alive.
+ * But a send can race that observation — by send time the socket may be `dead`
+ * (TOCTOU). The control hand must NOT decide on its own that a dead socket means
+ * "mailbox now" — that would bypass the 5b dispatch table (deliverability / conflict /
+ * pi-primary wakeMode). So on a `dead` connect it delegates to `deps.deadFallback`,
+ * a SAME-LOCK one-shot re-resolve (the 5c-2b resolver: reuse 5b resolveTarget /
+ * inspectSocket / resolveDispatch but DO NOT release) that hands back a fresh plan to
+ * EXECUTE or a reject. The hand runs that plan once; it never re-routes by itself.
+ *
+ * The three load-bearing send-final rules (GPT 5c-2 design, conditional GO):
+ *   - in-band reject (RPC `success:false`) is FINAL with NO fallback — the receiver
+ *     was reached and refused; re-resolving would be a second delivery attempt.
+ *   - a `dead` connect (ECONNREFUSED/ENOENT) proves non-delivery → re-resolve once.
+ *   - an `indeterminate` connect (timeout/EACCES/stall) proves NOTHING: the socket
+ *     may be alive-but-stalled, so a fallback would risk a DOUBLE delivery. It is an
+ *     immediate `failed` + rethrow — deadFallback and the mailbox helper are NOT even
+ *     called. (This is the exact F3 three-valued liveness distinction, on the send
+ *     path: dead ⇒ act, indeterminate ⇒ do not.)
+ *
+ * Release authority is ALWAYS the LockClaim the decider handed over. `reduceRelease`
+ * guarantees the release fires at most once across the single send-final event; a
+ * `releaseLock` throw never MASKS a send failure — the original error wins (5b).
+ */
+
+import type { ExecutionPlan } from "./entwurf-v2-decider.ts";
+import type { LockClaim } from "./entwurf-v2-lock.ts";
+import {
+	decideReleasePolicy,
+	initialReleaseState,
+	type ReleasePolicy,
+	type ReleaseState,
+	reduceRelease,
+} from "./entwurf-v2-release.ts";
+
+// The two send-capable plan shapes, narrowed from the decider's ExecutionPlan union.
+export type ControlSocketPlan = Extract<ExecutionPlan, { transport: "control-socket" }>;
+export type MetaMailboxPlan = Extract<ExecutionPlan, { transport: "meta-mailbox" }>;
+
+/** The terminal outcome of a send attempt, mapped 1:1 onto the reducer's
+ * `send-final` outcomes. `fallback-sent` is a REAL final outcome (legacy parity: a
+ * re-resolved delivery is not a hidden retry). */
+export type SendFinalOutcome = "sent" | "fallback-sent" | "rejected" | "failed";
+
+/** What a single RPC / mailbox enqueue reports. `success:false` is an in-band reject
+ * (the receiver answered and refused) — distinct from a thrown connect error. */
+export interface RpcSendResult {
+	success: boolean;
+	error?: string;
+}
+
+/** The same-lock one-shot re-resolve result (5c-2b implements the resolver; 5c-2a
+ * only consumes its contract). `execute` hands back a fresh plan to run ONCE under the
+ * SAME held lock; `reject` means there is no live route — a final `rejected`. The
+ * resolver must NOT release the lock — release stays the hand's single responsibility. */
+export type DeadFallbackResolution = { kind: "execute"; plan: ExecutionPlan } | { kind: "reject"; reason: string };
+
+/**
+ * Every IO seam is a REQUIRED dep — the hand performs ZERO IO of its own, exactly so
+ * the gate can drive every send-final path without a socket (5b's "no hidden default
+ * that touches the world" rule).
+ *   - sendOverSocket  — the control-socket RPC send (1차 AND the re-resolve retry).
+ *     Resolves `RpcSendResult` on a completed RPC; THROWS on a connect-time failure
+ *     (the thrown error's `.code` is what `classifyConnect` reads).
+ *   - classifyConnect — connect-error code → "dead" | "indeterminate" (the F3 split).
+ *   - releaseLock     — release the held claim; called at most once, only when the
+ *     reducer says shouldRelease.
+ *   - deadFallback    — the SAME-LOCK re-resolve, called ONLY on a `dead` connect and
+ *     ONLY while the lock is still held. (5c-2b supplies the real resolver.)
+ *   - sendViaMailbox  — enqueue-only meta-mailbox delivery, used ONLY when the
+ *     re-resolve hands back a meta-mailbox plan. The hand never decides mailbox
+ *     routing itself; it just runs the plan the resolver chose. (5c-4 supplies the
+ *     real enqueue.)
+ */
+export interface ControlSocketSendDeps {
+	sendOverSocket: (plan: ControlSocketPlan) => Promise<RpcSendResult>;
+	classifyConnect: (code: string | undefined) => "dead" | "indeterminate";
+	releaseLock: (lock: LockClaim) => void;
+	deadFallback: (plan: ControlSocketPlan, lock: LockClaim) => Promise<DeadFallbackResolution>;
+	sendViaMailbox: (plan: MetaMailboxPlan, lock: LockClaim) => Promise<RpcSendResult>;
+}
+
+export interface ControlSocketSendResult {
+	outcome: SendFinalOutcome;
+	/** Present ONLY on a `rejected` outcome that came from the dead-path re-resolve
+	 * (5c-2b): the resolver's machine-readable reason (dormant-fire-forget-unsupported /
+	 * mailbox-undeliverable / indeterminate-no-spawn / bad-target / target-address-conflict).
+	 * An in-band RPC refusal carries NO reason (there is no resolver taxonomy for it). The
+	 * 5d runner carries this verbatim so the surface can tell "in-band refusal" from
+	 * "no live route" — the N3 carry-over the hand boundary used to drop. */
+	rejectReason?: string;
+}
+
+// A drive step's verdict: the terminal outcome, plus the original error to RETHROW on
+// a `failed` (the hand releases first, then rethrows — never swallows the failure), plus
+// the optional resolver reject reason to carry on a re-resolve `rejected` (N3).
+interface SendDrive {
+	outcome: SendFinalOutcome;
+	error?: unknown;
+	rejectReason?: string;
+}
+
+/**
+ * Execute a control-socket send to a final outcome and release the held lock exactly
+ * once. `lock` MUST be the in-domain claim the decider handed over —
+ * `decideReleasePolicy` throws if it is null or paired with the wrong gid (a mis-wire
+ * is fail-loud, not a runtime branch). On a `failed` outcome the original transport
+ * error is rethrown AFTER the (single) release.
+ */
+export async function executeControlSocketSend(
+	plan: ControlSocketPlan,
+	lock: LockClaim | null,
+	deps: ControlSocketSendDeps,
+): Promise<ControlSocketSendResult> {
+	// Throws on a null / mis-paired lock (？7 + gid invariants). After this line the
+	// control-socket policy is release-after-send-final and the lock is non-null.
+	const policy: ReleasePolicy = decideReleasePolicy(plan, lock);
+	const held = lock as LockClaim;
+
+	// Lock-leak backstop: once the lock is held, ANY throw out of the drive — a
+	// contract-violation guard (spawn-bg re-resolve), the mis-route assert, even a buggy
+	// dep that throws where it should return — must still release the lock before it
+	// propagates. A leaked lock pins the gid forever (5a's worst failure). So convert any
+	// such throw into a `failed` final outcome, run finalizeRelease (which releases on
+	// the send-final event), and then rethrow the original error from there.
+	let drive: SendDrive;
+	try {
+		drive = await driveSend(plan, held, deps);
+	} catch (err) {
+		drive = { outcome: "failed", error: err };
+	}
+	finalizeRelease(policy, deps, held, drive);
+	return { outcome: drive.outcome, rejectReason: drive.rejectReason };
+}
+
+/** Drive the 1차 send and route a connect failure through the F3 split. */
+async function driveSend(plan: ControlSocketPlan, lock: LockClaim, deps: ControlSocketSendDeps): Promise<SendDrive> {
+	let result: RpcSendResult;
+	try {
+		result = await deps.sendOverSocket(plan);
+	} catch (err) {
+		const liveness = deps.classifyConnect((err as NodeJS.ErrnoException)?.code);
+		if (liveness === "indeterminate") {
+			// Stall/unknown — the socket may be alive. A fallback here risks a DOUBLE
+			// delivery, so finalize as failed WITHOUT touching deadFallback / mailbox.
+			return { outcome: "failed", error: err };
+		}
+		// dead ⇒ proven non-delivery ⇒ same-lock one-shot re-resolve (lock still held).
+		return await driveDeadFallback(plan, lock, deps);
+	}
+	// A completed RPC: ack ⇒ sent; in-band refusal ⇒ rejected, NO fallback.
+	return { outcome: result.success ? "sent" : "rejected" };
+}
+
+/**
+ * The dead-path fallback: re-resolve ONCE under the held lock, then run the resolver's
+ * chosen plan exactly once (the retry is one-shot — a second connect failure does NOT
+ * re-enter the fallback, it finalizes as failed). The hand only executes; the resolver
+ * decided.
+ */
+async function driveDeadFallback(
+	plan: ControlSocketPlan,
+	lock: LockClaim,
+	deps: ControlSocketSendDeps,
+): Promise<SendDrive> {
+	let resolution: DeadFallbackResolution;
+	try {
+		resolution = await deps.deadFallback(plan, lock);
+	} catch (err) {
+		return { outcome: "failed", error: err };
+	}
+	if (resolution.kind === "reject") {
+		// N3: carry the resolver's reason out so the runner/surface can distinguish a
+		// dormant-fire-forget / undeliverable / no-route reject from an in-band refusal.
+		return { outcome: "rejected", rejectReason: resolution.reason };
+	}
+	const rePlan = resolution.plan;
+	// Same-lock re-resolve invariant: the fallback plan MUST target the SAME gid the lock
+	// is held for. A resolver that returns a DIFFERENT target's plan would send/enqueue to
+	// B while only A's lock is ever released — a mis-route AND a lock leak. Fail loud (the
+	// execute-level catch in executeControlSocketSend releases A's lock before rethrowing).
+	if (rePlan.targetGardenId !== plan.targetGardenId || rePlan.targetGardenId !== lock.gardenId) {
+		throw new Error(
+			`entwurf-v2-send: re-resolve returned a plan for a different target (${rePlan.targetGardenId}) than the held lock (${lock.gardenId}) — same-lock re-resolve violated.`,
+		);
+	}
+	switch (rePlan.transport) {
+		case "control-socket":
+			// Re-resolve picked another live socket — retry the send ONCE. A second
+			// connect failure finalizes as failed (no further fallback).
+			try {
+				const r = await deps.sendOverSocket(rePlan);
+				return { outcome: r.success ? "fallback-sent" : "rejected" };
+			} catch (err) {
+				return { outcome: "failed", error: err };
+			}
+		case "meta-mailbox":
+			// Re-resolve picked the mailbox — enqueue ONCE via the injected helper. The
+			// hand never reaches for the mailbox on its own; only the resolver routes here.
+			try {
+				const r = await deps.sendViaMailbox(rePlan, lock);
+				return { outcome: r.success ? "fallback-sent" : "rejected" };
+			} catch (err) {
+				return { outcome: "failed", error: err };
+			}
+		case "spawn-bg":
+			// A SEND fallback must never re-resolve into a spawn — that is a decider
+			// contract violation (a send and a spawn are different actions), so fail loud
+			// rather than silently mis-execute.
+			throw new Error("entwurf-v2-send: re-resolve returned a spawn-bg plan for a send fallback (contract violation).");
+	}
+}
+
+/**
+ * N1: a release failure AFTER a non-`failed` final outcome. The send already reached a
+ * terminal result (`sent` / `fallback-sent` / `rejected`) — the delivery (or in-band
+ * refusal) HAPPENED — but `releaseLock` then threw, so the lock is dirty. This is NOT a
+ * send failure, and the caller MUST NOT re-dispatch (a re-send would double-deliver). A
+ * structured error (not a bare rethrow) lets the 5d runner render "finalized + lock
+ * dirty, retry-unsafe" distinctly from "send failed". For a `failed` outcome the original
+ * send error still wins — that path never builds this error.
+ */
+export class SendDeliveredReleaseFailedError extends Error {
+	readonly finalizedOutcome: Exclude<SendFinalOutcome, "failed">;
+	readonly releaseError: unknown;
+	constructor(finalizedOutcome: Exclude<SendFinalOutcome, "failed">, releaseError: unknown) {
+		const detail = releaseError instanceof Error ? releaseError.message : String(releaseError);
+		super(
+			`entwurf-v2-send: ${finalizedOutcome} delivered but releaseLock failed (lock dirty, do NOT re-send): ${detail}`,
+		);
+		this.name = "SendDeliveredReleaseFailedError";
+		this.finalizedOutcome = finalizedOutcome;
+		this.releaseError = releaseError;
+	}
+}
+
+/**
+ * Fold the single send-final event into the reducer and release the lock if (and only
+ * if) the reducer says so. On a `failed` outcome the lock is released FIRST and then
+ * the original error is rethrown — and if `releaseLock` itself throws, the original
+ * send error still wins (a release failure must not MASK the send failure; 5b). On a
+ * NON-`failed` outcome a release failure throws a `SendDeliveredReleaseFailedError` (N1):
+ * the delivery happened, so the runner must surface "finalized + lock dirty", not "failed".
+ */
+function finalizeRelease(policy: ReleasePolicy, deps: ControlSocketSendDeps, lock: LockClaim, drive: SendDrive): void {
+	const initial: ReleaseState = initialReleaseState();
+	const { shouldRelease } = reduceRelease(policy, initial, { kind: "send-final", outcome: drive.outcome });
+	const original = drive.outcome === "failed" ? drive.error : undefined;
+
+	if (shouldRelease) {
+		try {
+			deps.releaseLock(lock);
+		} catch (releaseErr) {
+			// A release failure must not swallow a real send failure.
+			if (drive.outcome === "failed") throw original;
+			// N1: the delivery/refusal already happened — surface it as a structured,
+			// retry-unsafe error rather than a bare release throw.
+			throw new SendDeliveredReleaseFailedError(drive.outcome, releaseErr);
+		}
+	}
+	if (drive.outcome === "failed") throw original;
+}