@junghanacs/entwurf 0.12.0

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

@@ -0,0 +1,337 @@
+/**
+ * entwurf-v2-spawn-production — the PRODUCTION `SpawnBgResumeDeps` factory for the 5c-3a
+ * spawn-bg watcher (0.11 Stage 0 step 5c-3c). It wires the six injected IO seams the pure
+ * watcher (`executeSpawnBgResume`) declares onto the real world: spawn a resume child as a
+ * resident citizen, observe its control socket by CONNECTABILITY (not mere existence),
+ * watch its exit, time the observe window, and kill on timeout. The watcher's release
+ * policy is untouched — this module only supplies the IO.
+ *
+ * Every seam stays injectable (defaults = the real fns) so a DETERMINISTIC gate drives
+ * spawnChild's argv, the exit/timeout/kill wiring, and the socket-alive verdict WITHOUT a
+ * real pi spawn or socket — the heavy live path (a real `pi --entwurf-control` resident
+ * child + a real unix-socket connect) is proven once by a separate opt-in smoke
+ * (`smoke-entwurf-v2-spawn-live`), kept OUT of `pnpm check` so the every-commit loop stays
+ * fast and deterministic (D5: chain = deterministic gate; live smoke = phase gate before 5d).
+ *
+ * The factory does NOT capture `plan` or `lock` (D3): `SpawnBgResumeDeps.spawnChild(plan)`
+ * already takes the plan, and the lock is the watcher's authority — it flows to
+ * `deps.releaseLock` from the watcher, never from here. A captured plan/lock would be a
+ * second authority that could drift from the one the watcher holds.
+ *
+ * socket-alive = CONNECTABLE, never file-exists (GPT 5c-3c, Q5): inspect the EXACT
+ * `plan.expectedSocketPath` (via the path-addressed `inspectControlSocketPath` — no gid
+ * re-derivation), map to liveness through the shared `mapInspectionToLiveness`, then apply
+ * `socketWatchVerdict`: a connectable socket is alive; a forged address (symlink / not a
+ * socket) is rejected IMMEDIATELY (time does not heal a forged path → the watcher's backstop
+ * kills and fail-closes to a retained lock); a dead/indeterminate socket keeps waiting (the
+ * dormant citizen's stale socket file, or a stall, is "not up yet", not a failure).
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import * as fs from "node:fs/promises";
+import {
+	findSessionFileById,
+	getEntwurfExplicitExtensions,
+	mirrorChildStderr,
+	readSessionIdentity,
+} from "./entwurf-core.ts";
+import { buildResumePiArgs } from "./entwurf-resume-args.ts";
+import type { LockClaim } from "./entwurf-v2-lock.ts";
+import { releaseLock } from "./entwurf-v2-lock.ts";
+import { V2_RESUME_RESIDENT_SESSION_ENV } from "./entwurf-v2-resume-marker.ts";
+import type { SpawnBgPlan, SpawnBgResumeDeps, SpawnedChild } from "./entwurf-v2-spawn.ts";
+import { inspectControlSocketPath, type LstatLike, mapInspectionToLiveness } from "./socket-discovery.ts";
+import { probeSocketLiveness, type SocketLiveness } from "./socket-probe.ts";
+
+// ── socketWatchVerdict (pure — the R2 watch policy, gate-pinned) ──────────────
+export type SocketWatchVerdict = "alive" | "wait" | "forged";
+
+/**
+ * Translate a mapped socket observation into the watcher's poll decision.
+ *   - forged  — an address-conflict (symlink / not-a-socket). NOT a transient liveness
+ *     state: time cannot turn a forged path into a live socket, so the poll must REJECT
+ *     immediately (→ watcher backstop → kill → retained), never keep waiting.
+ *   - alive   — a connectable socket. Resolve: the resumed citizen is up.
+ *   - wait    — dead (the dormant citizen's stale/absent socket — "not up yet") or
+ *     indeterminate (a stall). Keep polling until the socket connects, or the observe
+ *     timeout / abort ends the wait.
+ */
+export function socketWatchVerdict(
+	mapped: { liveness: SocketLiveness; socketPath: string } | { addressConflict: true },
+): SocketWatchVerdict {
+	if ("addressConflict" in mapped) return "forged";
+	return mapped.liveness === "alive" ? "alive" : "wait";
+}
+
+// ── the spawned child handle (D4) ────────────────────────────────────────────
+// A minimal structural view of the process the deps share. The real ChildProcess
+// satisfies it; the gate fakes it. The watcher sees only `pid` (SpawnedChild); the
+// production deps carry `proc` so awaitChildExit / killChild act on the SAME process.
+export interface SpawnedProcHandle {
+	pid?: number;
+	kill(signal?: NodeJS.Signals | number): boolean;
+	on(event: string, listener: (...args: unknown[]) => void): unknown;
+	removeListener(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+
+interface ProductionSpawnedChild extends SpawnedChild {
+	proc: SpawnedProcHandle;
+	/** Exit captured EAGERLY at proc creation (B2): the `exit` listener is installed the
+	 * instant the proc exists, BEFORE the watcher's awaitChildExit runs, so a child that
+	 * exits in the micro-gap between spawnChild resolving and awaitChildExit registering is
+	 * never missed (which would pin the lock through timeout→kill→retained). Resolve-ONLY
+	 * (never rejects) so it is safe to leave racing an abort in awaitChildExit. */
+	exitPromise: Promise<number | null>;
+}
+
+/** Narrow a watcher-supplied SpawnedChild back to the production handle. A child that is
+ * NOT one we spawned (no `proc` / `exitPromise`) is a mis-wire — fail loud, never no-op. */
+function requireProductionChild(child: SpawnedChild): ProductionSpawnedChild {
+	const c = child as Partial<ProductionSpawnedChild>;
+	if (!c.proc || !c.exitPromise) {
+		throw new Error("entwurf-v2-spawn-production: child handle has no proc/exitPromise (mis-wired SpawnBgResumeDeps).");
+	}
+	return c as ProductionSpawnedChild;
+}
+
+// ── launch identity (the spawnChild preamble, one injectable seam) ───────────
+/** The launch-time facts buildResumePiArgs needs, resolved from the saved session. The
+ * default reads them the SAME way the legacy resume launcher does (header authority); the
+ * gate injects a fake so spawnChild's argv is provable without a real session file. */
+export interface LaunchIdentity {
+	cwd: string;
+	explicitExtensionArgs: readonly string[];
+	provider: string | null | undefined;
+	model: string;
+}
+
+/**
+ * Resolve launch identity for a resume from the saved session — the same authority the
+ * legacy launcher uses (readSessionIdentity = first model_change; getEntwurfExplicitExtensions
+ * = bridge re-injection / #29 fail-fast), MINUS the legacy completion-delivery tail (that is
+ * 5d). Throws on anything that makes a resume impossible — no session file, no recorded
+ * model, an unresolvable ACP bridge, or no header cwd (NEVER falls back to process.cwd, #9).
+ * Each throw becomes the watcher's `spawn-start-failed` (no child to watch → release).
+ */
+export function resolveResumeLaunchIdentity(plan: SpawnBgPlan): LaunchIdentity {
+	const sessionFile = findSessionFileById(plan.sessionId);
+	if (!sessionFile) {
+		throw new Error(`entwurf-v2-spawn-production: no saved session for ${plan.sessionId} — cannot resume.`);
+	}
+	const identity = readSessionIdentity(sessionFile, { requireEntwurf: true });
+	const resumeModel = identity?.modelId ?? null;
+	if (!identity || !resumeModel) {
+		throw new Error(`entwurf-v2-spawn-production: ${plan.sessionId} has no recorded model — cannot resume.`);
+	}
+	const explicitExtensions = getEntwurfExplicitExtensions(resumeModel, false, identity.provider);
+	if (explicitExtensions.unresolvedAcpIntent) {
+		throw new Error(
+			`entwurf-v2-spawn-production: ${plan.sessionId} recorded provider=entwurf but the bridge ` +
+				`extension could not be resolved — refusing to resume with an unknown provider (#29).`,
+		);
+	}
+	if (!identity.cwd) {
+		throw new Error(
+			`entwurf-v2-spawn-production: ${plan.sessionId} header has no cwd (the cold-resume authority, #9).`,
+		);
+	}
+	return {
+		cwd: identity.cwd,
+		explicitExtensionArgs: explicitExtensions.args,
+		provider: explicitExtensions.provider ?? identity.provider,
+		model: explicitExtensions.modelOverride ?? resumeModel,
+	};
+}
+
+// ── the injectable seams (defaults = the real world) ─────────────────────────
+export interface ProductionSpawnOpts {
+	/** Poll interval for awaitSocketAlive's wait loop (ms). */
+	pollIntervalMs?: number;
+	/** Bounded wait, after a kill, for the resulting child-exited (the watcher's killGraceMs). */
+	killGraceMs?: number;
+	/** Connect-probe timeout for a socket-file inspection (ms). */
+	probeTimeoutMs?: number;
+	/** Resolve launch identity (default = resolveResumeLaunchIdentity). */
+	resolveIdentity?: (plan: SpawnBgPlan) => LaunchIdentity;
+	/** Spawn the resume child and return its handle (default = real `pi` spawn + unref +
+	 * mirrorChildStderr). `env` carries the v2 spawn-bg resume marker (V2_RESUME_RESIDENT_SESSION_ENV)
+	 * the factory plants so the resumed `--entwurf-control` resident is an AUTHORIZED Entwurf child,
+	 * not a corrupt operator resident. A throw becomes the watcher's spawn-start-failed. */
+	spawnChild?: (cmd: string, args: readonly string[], cwd: string, env: NodeJS.ProcessEnv) => SpawnedProcHandle;
+	/** lstat for socket inspection (default = fs.lstat). */
+	lstatFn?: (p: string) => Promise<LstatLike>;
+	/** Connect probe for a socket-file (default = probeSocketLiveness). */
+	probeFn?: (socketPath: string) => Promise<SocketLiveness>;
+	/** Release the held lock (default = the lock primitive's releaseLock). */
+	releaseFn?: (lock: LockClaim) => void;
+	/** Timer primitives (default = global setTimeout/clearTimeout) — injected so the gate
+	 * proves scheduling + abort-clear deterministically. */
+	setTimeoutFn?: (cb: () => void, ms: number) => ReturnType<typeof setTimeout>;
+	clearTimeoutFn?: (t: ReturnType<typeof setTimeout>) => void;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 150;
+const DEFAULT_KILL_GRACE_MS = 5_000;
+
+/** The default spawnChild: a detached, unref'd `pi` resident child with stderr mirrored —
+ * the same launch posture as the legacy worker, minus `--no-extensions` (the argv comes
+ * from buildResumePiArgs v2-control). Detached so the resumed citizen survives this parent. */
+function defaultSpawnChild(
+	cmd: string,
+	args: readonly string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv,
+): SpawnedProcHandle {
+	const proc: ChildProcess = spawn(cmd, [...args], {
+		cwd,
+		shell: false,
+		detached: true,
+		stdio: ["ignore", "ignore", "pipe"],
+		env,
+	});
+	proc.unref();
+	mirrorChildStderr(proc);
+	return proc;
+}
+
+/**
+ * Build the production `SpawnBgResumeDeps` the 5c-3a watcher consumes. The factory captures
+ * NO plan and NO lock (D3) — both flow through the watcher. Pass `opts` to inject fakes for
+ * the deterministic gate; the defaults are the real IO.
+ */
+export function makeProductionSpawnBgResumeDeps(opts: ProductionSpawnOpts = {}): SpawnBgResumeDeps {
+	const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	const killGraceMs = opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+	const resolveIdentity = opts.resolveIdentity ?? resolveResumeLaunchIdentity;
+	const spawnChildFn = opts.spawnChild ?? defaultSpawnChild;
+	const lstatFn = opts.lstatFn ?? ((p: string) => fs.lstat(p));
+	const probeFn =
+		opts.probeFn ?? ((socketPath: string) => probeSocketLiveness(socketPath, { timeoutMs: opts.probeTimeoutMs }));
+	const releaseFn = opts.releaseFn ?? ((lock: LockClaim) => void releaseLock(lock));
+	const setTimeoutFn = opts.setTimeoutFn ?? ((cb, ms) => setTimeout(cb, ms));
+	const clearTimeoutFn = opts.clearTimeoutFn ?? ((t) => clearTimeout(t));
+
+	// An abortable delay: resolves after `ms`, or rejects on abort (clearing the timer). Used
+	// by both awaitTimeout (the observe/grace deadlines) and the socket poll's inter-poll sleep.
+	const abortableDelay = (ms: number, signal: AbortSignal): Promise<void> =>
+		new Promise<void>((resolve, reject) => {
+			if (signal.aborted) {
+				reject(new Error("aborted"));
+				return;
+			}
+			const timer = setTimeoutFn(() => {
+				signal.removeEventListener("abort", onAbort);
+				resolve();
+			}, ms);
+			const onAbort = (): void => {
+				clearTimeoutFn(timer);
+				reject(new Error("aborted"));
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+		});
+
+	return {
+		killGraceMs,
+
+		spawnChild: async (plan: SpawnBgPlan): Promise<SpawnedChild> => {
+			const identity = resolveIdentity(plan);
+			const args = buildResumePiArgs({
+				variant: "v2-control",
+				sessionId: plan.sessionId,
+				explicitExtensionArgs: identity.explicitExtensionArgs,
+				provider: identity.provider,
+				model: identity.model,
+				prompt: plan.prompt,
+				launchArgs: plan.launchArgs,
+			});
+			// Plant the sessionId-bound authorization marker (QB-resident): this resume promotes a
+			// dormant `entwurf`-tagged session to a live `--entwurf-control` resident, which the
+			// entwurf-control guard would otherwise crash as a "corrupt resident session name". The
+			// marker authorizes ONLY this exact session — a human hand-opening the same session with
+			// `--entwurf-control` carries no marker and still crashes (the invariant is narrowed, not
+			// dropped). buildResumePiArgs's argv alone can't say "this is a v2 spawn-bg resume".
+			const childEnv: NodeJS.ProcessEnv = { ...process.env, [V2_RESUME_RESIDENT_SESSION_ENV]: plan.sessionId };
+			const proc = spawnChildFn("pi", args, identity.cwd, childEnv);
+
+			// B2: capture exit EAGERLY — the instant the proc exists, before we even await the
+			// spawn — so a fast exit cannot slip through the gap before awaitChildExit. Resolve-
+			// only (a signal kill reports null); it never rejects, so racing it against abort is safe.
+			const exitPromise = new Promise<number | null>((resolve) => {
+				proc.on("exit", (code: unknown) => resolve(typeof code === "number" ? code : null));
+			});
+
+			// B1: a started process is NOT guaranteed by `spawn()` returning — a spawn-time
+			// failure (ENOENT pi / exec error) arrives as an `error` event, not a sync throw. Wait
+			// for the `spawn` event to confirm a real start; an `error` before it rejects, which the
+			// watcher turns into spawn-start-failed (release, nothing to watch) — NOT a silent
+			// spawn-started that later stalls into a wrongful retained lock.
+			await new Promise<void>((resolve, reject) => {
+				const onSpawn = (): void => {
+					cleanup();
+					resolve();
+				};
+				const onError = (err: unknown): void => {
+					cleanup();
+					reject(err instanceof Error ? err : new Error(`spawn failed: ${String(err)}`));
+				};
+				const cleanup = (): void => {
+					proc.removeListener("spawn", onSpawn);
+					proc.removeListener("error", onError);
+				};
+				proc.on("spawn", onSpawn);
+				proc.on("error", onError);
+			});
+
+			const child: ProductionSpawnedChild = { pid: proc.pid, proc, exitPromise };
+			return child;
+		},
+
+		awaitSocketAlive: async (socketPath: string, signal: AbortSignal): Promise<void> => {
+			// Poll the EXACT path (no gid re-derivation). Connectable → resolve; forged →
+			// reject NOW; dead/indeterminate → wait one interval and re-poll, until abort.
+			while (!signal.aborted) {
+				const inspection = await inspectControlSocketPath(socketPath, lstatFn);
+				const mapped = await mapInspectionToLiveness(inspection, probeFn);
+				const verdict = socketWatchVerdict(mapped);
+				if (verdict === "alive") return;
+				if (verdict === "forged") {
+					throw new Error(
+						`entwurf-v2-spawn-production: forged control-socket address at ${socketPath} (never connected).`,
+					);
+				}
+				// wait — sleep one interval, honoring abort (rejects → loop exits below).
+				await abortableDelay(pollIntervalMs, signal);
+			}
+			throw new Error("entwurf-v2-spawn-production: awaitSocketAlive aborted before the socket became alive.");
+		},
+
+		awaitChildExit: (child: SpawnedChild, signal: AbortSignal): Promise<number | null> =>
+			// Race the EAGER exitPromise (installed at spawn, so a fast exit is already captured —
+			// B2) against abort. exitPromise is resolve-only, so the loser never surfaces as an
+			// unhandled rejection; only the abort branch rejects.
+			new Promise<number | null>((resolve, reject) => {
+				const { exitPromise } = requireProductionChild(child);
+				if (signal.aborted) {
+					reject(new Error("aborted"));
+					return;
+				}
+				const onAbort = (): void => reject(new Error("aborted"));
+				signal.addEventListener("abort", onAbort, { once: true });
+				exitPromise.then((code) => {
+					signal.removeEventListener("abort", onAbort);
+					resolve(code);
+				});
+			}),
+
+		awaitTimeout: (ms: number, signal: AbortSignal): Promise<void> => abortableDelay(ms, signal),
+
+		killChild: (child: SpawnedChild): void => {
+			// SIGTERM only this slice — the watcher's killGrace then waits for the resulting
+			// child-exited; if none arrives it returns lock-retained (a SIGKILL escalator is a
+			// separate policy + smoke). Best-effort: the watcher catches a throw here.
+			requireProductionChild(child).proc.kill("SIGTERM");
+		},
+
+		releaseLock: (lock: LockClaim): void => releaseFn(lock),
+	};
+}

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

@@ -0,0 +1,323 @@
+/**
+ * entwurf-v2-spawn — the 5c-3a spawn-bg RESUME watcher hand (0.11 Stage 0 step 5c-3a).
+ * It WIRES the real spawn + socket-observe IO onto the pure release reducer (5c-1):
+ * launch the resume child, watch for the FIRST observable liveness transition, feed
+ * that observation to `reduceRelease`, and release the held lock EXACTLY ONCE — or, if
+ * NO observation can be obtained, RETAIN the lock and surface the evidence rather than
+ * release blind. Every IO seam is an injected dep (the gate fakes it with controlled
+ * promises), so the spawn→observe→release ORDERING is gate-provable without a real
+ * child, socket, or timer — the same "pure-before-IO, IO-via-dep" discipline 5b/5c-2
+ * used.
+ *
+ * The load-bearing contract (Fable 3, the whole reason 5c is sliced pure-before-IO):
+ *   TIMEOUT IS NOT A RELEASE EVENT. A spawn-bg dispatch holds its per-gid lock until an
+ *   OBSERVED transition — `socket-alive` (the resumed child stood its control socket up)
+ *   or `child-exited` (any code, incl. null = killed by signal). A bare `observeTimeoutMs`
+ *   expiry proves NOTHING (the child may stand its socket up a moment later), so releasing
+ *   on it would reopen the exact double-spawn window 5a's lock exists to close. Instead the
+ *   timeout RESOLVES BY OBSERVATION: kill the child, then wait a BOUNDED `killGraceMs` for
+ *   the kill to produce a real `child-exited` (or a racing `socket-alive`). Only THAT
+ *   observation releases. If even the grace elapses with no observation, the hand does NOT
+ *   release — it returns a `lock-retained` diagnostic (released:false, with pid / socket /
+ *   lockPath / timeouts) so an operator can SEE the long-held lock, exactly as F2-P2
+ *   ("관측 가능해야 수용") demands. The function always returns BOUNDED — it never hangs.
+ *
+ * Post-spawn unexpected dep failure follows the SAME rule (GPT 5c-3a correction): once a
+ * child exists, an observation-less release is forbidden. A watch/timer/kill dep that
+ * throws is handled by best-effort kill → bounded attempt to OBSERVE the exit → release
+ * if observed, else `lock-retained` fail-closed. There is NO direct-release escape hatch:
+ * `deps.releaseLock` is reached ONLY through `reduceRelease` on a real observation event.
+ *
+ * Release authority is ALWAYS the LockClaim the decider handed over; the watcher reads
+ * ONLY `plan.expectedSocketPath` and never re-derives a socket path or a lock by gid.
+ */
+
+import type { ExecutionPlan } from "./entwurf-v2-decider.ts";
+import type { LockClaim } from "./entwurf-v2-lock.ts";
+import {
+	decideReleasePolicy,
+	initialReleaseState,
+	type ReleaseEvent,
+	type ReleasePolicy,
+	type ReleaseState,
+	reduceRelease,
+} from "./entwurf-v2-release.ts";
+
+/** The spawn-bg plan shape, narrowed from the decider's ExecutionPlan union. */
+export type SpawnBgPlan = Extract<ExecutionPlan, { transport: "spawn-bg" }>;
+
+/** A started resume child. `pid` is diagnostic-only (surfaced on a retained lock); the
+ * watcher tracks the child by this opaque handle, never by gid. */
+export interface SpawnedChild {
+	pid?: number;
+}
+
+/**
+ * Every IO seam is a REQUIRED dep — the hand performs ZERO IO of its own so the gate can
+ * drive every observation order without a real spawn/socket/timer.
+ *   - spawnChild       — launch the resume child. Resolves a handle on a STARTED process;
+ *     THROWS on a spawn-time failure (→ `spawn-start-failed`: no child to watch).
+ *   - awaitSocketAlive — resolve when `expectedSocketPath` becomes observable (the child
+ *     stood its control socket up). NEVER resolves if the socket never appears — the
+ *     timeout path handles that. Honors the abort signal so a loser can be torn down.
+ *   - awaitChildExit   — resolve with the child's exit code (null = killed by signal).
+ *     Honors the abort signal.
+ *   - awaitTimeout     — resolve after `ms` (the observe deadline, and again the kill
+ *     grace). Honors the abort signal. NOTE: a timeout is NEVER fed to the reducer.
+ *   - killChild        — terminate the started child. Used ONLY to escalate a timeout (or
+ *     a post-spawn dep failure) into a real `child-exited`; it is never a release itself.
+ *   - releaseLock      — release the held claim; reached ONLY via reduceRelease, at most
+ *     once, only on a real observation event.
+ *   - killGraceMs      — bounded wait, after a kill, for the resulting observation. Keeps
+ *     the watcher from hanging on a zombie: if it elapses, the lock is RETAINED (surfaced),
+ *     not released. A watcher-policy constant (NOT a routing decision — so it lives on the
+ *     dep, not the decider's plan).
+ */
+export interface SpawnBgResumeDeps {
+	spawnChild: (plan: SpawnBgPlan) => Promise<SpawnedChild>;
+	awaitSocketAlive: (socketPath: string, signal: AbortSignal) => Promise<void>;
+	awaitChildExit: (child: SpawnedChild, signal: AbortSignal) => Promise<number | null>;
+	awaitTimeout: (ms: number, signal: AbortSignal) => Promise<void>;
+	killChild: (child: SpawnedChild) => void;
+	releaseLock: (lock: LockClaim) => void;
+	killGraceMs: number;
+}
+
+/** Evidence carried on a `lock-retained` outcome so an operator can SEE (and clear) the
+ * lock that no observation released. */
+export interface SpawnRetainedDiagnostic {
+	targetGardenId: string;
+	pid?: number;
+	expectedSocketPath: string;
+	lockPath: string;
+	observeTimeoutMs: number;
+	killGraceMs: number;
+}
+
+/**
+ * The terminal outcome of a spawn-bg resume watch. The three RELEASED outcomes each fed
+ * exactly one observation event to the reducer; the `lock-retained` outcome fed NONE (it
+ * is the observation-less fail-closed — `released:false`, lock left for the operator).
+ *   - socket-alive       — the resumed child stood its socket up.
+ *   - child-exited        — the child exited (any code; null = signal/kill).
+ *   - spawn-start-failed  — the child never started (spawnChild threw); nothing to watch.
+ *   - lock-retained       — no observation was obtainable (kill grace elapsed, or a
+ *     post-spawn dep failed and the exit could not be observed). Lock NOT released.
+ */
+export type SpawnBgResumeResult =
+	| { kind: "socket-alive"; released: true; pid?: number }
+	| { kind: "child-exited"; released: true; exitCode: number | null; pid?: number }
+	| { kind: "spawn-start-failed"; released: true; error: string }
+	| {
+			kind: "lock-retained";
+			released: false;
+			reason: "kill-unconfirmed" | "observe-failed";
+			error?: string;
+			diagnostic: SpawnRetainedDiagnostic;
+	  };
+
+// An internal tag for the observation race: which source settled first.
+type Observation = { tag: "socket" } | { tag: "exit"; code: number | null } | { tag: "timeout" };
+
+function tagSocket(p: Promise<void>): Promise<Observation> {
+	return p.then(() => ({ tag: "socket" }) as const);
+}
+function tagExit(p: Promise<number | null>): Promise<Observation> {
+	return p.then((code) => ({ tag: "exit", code }) as const);
+}
+function tagTimeout(p: Promise<void>): Promise<Observation> {
+	return p.then(() => ({ tag: "timeout" }) as const);
+}
+
+function errMsg(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+/** Swallow a watcher promise's eventual rejection when it is abandoned without a race
+ * handler (the S1 sync-throw path tears down before the race attaches one), so an aborted
+ * loser cannot surface as an unhandledRejection. A no-op when the promise never started. */
+function defuse(p: Promise<unknown> | undefined): void {
+	if (p) void p.catch(() => {});
+}
+
+/**
+ * Launch a spawn-bg resume child and watch for the first observable liveness transition,
+ * releasing the held lock EXACTLY ONCE on that observation — or RETAINING the lock (with
+ * surfaced evidence) if no observation can be obtained. `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). Always returns bounded.
+ *
+ * A `releaseLock` throw on a RELEASED path propagates honestly (the observation already
+ * happened, so the caller must NOT re-spawn; the lock is dirty and needs manual cleanup —
+ * 5b masking direction). Such a throw is the ONE non-result exit; every other terminal
+ * state is a returned `SpawnBgResumeResult`.
+ */
+export async function executeSpawnBgResume(
+	plan: SpawnBgPlan,
+	lock: LockClaim | null,
+	deps: SpawnBgResumeDeps,
+): Promise<SpawnBgResumeResult> {
+	// Throws on a null / mis-paired lock (？7 + gid invariants). After this the spawn-bg
+	// policy is release-after-spawn-observation and the lock is non-null.
+	const policy: ReleasePolicy = decideReleasePolicy(plan, lock);
+	const held = lock as LockClaim;
+
+	let state: ReleaseState = initialReleaseState();
+	// The ONLY path to deps.releaseLock: fold a real observation event through the reducer
+	// and release iff (and exactly once) the reducer says so. No direct-release hatch.
+	const fire = (event: ReleaseEvent): void => {
+		const r = reduceRelease(policy, state, event);
+		state = r.state;
+		if (r.shouldRelease) deps.releaseLock(held);
+	};
+
+	// Spawn. A throw here means NO child exists → spawn-start-failed releases (nothing to
+	// watch; keeping the lock would pin the gid forever). No child means no lock-leak risk.
+	let child: SpawnedChild;
+	try {
+		child = await deps.spawnChild(plan);
+	} catch (err) {
+		fire({ kind: "spawn-start-failed", error: errMsg(err) });
+		return { kind: "spawn-start-failed", released: true, error: errMsg(err) };
+	}
+
+	const controller = new AbortController();
+	const { signal } = controller;
+	// Created ONCE and reused across the primary race and the kill-grace race; in the
+	// timeout branch both are still pending (timeout won), so re-racing them is safe.
+	//
+	// S1 (Fable 2차): the creation is in its OWN try because a watch dep can throw
+	// SYNCHRONOUSLY (a buggy dep that throws where it must RETURN a Promise — the same grade
+	// the send hand's case-13 backstop covers). The child already exists, so this is a
+	// post-spawn failure and the SAME rule applies: an observation-less release is forbidden.
+	// Best-effort kill, defuse any watcher that DID start (so its later rejection is not
+	// unhandled), tear down, and fail-closed to a retained diagnostic. We do NOT try to
+	// observe the exit — awaitChildExit may itself be the thrower; retained is the honest
+	// floor. (The async-rejection path is handled later by the race catch → backstop.)
+	let socketP!: Promise<Observation>;
+	let exitP!: Promise<Observation>;
+	try {
+		socketP = tagSocket(deps.awaitSocketAlive(plan.expectedSocketPath, signal));
+		exitP = tagExit(deps.awaitChildExit(child, signal));
+	} catch (err) {
+		try {
+			deps.killChild(child);
+		} catch {
+			// best-effort
+		}
+		controller.abort();
+		defuse(socketP);
+		defuse(exitP);
+		return retained(plan, child, "observe-failed", deps.killGraceMs, held.lockPath, errMsg(err));
+	}
+
+	try {
+		// Primary observation race. `timeout` participates but is NEVER a release event.
+		let first: Observation;
+		try {
+			const timeoutP = tagTimeout(deps.awaitTimeout(plan.observeTimeoutMs, signal));
+			first = await Promise.race([socketP, exitP, timeoutP]);
+		} catch (err) {
+			// A watch/timer dep rejected BEFORE any observation → post-spawn backstop.
+			return await backstop(plan, deps, child, held.lockPath, exitP, signal, fire, errMsg(err));
+		}
+
+		if (first.tag === "socket") {
+			fire({ kind: "socket-alive" });
+			return { kind: "socket-alive", released: true, pid: child.pid };
+		}
+		if (first.tag === "exit") {
+			fire({ kind: "child-exited", code: first.code });
+			return { kind: "child-exited", released: true, exitCode: first.code, pid: child.pid };
+		}
+
+		// first.tag === "timeout": NOT a release. Escalate to a kill, then wait a BOUNDED
+		// grace for the kill to produce a real child-exited (or a racing socket-alive).
+		try {
+			deps.killChild(child);
+		} catch {
+			// kill itself threw — still try to observe within the grace; if nothing, retain.
+		}
+		let second: Observation;
+		try {
+			const graceP = tagTimeout(deps.awaitTimeout(deps.killGraceMs, signal));
+			second = await Promise.race([socketP, exitP, graceP]);
+		} catch (err) {
+			// A dep rejected during the grace → cannot confirm; retain the lock, surface it.
+			return retained(plan, child, "kill-unconfirmed", deps.killGraceMs, held.lockPath, errMsg(err));
+		}
+		if (second.tag === "socket") {
+			fire({ kind: "socket-alive" });
+			return { kind: "socket-alive", released: true, pid: child.pid };
+		}
+		if (second.tag === "exit") {
+			fire({ kind: "child-exited", code: second.code });
+			return { kind: "child-exited", released: true, exitCode: second.code, pid: child.pid };
+		}
+		// Grace elapsed with NO observation → the kill is unconfirmed. Do NOT release blind;
+		// retain the lock and surface the evidence (bounded return, never a hang).
+		return retained(plan, child, "kill-unconfirmed", deps.killGraceMs, held.lockPath, undefined);
+	} finally {
+		// Tear down the losing watchers (their timers / FS watches) on every exit.
+		controller.abort();
+	}
+}
+
+/**
+ * Post-spawn backstop (GPT 5c-3a correction): a child exists but a watch/timer dep threw
+ * before any observation. An observation-less release is forbidden (it reopens the
+ * double-spawn window), so: best-effort kill → BOUNDED attempt to OBSERVE the exit →
+ * release iff observed, else `lock-retained` fail-closed. We race ONLY the exit (not the
+ * already-suspect socket watcher) plus a fresh grace timer.
+ */
+async function backstop(
+	plan: SpawnBgPlan,
+	deps: SpawnBgResumeDeps,
+	child: SpawnedChild,
+	lockPath: string,
+	exitP: Promise<Observation>,
+	signal: AbortSignal,
+	fire: (event: ReleaseEvent) => void,
+	originalError: string,
+): Promise<SpawnBgResumeResult> {
+	try {
+		deps.killChild(child);
+	} catch {
+		// best-effort
+	}
+	try {
+		const graceP = tagTimeout(deps.awaitTimeout(deps.killGraceMs, signal));
+		const obs = await Promise.race([exitP, graceP]);
+		if (obs.tag === "exit") {
+			fire({ kind: "child-exited", code: obs.code });
+			return { kind: "child-exited", released: true, exitCode: obs.code, pid: child.pid };
+		}
+	} catch {
+		// exit watcher itself was the failing dep (or threw again) → fall through to retain.
+	}
+	return retained(plan, child, "observe-failed", deps.killGraceMs, lockPath, originalError);
+}
+
+function retained(
+	plan: SpawnBgPlan,
+	child: SpawnedChild,
+	reason: "kill-unconfirmed" | "observe-failed",
+	killGraceMs: number,
+	lockPath: string,
+	error: string | undefined,
+): SpawnBgResumeResult {
+	return {
+		kind: "lock-retained",
+		released: false,
+		reason,
+		error,
+		diagnostic: {
+			targetGardenId: plan.targetGardenId,
+			pid: child.pid,
+			expectedSocketPath: plan.expectedSocketPath,
+			lockPath,
+			observeTimeoutMs: plan.observeTimeoutMs,
+			killGraceMs,
+		},
+	};
+}