@junghanacs/entwurf 0.12.0

package/scripts/smoke-entwurf-v2-matrix-live.ts

@@ -0,0 +1,398 @@
+/**
+ * smoke-entwurf-v2-matrix-live — the 5d-5 D4-b LIVE sentinel for the release-gate matrix.
+ *
+ * The deterministic sibling (check-entwurf-v2-matrix) drives the REAL decider over fakes with
+ * ZERO IO — it fixes every (target kind → transport → lock) cell as a table. This LIVE sentinel
+ * drives the REAL production `runEntwurfV2` deps against REAL OS objects on the substrate's
+ * happy path, to catch what fakes cannot: a real `pi --entwurf-control` control socket + RPC,
+ * a real lock acquire→release on disk, and a real mailbox enqueue. Negative/timeout/contention
+ * paths stay in the deterministic gate (GPT Q2/Q4) — this is "substrate still works", not a
+ * behavior suite.
+ *
+ * FOUR cells (GPT verdict — model-in-loop is OUT, this is a transport/lock/enqueue gate):
+ *   C1 control-socket — a real `pi --entwurf-control` resident (a pi citizen with a live
+ *      socket) → decider routes fire-and-forget/live to control-socket → real RPC send →
+ *      lock acquire→release ×1 → no lock garbage.
+ *   C1b socket-only (A1 narrow) — a real `pi --entwurf-control` resident with NO meta-record
+ *      (the operator-greeted record-less case) → resolveTarget promotes its live control socket
+ *      to a socket-only pi endpoint → fire-and-forget routes to control-socket (outcome=sent),
+ *      while owned-outcome on the SAME record-less target is refused (bad-target, no spawn).
+ *      This is the LIVE proof that closes the gap C1's hand-minted record was hiding.
+ *   C2 meta-mailbox (deliverable) — a self-fetch citizen (claude-code) with an ARMED receiver
+ *      marker → decider routes to meta-mailbox → a real `.msg` + signal is enqueued → lock-free
+ *      path (no lock file) → no garbage beyond the one message.
+ *   C3 meta-mailbox guard (undeliverable) — the SAME citizen kind but with NO armed receiver
+ *      (a terminated self-fetch session) → deliverability guard rejects (mailbox-undeliverable)
+ *      → NO `.msg` written (SE-2: no mailbox garbage for a dead receiver).
+ *
+ * Why programmatic, not model-in-loop (GPT Q2): "does the sender model actually call
+ * the dispatch verb (entwurf_v2)" is a SEPARATE behavior concern. Folding it in here
+ * would make a flaky model-tool-arg-variance failure indistinguishable from a bridge regression.
+ * So C2/C3 drive the production enqueue path directly; only C1 needs a real pi process (to prove
+ * the control socket + RPC are real, which fakes cannot).
+ *
+ * LIVE-only (spawns a real pi, opens a real socket) — kept OUT of `pnpm check`; honest skip when
+ * LIVE!=1 (a release-gate that hard-fails without auth/model is unrunnable unattended). Model:
+ *   ENTWURF_LIVE_TARGET   = "<provider>/<model>"  (default "openai-codex/gpt-5.4")
+ *   (or split: ENTWURF_LIVE_PROVIDER + ENTWURF_LIVE_MODEL)
+ *   LIVE=1 ./run.sh smoke-entwurf-v2-matrix-live
+ *
+ * Automation seams (GPT Q1): the resident child + its socket are always reaped in `finally`; a
+ * clean pass tears down the temp world while a failure PRESERVES it for post-mortem; fresh garden
+ * ids + temp dirs (no fixed session id → repeatable); staged timeouts (boot/observe); on failure
+ * a diagnostic block dumps the target id, socket/lock/mailbox paths, and the pi stderr tail.
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { SenderEnvelope } from "../pi-extensions/lib/entwurf-control-rpc.ts";
+import { generateSessionId } from "../pi-extensions/lib/entwurf-core.ts";
+import { lockPathFor } from "../pi-extensions/lib/entwurf-v2-lock.ts";
+import { makeProductionEntwurfV2Deps } from "../pi-extensions/lib/entwurf-v2-production.ts";
+import type { EntwurfV2RunResult } from "../pi-extensions/lib/entwurf-v2-runner.ts";
+import { runEntwurfV2 } from "../pi-extensions/lib/entwurf-v2-runner.ts";
+import {
+	metaRecordExistsByGardenId,
+	upsertMetaSession,
+	writeMetaReceiverMarker,
+} from "../pi-extensions/lib/meta-session.ts";
+import { terminateChild } from "./lib/acp-child-cleanup.ts";
+
+// pi's control socket lives at the canonical dir keyed by session id — pi owns this path, so
+// C1 must point the decider's controlSocketDir at the REAL dir (a fresh gid avoids collision).
+const REAL_CONTROL_DIR = path.join(os.homedir(), ".pi", "entwurf-control");
+const SOCKET_SUFFIX = ".sock";
+// Release-gate topology: repo-under-test, not deployment smoke. Load only this
+// checkout's extension so resident behavior is independent of global pi packages.
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const REPO_EXTENSION_ARGS = ["--no-extensions", "-e", REPO_ROOT] as const;
+
+// Staged timeouts (automation): short and per-stage so a stall is attributable.
+const BOOT_TIMEOUT_MS = 30_000; // pi --entwurf-control socket appears
+const POLL_MS = 100;
+
+let passed = 0;
+const artifacts: Record<string, string> = {};
+
+function ok(label: string, cond: boolean): void {
+	if (!cond) throw new Error(`SMOKE FAIL: ${label}`);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+function resolveTarget(): { provider: string; model: string } {
+	const combined = process.env.ENTWURF_LIVE_TARGET?.trim();
+	if (combined) {
+		const slash = combined.indexOf("/");
+		if (slash <= 0 || slash === combined.length - 1) {
+			throw new Error(`ENTWURF_LIVE_TARGET must be "<provider>/<model>", got: ${JSON.stringify(combined)}`);
+		}
+		return { provider: combined.slice(0, slash), model: combined.slice(slash + 1) };
+	}
+	return {
+		provider: process.env.ENTWURF_LIVE_PROVIDER?.trim() || "openai-codex",
+		model: process.env.ENTWURF_LIVE_MODEL?.trim() || "gpt-5.4",
+	};
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForSocket(sockPath: string, timeoutMs: number): Promise<boolean> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (existsSync(sockPath)) return true;
+		await sleep(POLL_MS);
+	}
+	return false;
+}
+
+function smokeSender(gardenId: string, cwd: string): SenderEnvelope {
+	return {
+		sessionId: gardenId,
+		agentId: "smoke/matrix-live",
+		cwd,
+		timestamp: new Date(0).toISOString(),
+		origin: "pi-session",
+		replyable: false,
+	};
+}
+
+async function main(): Promise<void> {
+	if (process.env.LIVE !== "1") {
+		console.log("[smoke-entwurf-v2-matrix-live] skipped — set LIVE=1 to run (spawns a real pi + opens a real socket).");
+		return;
+	}
+
+	const { provider, model } = resolveTarget();
+	console.log(`[smoke-entwurf-v2-matrix-live] target = ${provider}/${model}`);
+
+	// ── temp world (repeatable: fresh dirs, no fixed ids) ────────────────────────
+	const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "v2matrix-"));
+	const sessionsDir = path.join(tmp, "sessions");
+	const mailboxDir = path.join(tmp, "mailbox");
+	const lockDir = path.join(tmp, "locks");
+	const receiversDir = path.join(tmp, "receivers");
+	for (const d of [sessionsDir, mailboxDir, lockDir, receiversDir]) await fsp.mkdir(d, { recursive: true });
+	// The receiver marker is read through defaultMetaReceiversDir() (env-overridable); point it
+	// (and the store/mailbox defaults, belt-and-suspenders to the opts dirs) at the temp world.
+	process.env.ENTWURF_META_RECEIVERS_DIR = receiversDir;
+	process.env.ENTWURF_META_SESSIONS_DIR = sessionsDir;
+	process.env.ENTWURF_META_MAILBOX_DIR = mailboxDir;
+
+	let resident: ChildProcess | null = null;
+	let residentGid = "";
+	let c1bGid = "";
+	let stderrTail = "";
+	let succeeded = false;
+
+	const prodDeps = (sender: SenderEnvelope) =>
+		makeProductionEntwurfV2Deps({
+			senderProvider: () => sender,
+			sessionsDir,
+			mailboxDir,
+			lockDir,
+			controlSocketDir: REAL_CONTROL_DIR,
+		});
+
+	try {
+		// ── C1: control-socket — real `pi --entwurf-control` resident ──────────────
+		{
+			// DECIDER IDENTITY FIXTURE (NOT a writer E2E — R1): a real pi session does NOT
+			// self-write a meta-record (SE-1), but v2 production resolveTarget reads the target
+			// via metaRecordExists/readIdentity, so to exercise the control-socket TRANSPORT we
+			// hand-mint a backend=pi citizen and launch pi under the minted gid (record.gardenId ==
+			// the live socket's session id). nativeSessionId here is synthetic; the future pi
+			// writer's real shape is nativeSessionId==sessionId — irrelevant to this transport probe.
+			const minted = upsertMetaSession({
+				input: { backend: "pi", nativeSessionId: `smoke-c1-${process.pid}`, cwd: tmp, model },
+				dir: sessionsDir,
+			});
+			residentGid = minted.record.gardenId;
+			const sockPath = path.join(REAL_CONTROL_DIR, `${residentGid}${SOCKET_SUFFIX}`);
+			artifacts["C1.gid"] = residentGid;
+			artifacts["C1.socket"] = sockPath;
+			// B3: the fresh gid must not collide with a pre-existing socket — else cleanup would
+			// delete someone else's live socket. Fail loud rather than risk it.
+			ok("C1 fresh gid has no pre-existing control socket", !existsSync(sockPath));
+
+			// B1: drive the resident in `--mode rpc` with stdin held open (keepalive). A non-TTY
+			// interactive `pi` (stdin ignored) can abort or silently exit; rpc mode is the control
+			// substrate this cell actually probes (model UI is irrelevant here).
+			resident = spawn(
+				"pi",
+				[
+					...REPO_EXTENSION_ARGS,
+					"--session-id",
+					residentGid,
+					"--entwurf-control",
+					"--provider",
+					provider,
+					"--model",
+					model,
+					"--mode",
+					"rpc",
+				],
+				{ cwd: tmp, stdio: ["pipe", "ignore", "pipe"], detached: false },
+			);
+			resident.stderr?.on("data", (b: Buffer) => {
+				stderrTail = (stderrTail + b.toString()).slice(-2000);
+			});
+
+			const up = await waitForSocket(sockPath, BOOT_TIMEOUT_MS);
+			ok("C1 real `pi --entwurf-control` stood up a control socket", up);
+
+			const result: EntwurfV2RunResult = await runEntwurfV2(
+				{ target: residentGid, intent: "fire-and-forget", message: "matrix-live C1 control-socket probe" },
+				prodDeps(smokeSender(residentGid, tmp)),
+			);
+			// R2: not just "executed/control-socket" — the final outcome must be a real `sent`
+			// (an in-band reject or dead-fallback would also surface as control-socket otherwise).
+			ok(
+				"C1 alive pi citizen → control-socket RPC, outcome=sent",
+				result.kind === "executed" &&
+					result.transport === "control-socket" &&
+					result.outcome.transport === "control-socket" &&
+					result.outcome.outcome === "sent",
+			);
+			// in-domain control-socket send keeps then releases the lock → no lock file remains.
+			ok("C1 lock released (no lock file left for the target)", !existsSync(lockPathFor(residentGid, lockDir)));
+
+			if (resident) {
+				await terminateChild(resident);
+				resident = null;
+			}
+		}
+
+		// ── C1b: A1 narrow — RECORD-LESS live pi control socket → socket-only target ─
+		// The operator-greeted case the deterministic gates model: a real `pi --entwurf-control`
+		// resident with NO meta-record. resolveTarget finds no record, sees a live non-symlink
+		// control socket (presence hint), promotes it to a socket-only pi endpoint, and routes
+		// fire-and-forget to control-socket — the end-to-end proof that closes the gap C1's
+		// hand-minted record was hiding. owned-outcome on the SAME record-less target is refused
+		// (bad-target, no spawn). Unlike C1, NO upsertMetaSession is called for this gid.
+		{
+			c1bGid = generateSessionId();
+			const sockPath = path.join(REAL_CONTROL_DIR, `${c1bGid}${SOCKET_SUFFIX}`);
+			artifacts["C1b.gid"] = c1bGid;
+			artifacts["C1b.socket"] = sockPath;
+			ok("C1b fresh gid has no pre-existing control socket", !existsSync(sockPath));
+			// The gap-closing precondition: this gid is genuinely RECORD-LESS (C1 minted one).
+			ok(
+				"C1b target has NO meta-record (record-less, the operator-greeted case)",
+				!metaRecordExistsByGardenId(c1bGid, sessionsDir),
+			);
+
+			resident = spawn(
+				"pi",
+				[
+					...REPO_EXTENSION_ARGS,
+					"--session-id",
+					c1bGid,
+					"--entwurf-control",
+					"--provider",
+					provider,
+					"--model",
+					model,
+					"--mode",
+					"rpc",
+				],
+				{ cwd: tmp, stdio: ["pipe", "ignore", "pipe"], detached: false },
+			);
+			resident.stderr?.on("data", (b: Buffer) => {
+				stderrTail = (stderrTail + b.toString()).slice(-2000);
+			});
+
+			const up = await waitForSocket(sockPath, BOOT_TIMEOUT_MS);
+			ok("C1b real record-less `pi --entwurf-control` stood up a control socket", up);
+
+			const result: EntwurfV2RunResult = await runEntwurfV2(
+				{ target: c1bGid, intent: "fire-and-forget", message: "matrix-live C1b record-less socket-only probe" },
+				prodDeps(smokeSender(c1bGid, tmp)),
+			);
+			ok(
+				"C1b record-less live pi → socket-only control-socket RPC, outcome=sent",
+				result.kind === "executed" &&
+					result.transport === "control-socket" &&
+					result.outcome.transport === "control-socket" &&
+					result.outcome.outcome === "sent",
+			);
+			ok("C1b lock released (no lock file left for the socket-only target)", !existsSync(lockPathFor(c1bGid, lockDir)));
+
+			// owned-outcome on the record-less but LIVE target → owned-live-no-autosend (the honest
+			// table verdict), NOT the `bad-target` lie: the live resident is a real addressable
+			// citizen. spawn-bg still never opens (allowResume:false guard; no record = no resume
+			// authority). The no-spawn invariant is also pinned deterministically in the gate.
+			const owned: EntwurfV2RunResult = await runEntwurfV2(
+				{ target: c1bGid, intent: "owned-outcome", message: "matrix-live C1b owned must be refused" },
+				prodDeps(smokeSender(c1bGid, tmp)),
+			);
+			ok(
+				"C1b record-less(live) + owned-outcome → rejected owned-live-no-autosend (NOT bad-target, no spawn)",
+				owned.kind === "rejected" && owned.receipt.reason === "owned-live-no-autosend",
+			);
+
+			if (resident) {
+				await terminateChild(resident);
+				resident = null;
+			}
+		}
+
+		// ── C2: meta-mailbox — deliverable self-fetch citizen (ARMED receiver) ──────
+		{
+			const minted = upsertMetaSession({
+				input: { backend: "claude-code", nativeSessionId: `smoke-c2-${process.pid}`, cwd: tmp },
+				dir: sessionsDir,
+			});
+			const gid = minted.record.gardenId;
+			artifacts["C2.gid"] = gid;
+			// armed = a presence marker owned by THIS (live) process → deliverable.
+			writeMetaReceiverMarker({
+				gardenId: gid,
+				backend: "claude-code",
+				nativeSessionId: minted.record.nativeSessionId,
+				ownerPid: process.pid,
+				armProvenance: "session-start",
+				receiversDir,
+			});
+
+			const result: EntwurfV2RunResult = await runEntwurfV2(
+				{ target: gid, intent: "fire-and-forget", message: "matrix-live C2 meta-mailbox probe" },
+				prodDeps(smokeSender(gid, tmp)),
+			);
+			ok(
+				"C2 decider routed an armed self-fetch citizen to meta-mailbox (executed)",
+				result.kind === "executed" && result.transport === "meta-mailbox",
+			);
+			const boxDir = path.join(mailboxDir, gid);
+			artifacts["C2.mailbox"] = boxDir;
+			const msgs = await fsp.readdir(boxDir).catch(() => [] as string[]);
+			// B4: enqueue is exactly one .msg AND the doorbell signal is poked.
+			ok("C2 exactly one .msg enqueued to the target mailbox", msgs.filter((f) => f.endsWith(".msg")).length === 1);
+			ok("C2 the doorbell inbox.signal was poked", existsSync(path.join(boxDir, "inbox.signal")));
+			ok("C2 meta-mailbox is lock-free (no lock file)", !existsSync(lockPathFor(gid, lockDir)));
+		}
+
+		// ── C3: meta-mailbox guard — undeliverable (NO armed receiver) ──────────────
+		{
+			const minted = upsertMetaSession({
+				input: { backend: "claude-code", nativeSessionId: `smoke-c3-${process.pid}`, cwd: tmp },
+				dir: sessionsDir,
+			});
+			const gid = minted.record.gardenId;
+			artifacts["C3.gid"] = gid;
+			// NO receiver marker written → terminated self-fetch session → fail-closed.
+
+			const result: EntwurfV2RunResult = await runEntwurfV2(
+				{ target: gid, intent: "fire-and-forget", message: "matrix-live C3 should be refused" },
+				prodDeps(smokeSender(gid, tmp)),
+			);
+			// B5: pin the reason — a different reject (bad-target, etc.) must not pass as "guard works".
+			ok(
+				"C3 deliverability guard rejected with reason=mailbox-undeliverable",
+				result.kind === "rejected" && result.receipt.reason === "mailbox-undeliverable",
+			);
+			// B4: SE-2 reject contract = no enqueue AND no signal poke (mailbox fs untouched).
+			const boxDir = path.join(mailboxDir, gid);
+			const msgs = await fsp.readdir(boxDir).catch(() => [] as string[]);
+			ok("C3 no .msg garbage left for the dead receiver (SE-2)", !msgs.some((f) => f.endsWith(".msg")));
+			ok("C3 no inbox.signal poked for the dead receiver (SE-2)", !existsSync(path.join(boxDir, "inbox.signal")));
+		}
+
+		succeeded = true;
+		console.log(`\nsmoke-entwurf-v2-matrix-live: ${passed} checks passed (real pi control socket + real mailbox)`);
+	} catch (err) {
+		console.error("\n[smoke-entwurf-v2-matrix-live] FAILED — diagnostic artifacts:");
+		for (const [k, v] of Object.entries(artifacts)) console.error(`  ${k} = ${v}`);
+		if (stderrTail) console.error(`  pi stderr (tail):\n${stderrTail.replace(/^/gm, "    ")}`);
+		throw err;
+	} finally {
+		if (resident) {
+			await terminateChild(resident).catch(() => {});
+			resident = null;
+		}
+		// remove the real control sockets pi may have left under the fresh gids (C1, C1b)
+		for (const gid of [residentGid, c1bGid]) {
+			if (gid) {
+				await fsp.rm(path.join(REAL_CONTROL_DIR, `${gid}${SOCKET_SUFFIX}`), { force: true }).catch(() => {});
+			}
+		}
+		// B6: keep the temp world on failure so the printed artifact paths are real for post-mortem
+		// (CI/cron). Only a clean pass tears it down.
+		if (succeeded) {
+			await fsp.rm(tmp, { recursive: true, force: true });
+		} else {
+			console.error(`[smoke-entwurf-v2-matrix-live] temp world preserved for inspection: ${tmp}`);
+		}
+	}
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/scripts/smoke-entwurf-v2-spawn-live.ts

@@ -0,0 +1,175 @@
+/**
+ * smoke-entwurf-v2-spawn-live — the 5c-3c LIVE phase gate (D5). Unlike the deterministic
+ * gate (check-entwurf-v2-spawn-production, fakes only), this exercises the production
+ * SpawnBgResumeDeps against REAL OS objects — a real unix socket, real child processes, real
+ * timers, real abort teardown — to catch what fakes cannot: actual spawn/exit/error event
+ * semantics, real lstat+connect liveness, real timer/abort cleanup, and the 5c-3a watcher's
+ * timeout→kill→child-exited→release integration on a live process.
+ *
+ * It does NOT spawn a real `pi --entwurf-control` resume (that needs a saved session, model
+ * auth, and backend state — flaky); proving the argv actually launches pi end-to-end is the
+ * 5d surface matrix's job. `buildResumePiArgs` is already pinned by the deterministic gate.
+ *
+ * Kept OUT of `pnpm check` (it spawns processes / opens sockets); run it manually before 5d:
+ *   LIVE=1 ./run.sh smoke-entwurf-v2-spawn-live
+ * and record the result in NEXT.md / the commit body (chain-outside, phase-gate-inside).
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import * as fsp from "node:fs/promises";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { LockClaim } from "../pi-extensions/lib/entwurf-v2-lock.ts";
+import { executeSpawnBgResume, type SpawnBgPlan } from "../pi-extensions/lib/entwurf-v2-spawn.ts";
+import { makeProductionSpawnBgResumeDeps } from "../pi-extensions/lib/entwurf-v2-spawn-production.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	if (!cond) throw new Error(`SMOKE FAIL: ${label}`);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+// A resident child that survives until SIGTERM, then exits 0 — a stand-in for a pi child
+// (we are proving the OS-level lifecycle wiring, not pi's resume behavior).
+const RESIDENT_CHILD = "process.on('SIGTERM',()=>process.exit(0)); setInterval(()=>{},1e9);";
+
+function lockClaim(gardenId: string): LockClaim {
+	return {
+		gardenId,
+		pid: process.pid,
+		hostname: os.hostname(),
+		createdAt: new Date(0).toISOString(),
+		nonce: "live5c3csmoke00",
+		owner: "entwurf_v2",
+		lockPath: `/tmp/${gardenId}.lock`,
+	};
+}
+
+function spawnBgPlan(over: Partial<SpawnBgPlan> = {}): SpawnBgPlan {
+	const gid = "20260613T000000-aaaaaa";
+	return {
+		transport: "spawn-bg",
+		action: "resume",
+		targetGardenId: gid,
+		sessionId: gid,
+		cwd: process.cwd(),
+		prompt: "continue",
+		launchArgs: [],
+		expectedSocketPath: "/nonexistent/never.sock",
+		observeTimeoutMs: 30_000,
+		releaseWhen: "socket-alive-or-child-exited",
+		...over,
+	};
+}
+
+async function main(): Promise<void> {
+	const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "v2spawn-"));
+	const children: ChildProcess[] = [];
+	let server: net.Server | null = null;
+
+	try {
+		// ── S1: real unix-socket connectability (real fs.lstat + real probeSocketLiveness) ─
+		{
+			const sockPath = path.join(tmp, "live.sock");
+			server = net.createServer();
+			await new Promise<void>((resolve) => server?.listen(sockPath, resolve));
+			const deps = makeProductionSpawnBgResumeDeps({ pollIntervalMs: 20 });
+			await deps.awaitSocketAlive(sockPath, new AbortController().signal);
+			ok("S1 a real listening unix socket → awaitSocketAlive resolves (connectable)", true);
+
+			// symlink at the path → forged (real lstat catches it; never connected — P1).
+			const symPath = path.join(tmp, "sym.sock");
+			await fsp.symlink(sockPath, symPath);
+			let forged = false;
+			try {
+				await deps.awaitSocketAlive(symPath, new AbortController().signal);
+			} catch (e) {
+				forged = e instanceof Error && e.message.includes("forged");
+			}
+			ok("S1 a symlink at the socket path → forged reject (real lstat P1)", forged);
+
+			// absent path → dead → wait; abort settles it (real timer + abort cleanup).
+			const ctrl = new AbortController();
+			const absentP = deps.awaitSocketAlive(path.join(tmp, "absent.sock"), ctrl.signal);
+			setTimeout(() => ctrl.abort(), 60);
+			let aborted = false;
+			try {
+				await absentP;
+			} catch {
+				aborted = true;
+			}
+			ok("S1 an absent socket → waits, then abort settles it (no hang)", aborted);
+
+			await new Promise<void>((resolve) => server?.close(() => resolve()));
+			server = null;
+		}
+
+		// ── S2: real child lifecycle — spawn event, exit capture, SIGTERM kill ───────────
+		{
+			const deps = makeProductionSpawnBgResumeDeps({
+				resolveIdentity: () => ({ cwd: tmp, explicitExtensionArgs: [], provider: null, model: "smoke" }),
+				spawnChild: () => {
+					const proc = spawn(process.execPath, ["-e", RESIDENT_CHILD], { stdio: "ignore" });
+					children.push(proc);
+					return proc;
+				},
+			});
+			// spawnChild awaits the REAL 'spawn' event before resolving (B1).
+			const child = await deps.spawnChild(spawnBgPlan());
+			ok("S2 spawnChild resolves on the real 'spawn' event (B1)", typeof child.pid === "number" && child.pid > 0);
+
+			// SIGTERM → the resident child terminates; awaitChildExit OBSERVES the exit via the
+			// eager exitPromise (B2). The code is 0 if the child's SIGTERM handler ran, or null if
+			// the signal landed before the handler was installed — both are a real, observed exit
+			// (the watcher releases on child-exited for ANY code), which is what this proves.
+			deps.killChild(child);
+			const code = await deps.awaitChildExit(child, new AbortController().signal);
+			ok("S2 killChild(SIGTERM) → awaitChildExit observes the exit (code 0 or null)", code === 0 || code === null);
+		}
+
+		// ── S3: watcher integration — real timeout → kill → child-exited → release ───────
+		{
+			let releases = 0;
+			const deps = makeProductionSpawnBgResumeDeps({
+				resolveIdentity: () => ({ cwd: tmp, explicitExtensionArgs: [], provider: null, model: "smoke" }),
+				spawnChild: () => {
+					const proc = spawn(process.execPath, ["-e", RESIDENT_CHILD], { stdio: "ignore" });
+					children.push(proc);
+					return proc;
+				},
+				releaseFn: () => {
+					releases++;
+				},
+				pollIntervalMs: 20,
+				killGraceMs: 2_000,
+			});
+			// A child that never stands a socket up + a short observe window → the watcher must
+			// time out, NOT release on the timeout, kill, observe the real exit, then release once.
+			const plan = spawnBgPlan({ observeTimeoutMs: 80, expectedSocketPath: path.join(tmp, "never-appears.sock") });
+			const result = await executeSpawnBgResume(plan, lockClaim(plan.sessionId), deps);
+			ok("S3 timeout→kill→child-exited (real timer + real child + 5c-3a watcher)", result.kind === "child-exited");
+			ok("S3 lock released exactly once on the observed exit", result.released === true && releases === 1);
+		}
+
+		console.log(`\nsmoke-entwurf-v2-spawn-live: ${passed} checks passed (real OS primitives)`);
+	} finally {
+		for (const c of children) {
+			try {
+				c.kill("SIGKILL");
+			} catch {
+				// best-effort
+			}
+		}
+		if (server) {
+			await new Promise<void>((resolve) => server?.close(() => resolve()));
+		}
+		await fsp.rm(tmp, { recursive: true, force: true });
+	}
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});