@junghanacs/entwurf 0.13.1 → 0.14.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-spawn.js

@@ -1,216 +0,0 @@
-/**
- * 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 { decideReleasePolicy, initialReleaseState, reduceRelease, } from "./entwurf-v2-release.js";
-function tagSocket(p) {
-    return p.then(() => ({ tag: "socket" }));
-}
-function tagExit(p) {
-    return p.then((code) => ({ tag: "exit", code }));
-}
-function tagTimeout(p) {
-    return p.then(() => ({ tag: "timeout" }));
-}
-function errMsg(err) {
-    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) {
-    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, lock, deps) {
-    // 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 = decideReleasePolicy(plan, lock);
-    const held = lock;
-    let state = 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) => {
-        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;
-    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;
-    let exitP;
-    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;
-        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;
-        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, deps, child, lockPath, exitP, signal, fire, originalError) {
-    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, child, reason, killGraceMs, lockPath, error) {
-    return {
-        kind: "lock-retained",
-        released: false,
-        reason,
-        error,
-        diagnostic: {
-            targetGardenId: plan.targetGardenId,
-            pid: child.pid,
-            expectedSocketPath: plan.expectedSocketPath,
-            lockPath,
-            observeTimeoutMs: plan.observeTimeoutMs,
-            killGraceMs,
-        },
-    };
-}

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

@@ -1,373 +0,0 @@
-/**
- * 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 { existsSync } from "node:fs";
-import * as fs from "node:fs/promises";
-import { 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 type { SpawnBgPlan, SpawnBgResumeDeps, SpawnedChild } from "./entwurf-v2-spawn.ts";
-import { readAddressableMetaIdentity } from "./meta-session.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 meta-record + the
- * recorded transcript (record authority, #50 C2/C3); the gate injects a fake so
- * spawnChild's argv is provable without a real session file. */
-export interface LaunchIdentity {
-	/** The EXACT session JSONL to resume — `pi --session <path>`. */
-	sessionFile: string;
-	cwd: string;
-	explicitExtensionArgs: readonly string[];
-	provider: string | null | undefined;
-	model: string;
-}
-
-/**
- * Resolve launch identity for a resume. The TARGET is now resolved through the
- * meta-record (#50 C2): `gardenId → record.transcriptPath`. It used to be a global
- * header scan for a JSONL whose header id equalled the garden id — which only worked
- * while entwurf forced pi's session id to BE the garden id. With the record minting the
- * address, that scan cannot find anything (a citizen's header carries pi's own uuid), so
- * keeping it would not have been a "smaller change", it would have been a broken one.
- *
- * The record is also the AUTHORIZATION now (#50 C3). The old gates — `requireEntwurf`
- * (an `entwurf` tag in the session NAME, planted by a name mirror that no longer
- * exists) and the sessionId-bound resume-marker env — are deleted. Record-backed pi
- * citizens are all siblings (LOCKED PROTOCOL 6), so "this garden id names a pi citizen
- * with a recorded transcript" is the whole test, PLUS one integrity check: the resumed
- * file's header id must equal `record.nativeSessionId` (pi owns the transcript, the
- * record remembers whose it is — a mismatch means the transcriptPath is stale or
- * foreign, and resuming it would put a turn into a different being's session).
- *
- * That check is per-record, and per-record is not enough: the v2 lock domain is keyed on
- * GARDEN ID, so two records sharing one `nativeSessionId` would each pass their own
- * integrity check and resume the SAME transcript concurrently under two different locks.
- * Hence {@link readAddressableMetaIdentity} rather than the plain targeted read (#52) —
- * a resume is exactly the moment a record stops being data and becomes an address.
- *
- * Everything else is unchanged authority: readSessionIdentity (first model_change) for
- * provider/model/cwd, getEntwurfExplicitExtensions for bridge re-injection (#29 fail-fast).
- * Throws on anything that makes a resume impossible; each throw becomes the watcher's
- * `spawn-start-failed` (no child to watch → release), never a silent no-op.
- */
-export function resolveResumeLaunchIdentity(plan: SpawnBgPlan): LaunchIdentity {
-	const record = readAddressableMetaIdentity(plan.sessionId);
-	if (record.backend !== "pi") {
-		throw new Error(
-			`entwurf-v2-spawn-production: ${plan.sessionId} is a ${record.backend} citizen — ` +
-				`spawn-bg resume is a host-adapter capability, and its domain currently contains backend pi only. ` +
-				`This is a relaunch capability, not the control-socket rail and not citizen rank.`,
-		);
-	}
-	const sessionFile = record.transcriptPath;
-	if (!sessionFile) {
-		throw new Error(
-			`entwurf-v2-spawn-production: ${plan.sessionId} has no recorded transcriptPath — ` +
-				`the citizen never wrote a session file (no turn yet), so there is nothing to resume.`,
-		);
-	}
-	// A recorded path is only a resume target while the file is actually on disk.
-	// Without this check a missing transcript falls through readSessionIdentity's
-	// ENOENT swallow and surfaces as "no recorded model" — the wrong cause (F7):
-	// the transcript was deleted, or the record carries a phantom path minted
-	// before birth guarded on file existence.
-	if (!existsSync(sessionFile)) {
-		throw new Error(
-			`entwurf-v2-spawn-production: ${plan.sessionId} recorded transcriptPath "${sessionFile}" ` +
-				`does not exist on disk — the transcript was deleted, or the record carries a phantom ` +
-				`path from a pre-guard birth; nothing to resume.`,
-		);
-	}
-	const identity = readSessionIdentity(sessionFile);
-	const resumeModel = identity?.modelId ?? null;
-	if (!identity || !resumeModel) {
-		throw new Error(`entwurf-v2-spawn-production: ${plan.sessionId} has no recorded model — cannot resume.`);
-	}
-	if (identity.sessionId !== record.nativeSessionId) {
-		throw new Error(
-			`entwurf-v2-spawn-production: ${plan.sessionId} transcript header id "${identity.sessionId ?? "(none)"}" ` +
-				`does not match the record's nativeSessionId "${record.nativeSessionId}" — the recorded transcriptPath ` +
-				`is stale or points at a foreign session file; refusing to resume another being's transcript.`,
-		);
-	}
-	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 {
-		sessionFile,
-		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). The child inherits this process's env untouched — the resume-marker
-	 * env the factory used to plant died with the name-mirror guard it authorized (#50 C3).
-	 * A throw becomes the watcher's spawn-start-failed. */
-	spawnChild?: (cmd: string, args: readonly string[], cwd: string) => 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): SpawnedProcHandle {
-	const proc: ChildProcess = spawn(cmd, [...args], {
-		cwd,
-		shell: false,
-		detached: true,
-		stdio: ["ignore", "ignore", "pipe"],
-	});
-	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",
-				sessionFile: identity.sessionFile,
-				explicitExtensionArgs: identity.explicitExtensionArgs,
-				provider: identity.provider,
-				model: identity.model,
-				prompt: plan.prompt,
-				launchArgs: plan.launchArgs,
-			});
-			const proc = spawnChildFn("pi", args, identity.cwd);
-
-			// 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),
-	};
-}