@junghanacs/entwurf 0.12.0 → 0.12.2

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

@@ -0,0 +1,125 @@
+/**
+ * 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 { isLivenessSupported, resolveDispatch } from "./entwurf-v2-contract.js";
+import { defaultMetaMailboxDir, defaultMetaSessionsDir } from "./meta-session.js";
+import { mapInspectionToLiveness } from "./socket-discovery.js";
+/**
+ * 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, lock, deps) {
+    // 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/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-send.js

@@ -0,0 +1,184 @@
+/**
+ * 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 { decideReleasePolicy, initialReleaseState, reduceRelease, } from "./entwurf-v2-release.js";
+/**
+ * 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, lock, deps) {
+    // 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 = decideReleasePolicy(plan, lock);
+    const held = lock;
+    // 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;
+    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, lock, deps) {
+    let result;
+    try {
+        result = await deps.sendOverSocket(plan);
+    }
+    catch (err) {
+        const liveness = deps.classifyConnect(err?.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, lock, deps) {
+    let resolution;
+    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 {
+    finalizedOutcome;
+    releaseError;
+    constructor(finalizedOutcome, releaseError) {
+        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, deps, lock, drive) {
+    const initial = 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;
+}

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

@@ -0,0 +1,237 @@
+/**
+ * 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 { spawn } from "node:child_process";
+import * as fs from "node:fs/promises";
+import { findSessionFileById, getEntwurfExplicitExtensions, mirrorChildStderr, readSessionIdentity, } from "./entwurf-core.js";
+import { buildResumePiArgs } from "./entwurf-resume-args.js";
+import { releaseLock } from "./entwurf-v2-lock.js";
+import { V2_RESUME_RESIDENT_SESSION_ENV } from "./entwurf-v2-resume-marker.js";
+import { inspectControlSocketPath, mapInspectionToLiveness } from "./socket-discovery.js";
+import { probeSocketLiveness } from "./socket-probe.js";
+/**
+ * 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) {
+    if ("addressConflict" in mapped)
+        return "forged";
+    return mapped.liveness === "alive" ? "alive" : "wait";
+}
+/** 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) {
+    const c = child;
+    if (!c.proc || !c.exitPromise) {
+        throw new Error("entwurf-v2-spawn-production: child handle has no proc/exitPromise (mis-wired SpawnBgResumeDeps).");
+    }
+    return c;
+}
+/**
+ * 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) {
+    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,
+    };
+}
+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, args, cwd, env) {
+    const proc = 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 = {}) {
+    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) => fs.lstat(p));
+    const probeFn = opts.probeFn ?? ((socketPath) => probeSocketLiveness(socketPath, { timeoutMs: opts.probeTimeoutMs }));
+    const releaseFn = opts.releaseFn ?? ((lock) => 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, signal) => new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new Error("aborted"));
+            return;
+        }
+        const timer = setTimeoutFn(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeoutFn(timer);
+            reject(new Error("aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    return {
+        killGraceMs,
+        spawnChild: async (plan) => {
+            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 = { ...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((resolve) => {
+                proc.on("exit", (code) => 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((resolve, reject) => {
+                const onSpawn = () => {
+                    cleanup();
+                    resolve();
+                };
+                const onError = (err) => {
+                    cleanup();
+                    reject(err instanceof Error ? err : new Error(`spawn failed: ${String(err)}`));
+                };
+                const cleanup = () => {
+                    proc.removeListener("spawn", onSpawn);
+                    proc.removeListener("error", onError);
+                };
+                proc.on("spawn", onSpawn);
+                proc.on("error", onError);
+            });
+            const child = { pid: proc.pid, proc, exitPromise };
+            return child;
+        },
+        awaitSocketAlive: async (socketPath, signal) => {
+            // 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, signal) => 
+        // 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((resolve, reject) => {
+            const { exitPromise } = requireProductionChild(child);
+            if (signal.aborted) {
+                reject(new Error("aborted"));
+                return;
+            }
+            const onAbort = () => reject(new Error("aborted"));
+            signal.addEventListener("abort", onAbort, { once: true });
+            exitPromise.then((code) => {
+                signal.removeEventListener("abort", onAbort);
+                resolve(code);
+            });
+        }),
+        awaitTimeout: (ms, signal) => abortableDelay(ms, signal),
+        killChild: (child) => {
+            // 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) => releaseFn(lock),
+    };
+}