@junghanacs/entwurf 0.12.0

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

@@ -0,0 +1,326 @@
+/**
+ * entwurf-v2-production — 5d-2b: the ctx-free PRODUCTION assembly of `runEntwurfV2`'s deps.
+ * `makeProductionEntwurfV2Deps(opts)` wires the real 5b decider IO seams + the three 5c
+ * transport hands into one `EntwurfV2RunDeps` (`{decide, executor}`). It touches NO
+ * `ExtensionContext`/`ExtensionAPI` — the wiring SITE (5d-3, entwurf-control.ts) builds the
+ * `senderProvider` from `buildLocalSenderEnvelope(ctx)` and passes it in, so this module
+ * stays in `lib/` with the rest of the gate-/smoke-testable v2 core.
+ *
+ * Three invariants this factory exists to guarantee (each gate-proven):
+ *   - ONE lock domain (Q2/QB3). A single `release` closure bound to `lockDir` is the lock
+ *     authority for EVERY hand: the decider's `releaseLock`, the control-send hand's
+ *     `releaseLock`, AND the spawn watcher's `releaseFn`. The spawn factory's default
+ *     `releaseFn` ignores `lockDir` (it would release into the DEFAULT lock dir) — passing
+ *     `release` explicitly is what closes that split-brain.
+ *   - ONE mailbox sender (Q3). A single `makeProductionSendViaMailbox` instance is the
+ *     top-level meta-mailbox hand AND the control-send dead-fallback's mailbox enqueue, so a
+ *     direct send and a fallback send never drift in sender envelope / dirs.
+ *   - ONE path set (Q5). `sessionsDir`/`mailboxDir`/`lockDir`/`controlSocketDir` are resolved
+ *     ONCE and threaded to the decider, the dead-fallback resolver, and the enqueue, so the
+ *     plan the decider plants and the plan the fallback plants address the same store.
+ *
+ * `resolveTarget` (QB1): a MISSING meta-record is a soft `bad-target` (identity:null); a
+ * PRESENT-but-corrupt record fails LOUD (the read throws drift) — never matched by string.
+ * `preProbeAddressConflict` (QB2): a single record-side `lstat` (NO connect) of the target's
+ * canonical socket path; `indeterminate` (EACCES/unknown) fails loud rather than silently
+ * claiming "no conflict". The decider's later `inspectSocket` probe is a SEPARATE step.
+ */
+
+import {
+	type RpcClientOptions,
+	type RpcCommand,
+	type RpcResponse,
+	sendRpcCommand as realSendRpc,
+	type SenderEnvelope,
+} from "./entwurf-control-rpc.ts";
+import {
+	type MailboxDeliverabilityResult,
+	mailboxConversationalDeliverable,
+	receiverMarkerMatchesIdentity,
+} from "./entwurf-deliverability.ts";
+import { isNonPiGardenIdSocketConflict } from "./entwurf-facts.ts";
+import { type PreflightInput, type PreflightOutcome, preflight as realPreflight } from "./entwurf-preflight.ts";
+import { isLivenessSupported } from "./entwurf-v2-contract.ts";
+import {
+	type DispatchDeciderDeps,
+	type DispatchInput,
+	decideDispatch,
+	type TargetResolution,
+} from "./entwurf-v2-decider.ts";
+import {
+	type AcquireLockResult,
+	ENTWURF_V2_LOCK_DIR,
+	type LockClaim,
+	acquireLock as realAcquireLock,
+	releaseLock as realReleaseLock,
+} from "./entwurf-v2-lock.ts";
+import { makeProductionSendViaMailbox } from "./entwurf-v2-mailbox.ts";
+import type { DispatchExecutorDeps, EntwurfV2RunDeps } from "./entwurf-v2-runner.ts";
+import {
+	type ControlSocketPlan,
+	type ControlSocketSendDeps,
+	executeControlSocketSend,
+	type MetaMailboxPlan,
+	type RpcSendResult,
+} from "./entwurf-v2-send.ts";
+import { resolveDeadControlSendFallback } from "./entwurf-v2-send-fallback.ts";
+import type { SpawnBgPlan } from "./entwurf-v2-spawn.ts";
+import { executeSpawnBgResume } from "./entwurf-v2-spawn.ts";
+import { makeProductionSpawnBgResumeDeps, type ProductionSpawnOpts } from "./entwurf-v2-spawn-production.ts";
+import {
+	defaultMetaMailboxDir,
+	defaultMetaSessionsDir,
+	type EnqueueMetaMessageOptions,
+	type EnqueueMetaMessageResult,
+	enqueueMetaMessage,
+	type MetaIdentity,
+	type MetaReceiverMarker,
+	metaCapabilityFor,
+	metaRecordExistsByGardenId,
+	readMetaIdentityByGardenId,
+	readMetaReceiverMarker,
+} from "./meta-session.ts";
+import {
+	CONTROL_SOCKET_DIR,
+	controlSocketPath,
+	inspectControlSocketPath,
+	inspectTargetControlSocket,
+	isSocketOnlyPiCandidate,
+	type TargetSocketInspection,
+} from "./socket-discovery.ts";
+import { classifyConnectError, probeSocketLiveness, type SocketLiveness } from "./socket-probe.ts";
+
+/**
+ * The leaf IO the production factory calls. Every field defaults to the REAL fn; the 5d-2b
+ * gate overrides them with spies to prove the wiring (shared closures, lockDir binding,
+ * shared mailbox instance) WITHOUT a real socket/lock/meta-record. This is the only seam —
+ * the factory's COMPOSITION (which closure goes to which hand) is never overridable.
+ */
+export interface ProductionEntwurfV2Seams {
+	metaRecordExists: (gid: string, sessionsDir: string) => boolean;
+	readIdentity: (gid: string, sessionsDir: string) => MetaIdentity;
+	/** Read the target's receiver presence marker (null = absent / dead owner / corrupt). The
+	 * SE-2 2d-3 active-receiver source; the factory's `mailboxDeliverabilityFor` closure verifies
+	 * its identity match. */
+	readReceiverMarker: (gardenId: string) => MetaReceiverMarker | null;
+	/** Record-side lstat of the EXACT target socket path (no connect) for the pre-probe conflict. */
+	inspectPath: (socketPath: string) => Promise<TargetSocketInspection>;
+	acquireLock: (gid: string, deps: { dir?: string }) => AcquireLockResult;
+	releaseLock: (claim: LockClaim, deps: { dir?: string }) => unknown;
+	inspectSocket: (gid: string, dir: string) => Promise<TargetSocketInspection>;
+	probeSocket: (socketPath: string) => Promise<SocketLiveness>;
+	preflight: (input: PreflightInput) => PreflightOutcome;
+	classifyConnect: (code: string | undefined) => "dead" | "indeterminate";
+	sendRpc: (socketPath: string, command: RpcCommand, options?: RpcClientOptions) => Promise<{ response: RpcResponse }>;
+	enqueue: (opts: EnqueueMetaMessageOptions) => EnqueueMetaMessageResult;
+	/** Extra spawn-factory overrides (timers/spawnChild/probe) for a deterministic spawn gate.
+	 * `releaseFn` is NOT overridable here — the factory injects the shared `release` (QB3). */
+	spawnOverrides: Omit<ProductionSpawnOpts, "releaseFn">;
+}
+
+export interface ProductionEntwurfV2Opts {
+	/** Built at the wiring site from `buildLocalSenderEnvelope(ctx)`, decorated with its
+	 * HONEST pi-session replyability (SE-1 2e-a: `replyable` reflects whether the canonical
+	 * control socket actually exists, not a hardcoded true). ONE provider feeds the
+	 * control-socket RPC sender AND the meta-mailbox body sender (they share the envelope). */
+	senderProvider: () => SenderEnvelope | undefined;
+	/** pi agent dir holding `trust.json` (preflight). Omit → preflight's own default. */
+	agentDir?: string;
+	/** Operator-policy auto-approve roots (preflight prefix promotion). No package default. */
+	prefixRoots?: readonly string[];
+	lockDir?: string;
+	sessionsDir?: string;
+	mailboxDir?: string;
+	controlSocketDir?: string;
+	observeTimeoutMs?: number;
+	killGraceMs?: number;
+	/** Gate/smoke seam overrides — defaults are the real IO. */
+	seams?: Partial<ProductionEntwurfV2Seams>;
+}
+
+/** Map a record-side socket inspection to the singleton (socketGids, symlinkedGids) the
+ * `isNonPiGardenIdSocketConflict` predicate consumes. `indeterminate` fails LOUD (QB2): an
+ * unprovable conflict must NOT be folded to "no conflict" — that would silently allow an
+ * unsupported-backend mailbox send onto a quarantined address. */
+function conflictSetsFor(
+	gid: string,
+	inspection: TargetSocketInspection,
+): { socketGids: ReadonlySet<string>; symlinkedGids: ReadonlySet<string> } {
+	switch (inspection.kind) {
+		case "absent":
+			return { socketGids: new Set(), symlinkedGids: new Set() };
+		case "socket-file":
+			return { socketGids: new Set([gid]), symlinkedGids: new Set() };
+		case "address-conflict":
+			// symlink → the symlink axis; not-socket → a non-symlink `.sock` entry, same axis
+			// the fact-provider's `socketGids` carries (NOT only real sockets).
+			return inspection.reason === "symlink"
+				? { socketGids: new Set(), symlinkedGids: new Set([gid]) }
+				: { socketGids: new Set([gid]), symlinkedGids: new Set() };
+		case "indeterminate":
+			throw new Error(
+				`entwurf-v2-production: cannot resolve target ${gid} — its control socket lstat is indeterminate (${inspection.error}); refusing to claim "no address conflict".`,
+			);
+	}
+}
+
+/**
+ * Assemble the production `runEntwurfV2` deps. See the module header for the three wiring
+ * invariants. The returned `{ decide, executor }` is exactly the shape `runEntwurfV2` joins.
+ */
+export function makeProductionEntwurfV2Deps(opts: ProductionEntwurfV2Opts): EntwurfV2RunDeps {
+	// ── ONE path set (Q5): resolve every dir ONCE ─────────────────────────────
+	const lockDir = opts.lockDir ?? ENTWURF_V2_LOCK_DIR;
+	const sessionsDir = opts.sessionsDir ?? defaultMetaSessionsDir();
+	const mailboxDir = opts.mailboxDir ?? defaultMetaMailboxDir();
+	const controlSocketDir = opts.controlSocketDir ?? CONTROL_SOCKET_DIR;
+
+	const s = opts.seams ?? {};
+	const io: ProductionEntwurfV2Seams = {
+		metaRecordExists: s.metaRecordExists ?? metaRecordExistsByGardenId,
+		readIdentity: s.readIdentity ?? readMetaIdentityByGardenId,
+		readReceiverMarker: s.readReceiverMarker ?? ((gid: string) => readMetaReceiverMarker({ gardenId: gid })),
+		inspectPath: s.inspectPath ?? inspectControlSocketPath,
+		acquireLock: s.acquireLock ?? realAcquireLock,
+		releaseLock: s.releaseLock ?? realReleaseLock,
+		inspectSocket: s.inspectSocket ?? inspectTargetControlSocket,
+		probeSocket: s.probeSocket ?? probeSocketLiveness,
+		preflight: s.preflight ?? realPreflight,
+		classifyConnect: s.classifyConnect ?? classifyConnectError,
+		sendRpc: s.sendRpc ?? realSendRpc,
+		enqueue: s.enqueue ?? enqueueMetaMessage,
+		spawnOverrides: s.spawnOverrides ?? {},
+	};
+
+	// ── ONE lock domain (Q2/QB3): a single lockDir-bound release for ALL hands ─
+	const acquire = (gid: string): AcquireLockResult => io.acquireLock(gid, { dir: lockDir });
+	const release = (claim: LockClaim): void => {
+		io.releaseLock(claim, { dir: lockDir });
+	};
+
+	// ── ONE mailbox sender (Q3): one instance for the hand AND the dead-fallback ─
+	const sendViaMailbox = makeProductionSendViaMailbox({
+		senderProvider: opts.senderProvider,
+		enqueue: io.enqueue,
+	});
+
+	// ── ONE deliverability seam (SE-2 2d-3): wake-mode capability AND a live active-
+	// receiver (a presence marker that matches THIS identity). The SAME closure is injected
+	// into the decider AND the dead-fallback, so a direct send and a re-resolved fallback
+	// send can never drift to different deliverability verdicts. recordBacked is true by
+	// construction — resolveTarget already proved the record exists before any unsupported-
+	// backend mailbox route, and the closure is only consulted on that route. A null /
+	// dead-owner / identity-mismatched marker is fail-closed to inactive (SE-2): a reply to a
+	// terminated self-fetch citizen is rejected, not enqueued as mailbox garbage. ──────────
+	const mailboxDeliverabilityFor = (identity: MetaIdentity): MailboxDeliverabilityResult => {
+		const wakeMode = metaCapabilityFor(identity.backend).wakeMode;
+		const marker = io.readReceiverMarker(identity.gardenId);
+		const matched = receiverMarkerMatchesIdentity(marker, identity);
+		return mailboxConversationalDeliverable({
+			wakeMode,
+			recordBacked: true,
+			ownerAlive: matched,
+			watchArmed: matched,
+		});
+	};
+
+	// ── target resolution (QB1 + QB2) ─────────────────────────────────────────
+	const resolveTarget = async (gid: string): Promise<TargetResolution> => {
+		// MISSING record → not a citizen. But a record-LESS, gid-shaped, NON-SYMLINK control
+		// socket means the gid is still an addressable socket-only pi endpoint (A1 narrow,
+		// 0.11.0): entwurf_v2 accepts it as a FIRE-AND-FORGET control-send target only. This is
+		// PROBE-FREE — a single `inspectPath` lstat (NO connect), the SAME seam the pre-probe
+		// conflict uses — and `isSocketOnlyPiCandidate` promotes ONLY a confirmed non-symlink
+		// socket (`socket-file`); symlink/absent/not-socket/indeterminate stay a plain
+		// bad-target. PRESENT record → read (drift/corrupt throws = fail-loud).
+		if (!io.metaRecordExists(gid, sessionsDir)) {
+			const inspection = await io.inspectPath(controlSocketPath(gid, controlSocketDir));
+			return { identity: null, preProbeAddressConflict: false, socketOnlyPi: isSocketOnlyPiCandidate(inspection) };
+		}
+		const identity = io.readIdentity(gid, sessionsDir);
+		// `preProbeAddressConflict` is the record-side NON-PI conflict ONLY (B1). An in-domain
+		// (pi) target's socket lstat/connect MUST run UNDER the lock in the decider's later
+		// `inspectSocket` step (1C: lock BEFORE lstat/connect) — so a pi target short-circuits
+		// here with NO pre-lock lstat. Doing the lstat here would (a) be a needless pre-lock IO
+		// and (b) turn a pi target's `indeterminate` lstat into a top-level throw, stealing it
+		// from the under-lock `inspectSocket → indeterminate → indeterminate-no-spawn` path.
+		if (isLivenessSupported(identity.backend)) {
+			return { identity, preProbeAddressConflict: false };
+		}
+		// Only an unsupported (non-pi) citizen reaches the record-side lstat: a single lstat (no
+		// connect) of the canonical path; `indeterminate` fails loud (QB2 — never "no conflict").
+		const inspection = await io.inspectPath(controlSocketPath(gid, controlSocketDir));
+		const { socketGids, symlinkedGids } = conflictSetsFor(gid, inspection);
+		const preProbeAddressConflict = isNonPiGardenIdSocketConflict(identity.backend, gid, socketGids, symlinkedGids);
+		return { identity, preProbeAddressConflict };
+	};
+
+	const inspectSocket = (gid: string): Promise<TargetSocketInspection> => io.inspectSocket(gid, controlSocketDir);
+	const probeSocket = (socketPath: string): Promise<SocketLiveness> => io.probeSocket(socketPath);
+
+	// ── decider deps (5b) ─────────────────────────────────────────────────────
+	const deciderDeps: DispatchDeciderDeps = {
+		resolveTarget,
+		acquireLock: acquire,
+		releaseLock: release,
+		inspectSocket,
+		probeSocket,
+		preflightForCwd: (cwd: string): PreflightOutcome =>
+			io.preflight({ cwd, agentDir: opts.agentDir, prefixRoots: opts.prefixRoots }),
+		mailboxDeliverabilityFor,
+		mailboxDir,
+		sessionsDir,
+		observeTimeoutMs: opts.observeTimeoutMs,
+	};
+
+	// ── control-send hand deps (5c-2): the dead-fallback shares resolveTarget /
+	// inspect / probe / dirs with the decider; the mailbox enqueue is the SAME
+	// `sendViaMailbox` instance; the release is the SAME `release` closure. ─────
+	const controlSendDeps: ControlSocketSendDeps = {
+		sendOverSocket: async (plan: ControlSocketPlan): Promise<RpcSendResult> => {
+			const { response } = await io.sendRpc(plan.socketPath, {
+				type: "send",
+				message: plan.message,
+				mode: plan.mode,
+				wants_reply: plan.wantsReply,
+				sender: opts.senderProvider(),
+			});
+			return { success: response.success, error: response.error };
+		},
+		classifyConnect: io.classifyConnect,
+		releaseLock: release,
+		deadFallback: (plan: ControlSocketPlan, lock: LockClaim) =>
+			resolveDeadControlSendFallback(plan, lock, {
+				resolveTarget,
+				inspectSocket,
+				probeSocket,
+				mailboxDeliverabilityFor,
+				mailboxDir,
+				sessionsDir,
+			}),
+		sendViaMailbox,
+	};
+
+	// ── executor: the three transport hands, each pre-bound ───────────────────
+	const executor: DispatchExecutorDeps = {
+		sendControl: (plan, lock) => executeControlSocketSend(plan as ControlSocketPlan, lock, controlSendDeps),
+		resumeSpawnBg: (plan, lock) =>
+			executeSpawnBgResume(
+				plan as SpawnBgPlan,
+				lock,
+				// QB3: inject the shared lockDir-bound `release` — never the spawn factory's
+				// default releaseFn (which would release into the DEFAULT lock dir).
+				makeProductionSpawnBgResumeDeps({
+					...io.spawnOverrides,
+					killGraceMs: opts.killGraceMs ?? io.spawnOverrides.killGraceMs,
+					releaseFn: release,
+				}),
+			),
+		sendMailbox: (plan, _lock) => sendViaMailbox(plan as MetaMailboxPlan, _lock as LockClaim),
+	};
+
+	return {
+		decide: (input: DispatchInput) => decideDispatch(input, deciderDeps),
+		executor,
+	};
+}

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

@@ -0,0 +1,149 @@
+/**
+ * entwurf-v2-release — the PURE release-policy reducer for the 5c transport hand
+ * (0.11 Stage 0 step 5c-1). It answers ONE question with zero IO: given the plan
+ * the 5b decider chose and the lock it handed over, on WHICH execution event may
+ * the transport hand release that lock — and it guarantees the release fires
+ * AT MOST ONCE.
+ *
+ * Why a pure reducer before any transport IO (5b discipline = gate-first →
+ * pure-before-IO → wire): the load-bearing risk of 5c is NOT the spawn/send IO, it
+ * is the RELEASE TIMING (Fable 3, "release-after-observation"). A spawn-bg dispatch
+ * that releases its lock too early — on spawn-started/ack instead of on an observed
+ * liveness transition — reopens the exact double-spawn window 5a's per-gid lock
+ * exists to close. So the timing logic is isolated here as a pure state machine the
+ * gate drives over every event order, and 5c-2/5c-3/5c-4 only WIRE the real
+ * send/spawn/mailbox IO onto it. The hand feeds events; this module decides release.
+ *
+ * The three policies (one per ExecutionPlan transport):
+ *   - no-lock                       — meta-mailbox (？7: no lock was ever held).
+ *     Nothing to release on any event.
+ *   - release-after-send-final      — control-socket send. The lock is held only for
+ *     the at-most-once re-resolve; release once the send reaches a FINAL outcome.
+ *   - release-after-spawn-observation — spawn-bg resume. The lock is held until the
+ *     FIRST observable transition: socket-alive OR child-exited (any code). A
+ *     spawn-started event is explicitly NOT a release trigger (that is the whole
+ *     point). A spawn that never started (spawn-start-failed) has no child to watch,
+ *     so it releases to free the gid — keeping the lock would pin it forever.
+ *
+ * The release authority is ALWAYS the LockClaim the decider handed over (5c wires it
+ * through). This module never re-derives a lock by gid, never re-resolves a path —
+ * it is pure routing logic over opaque events.
+ */
+
+import type { ExecutionPlan } from "./entwurf-v2-decider.ts";
+import type { LockClaim } from "./entwurf-v2-lock.ts";
+
+// ── ReleasePolicy (derived once from the plan + held lock) ───────────────────
+export type ReleasePolicy =
+	| { kind: "no-lock" }
+	| { kind: "release-after-send-final" }
+	| { kind: "release-after-spawn-observation" };
+
+// ── ReleaseEvent (the transport hand feeds these as execution proceeds) ──────
+// `send-final` carries the terminal send outcome (legacy parity: a fallback-sent is
+// a real final outcome, not a hidden retry). `child-exited` carries the code (null =
+// killed by signal) but the policy releases on ANY code. `mailbox-enqueued` is the
+// terminal ack on the lock-free path. `spawn-started`/`spawn-start-failed` bracket
+// the spawn attempt — only the FAILURE finalizes; a successful start must wait for an
+// observed transition.
+export type ReleaseEvent =
+	| { kind: "send-final"; outcome: "sent" | "fallback-sent" | "rejected" | "failed" }
+	| { kind: "spawn-started"; pid: number }
+	| { kind: "spawn-start-failed"; error: string }
+	| { kind: "socket-alive" }
+	| { kind: "child-exited"; code: number | null }
+	| { kind: "mailbox-enqueued" };
+
+// ── ReleaseState (single-release accumulator) ───────────────────────────────
+export interface ReleaseState {
+	released: boolean;
+}
+
+export function initialReleaseState(): ReleaseState {
+	return { released: false };
+}
+
+/**
+ * An in-domain execute (control-socket / spawn-bg) must hold a lock whose gardenId
+ * IS the plan's target. Both halves are 5b decider-contract invariants, not runtime
+ * conditions: a null lock or a lock paired with the WRONG plan are the same grade of
+ * mis-wiring (a later release would free nothing, or free a DIFFERENT gid's lock), so
+ * both fail loud here rather than silently mis-releasing. Asserts the lock non-null
+ * so the caller may use it as a `LockClaim`.
+ */
+function assertInDomainLock(plan: ExecutionPlan, lock: LockClaim | null): asserts lock is LockClaim {
+	if (lock === null) {
+		throw new Error(`entwurf-v2-release: an in-domain (${plan.transport}) execute must hold a lock.`);
+	}
+	if (lock.gardenId !== plan.targetGardenId) {
+		throw new Error(
+			`entwurf-v2-release: lock gardenId (${lock.gardenId}) does not match plan target (${plan.targetGardenId}) — mis-paired plan/lock.`,
+		);
+	}
+}
+
+/**
+ * Derive the release policy from the plan, cross-checking the lock invariants the 5b
+ * decider guarantees: meta-mailbox ⇒ lock null (？7); in-domain (control-socket /
+ * spawn-bg) ⇒ lock non-null AND lock.gardenId === plan.targetGardenId. A mismatch is
+ * a decider contract violation, not a runtime condition — it throws so a mis-wired
+ * hand fails loud instead of silently dropping or mis-releasing a lock.
+ */
+export function decideReleasePolicy(plan: ExecutionPlan, lock: LockClaim | null): ReleasePolicy {
+	switch (plan.transport) {
+		case "meta-mailbox":
+			if (lock !== null) {
+				throw new Error("entwurf-v2-release: a meta-mailbox plan must carry no lock (？7 invariant violated).");
+			}
+			return { kind: "no-lock" };
+		case "control-socket":
+			assertInDomainLock(plan, lock);
+			return { kind: "release-after-send-final" };
+		case "spawn-bg":
+			assertInDomainLock(plan, lock);
+			return { kind: "release-after-spawn-observation" };
+	}
+}
+
+export interface ReduceReleaseResult {
+	state: ReleaseState;
+	shouldRelease: boolean;
+}
+
+/**
+ * Fold one execution event into the release decision. `shouldRelease` is true
+ * EXACTLY ONCE — on the first event that satisfies the policy's release condition;
+ * every later event (after `state.released`) returns false. The single-release
+ * guarantee is what lets the spawn watcher race socket-alive against child-exit
+ * without a double release: whichever fires first releases, the other is a no-op.
+ */
+export function reduceRelease(policy: ReleasePolicy, state: ReleaseState, event: ReleaseEvent): ReduceReleaseResult {
+	if (state.released) {
+		return { state, shouldRelease: false };
+	}
+	const release = (): ReduceReleaseResult => ({ state: { released: true }, shouldRelease: true });
+	const hold = (): ReduceReleaseResult => ({ state, shouldRelease: false });
+
+	switch (policy.kind) {
+		case "no-lock":
+			// No lock was ever held → nothing to release on any event.
+			return hold();
+		case "release-after-send-final":
+			// Release once the send reaches a final outcome; hold before that.
+			return event.kind === "send-final" ? release() : hold();
+		case "release-after-spawn-observation":
+			// Fable 3: spawn-started is NOT a release event. Release on the first
+			// observed transition (socket-alive / child-exited, any code), or on a
+			// failed start (no child to watch).
+			switch (event.kind) {
+				case "socket-alive":
+				case "child-exited":
+				case "spawn-start-failed":
+					return release();
+				case "spawn-started":
+				case "send-final":
+				case "mailbox-enqueued":
+					return hold();
+			}
+	}
+}

package/pi-extensions/lib/entwurf-v2-resume-marker.ts

@@ -0,0 +1,34 @@
+/**
+ * entwurf-v2-resume-marker — the single source of truth for the env var name that a v2
+ * spawn-bg resume plants on its resume child to authorize it as an Entwurf-child resident.
+ *
+ * Why its own leaf module (no imports): the PRODUCER is `entwurf-v2-spawn-production.ts` (a
+ * lib module that imports siblings with `.ts` extensions, compiled by `scripts/tsconfig.json`
+ * with `allowImportingTsExtensions`), but the CONSUMER is `entwurf-control.ts` (the extension
+ * entry, compiled by the ROOT tsconfig WITHOUT that flag, importing siblings as `.js`).
+ * Importing the const straight from `entwurf-v2-spawn-production.ts` into `entwurf-control.ts`
+ * would drag the whole `.ts`-importing v2 decider/spawn subtree into the root program and
+ * trip TS5097 on every `.ts` extension. A zero-import leaf const is root-safe from either side.
+ *
+ * Meaning: when this env var equals the child's own sessionId, the child is the resume citizen
+ * a v2 spawn-bg resume promoted from a dormant `entwurf`-tagged session to a live
+ * `--entwurf-control` resident (an AUTHORIZED Entwurf child resident — keeps its `entwurf` tag,
+ * stays re-resumable once it dies). A human hand-opening the same session with
+ * `--entwurf-control` carries no marker → still a "corrupt resident session name" crash. The
+ * marker is sessionId-bound (not a generic boolean) so it authorizes only the exact session it
+ * was minted for; it is a wrong-surface crash guard, not a security boundary. See
+ * `entwurf-control.ts` `maybeSetResidentName` (consumer) and `entwurf-v2-spawn-production.ts`
+ * `makeProductionSpawnBgResumeDeps` (producer).
+ */
+export const V2_RESUME_RESIDENT_SESSION_ENV = "ENTWURF_V2_RESUME_RESIDENT_SESSION_ID";
+
+/**
+ * True when this process is the resume child a v2 spawn-bg resume launched for EXACTLY
+ * `sessionId` — the marker equals the child's own id. The pure SSOT of the authorization
+ * check (`env` is injectable so the guard is gate-provable without touching `process.env`).
+ * The binding is to the exact id, not a generic boolean: a present-but-different marker is
+ * NOT authorized, so the env var cannot be reused to wave a different session past the guard.
+ */
+export function isV2ResumeResidentAuthorized(sessionId: string, env: NodeJS.ProcessEnv = process.env): boolean {
+	return env[V2_RESUME_RESIDENT_SESSION_ENV] === sessionId;
+}