@junghanacs/entwurf 0.12.0

package/scripts/check-entwurf-mailbox-guard.ts

@@ -0,0 +1,264 @@
+/**
+ * check-entwurf-mailbox-guard — deterministic gate for the guarded mailbox enqueue
+ * (SE-1/SE-2 slice 2d). The IO orchestration that conversational-reply sites use
+ * instead of calling enqueueMetaMessage directly: it must NOT enqueue (no .msg, no
+ * doorbell poke, no mailbox mutation) when the target is undeliverable, and must
+ * enqueue exactly once when it is.
+ *
+ * Proves (GPT Q5 — both axes):
+ *   1. PURE 0-call: with injected facts/readers, an undeliverable target leaves the
+ *      injected enqueue UNCALLED (dead receiver / direct-inject / absent record);
+ *      a deliverable target calls it exactly once and carries the result through.
+ *   2. TMPDIR SNAPSHOT: with the REAL enqueueMetaMessage against a real mailbox dir,
+ *      a refused send leaves the mailbox tree byte-for-byte unchanged (file list +
+ *      content hash, not just mtime), and an accepted send writes exactly one .msg +
+ *      pokes the signal.
+ *   3. fact gathering: recordBacked/wakeMode from the record+capability, ownerAlive/
+ *      watchArmed from the receiver marker (present→true, absent/dead→false).
+ */
+
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { gatherMailboxDeliverabilityFacts, guardedMailboxEnqueue } from "../pi-extensions/lib/entwurf-mailbox-guard.ts";
+import {
+	enqueueMetaMessage,
+	type MetaIdentity,
+	mintMetaIdentity,
+	readMetaReceiverMarker,
+	serializeMetaIdentity,
+	writeMetaReceiverMarker,
+} from "../pi-extensions/lib/meta-session.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const REPO_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const GARDEN = "20260614T120000-aaaaaa";
+const selfFetch = () => ({ wakeMode: "self-fetch" }) as never;
+const directInject = () => ({ wakeMode: "direct-inject" }) as never;
+// The record identity and the marker MUST agree on garden/backend/native id — that
+// agreement is what SE-2 2d-3 now requires (a present marker alone is not enough). Built
+// from a fixed garden id (NOT mintMetaIdentity, which would generate a random gardenId that
+// never matches GARDEN — the old presence-only test silently ignored that mismatch).
+const liveIdentity = (): MetaIdentity => ({
+	schemaVersion: 2,
+	gardenId: GARDEN,
+	backend: "claude-code",
+	nativeSessionId: "n-a",
+	cwd: "/tmp",
+	model: null,
+	transcriptPath: null,
+	parentGardenId: null,
+	isEntwurf: false,
+	createdAt: "2026-06-14T01:00:00.000Z",
+	recordUpdatedAt: "2026-06-14T01:00:00.000Z",
+});
+const liveMarker = () =>
+	({
+		gardenId: GARDEN,
+		backend: "claude-code",
+		nativeSessionId: "n-a",
+		ownerPid: 1,
+		ownerStartKey: "x",
+		ownerKind: "claude-code-cli",
+		armProvenance: "session-start",
+		updatedAt: "t",
+	}) as never;
+// Same shape as liveMarker but with a drifted native id → does NOT match the record
+// identity ("n-a") → SE-2 2d-3 treats it as a stale/foreign marker (inactive receiver).
+const driftMarker = () =>
+	({
+		gardenId: GARDEN,
+		backend: "claude-code",
+		nativeSessionId: "n-OTHER",
+		ownerPid: 1,
+		ownerStartKey: "x",
+		ownerKind: "claude-code-cli",
+		armProvenance: "session-start",
+		updatedAt: "t",
+	}) as never;
+
+// ── PURE 0-call (injected facts/readers) ────────────────────────────────────
+{
+	let calls = 0;
+	const enqueue = () => {
+		calls++;
+		return "ENQUEUED";
+	};
+
+	// deliverable: self-fetch record + live marker → enqueue once.
+	const okOut = guardedMailboxEnqueue(
+		GARDEN,
+		{ readIdentity: liveIdentity, readReceiverMarker: liveMarker, capabilityFor: selfFetch },
+		enqueue,
+	);
+	ok("deliverable → enqueue called exactly once", calls === 1);
+	ok("deliverable → outcome carries the enqueue result", okOut.delivered === true && okOut.result === "ENQUEUED");
+
+	// dead receiver (marker null) → 0-call.
+	calls = 0;
+	const deadOut = guardedMailboxEnqueue(
+		GARDEN,
+		{ readIdentity: liveIdentity, readReceiverMarker: () => null, capabilityFor: selfFetch },
+		enqueue,
+	);
+	ok("dead/absent receiver → enqueue NOT called (0-call)", calls === 0);
+	ok(
+		"dead receiver → delivered:false with a reason",
+		deadOut.delivered === false && !deadOut.delivered && deadOut.reason.length > 0,
+	);
+
+	// direct-inject backend (pi) → 0-call even with a live marker (SE-1).
+	calls = 0;
+	guardedMailboxEnqueue(
+		GARDEN,
+		{ readIdentity: liveIdentity, readReceiverMarker: liveMarker, capabilityFor: directInject },
+		enqueue,
+	);
+	ok("direct-inject backend → enqueue NOT called (SE-1, 0-call)", calls === 0);
+
+	// SE-2 2d-3: a present marker whose identity has DRIFTED (native session id mismatch) is a
+	// stale/foreign marker — not THIS receiver — so presence alone does not deliver. 0-call.
+	calls = 0;
+	const driftOut = guardedMailboxEnqueue(
+		GARDEN,
+		{
+			readIdentity: liveIdentity,
+			readReceiverMarker: driftMarker,
+			capabilityFor: selfFetch,
+		},
+		enqueue,
+	);
+	ok("marker identity drift (native id) → enqueue NOT called (SE-2 2d-3, 0-call)", calls === 0);
+	ok("marker identity drift → delivered:false", driftOut.delivered === false);
+
+	// no backing record → 0-call.
+	calls = 0;
+	guardedMailboxEnqueue(
+		GARDEN,
+		{
+			readIdentity: () => {
+				throw new Error("no record");
+			},
+			readReceiverMarker: liveMarker,
+			capabilityFor: selfFetch,
+		},
+		enqueue,
+	);
+	ok("absent record → enqueue NOT called (0-call)", calls === 0);
+}
+
+// ── fact gathering ──────────────────────────────────────────────────────────
+{
+	const facts = gatherMailboxDeliverabilityFacts(GARDEN, {
+		readIdentity: liveIdentity,
+		readReceiverMarker: liveMarker,
+		capabilityFor: selfFetch,
+	});
+	ok("facts: recordBacked from a present record", facts.recordBacked === true);
+	ok("facts: wakeMode from the capability registry", facts.wakeMode === "self-fetch");
+	ok("facts: ownerAlive+watchArmed true from a present marker", facts.ownerAlive === true && facts.watchArmed === true);
+
+	const absent = gatherMailboxDeliverabilityFacts(GARDEN, {
+		readIdentity: () => {
+			throw new Error("none");
+		},
+		readReceiverMarker: () => null,
+		capabilityFor: selfFetch,
+	});
+	ok(
+		"facts: absent record → recordBacked false, wakeMode undefined",
+		absent.recordBacked === false && absent.wakeMode === undefined,
+	);
+	ok("facts: absent marker → ownerAlive+watchArmed false", absent.ownerAlive === false && absent.watchArmed === false);
+
+	// A present-but-drifted marker (native id mismatch) is recordBacked (the record is fine)
+	// but the receiver is inactive — the SE-2 2d-3 identity-match gate, not presence alone.
+	const drift = gatherMailboxDeliverabilityFacts(GARDEN, {
+		readIdentity: liveIdentity,
+		readReceiverMarker: driftMarker,
+		capabilityFor: selfFetch,
+	});
+	ok(
+		"facts: drifted marker → recordBacked true but ownerAlive+watchArmed false",
+		drift.recordBacked === true && drift.ownerAlive === false && drift.watchArmed === false,
+	);
+}
+
+// ── TMPDIR SNAPSHOT (real enqueueMetaMessage) ───────────────────────────────
+function snapshot(dir: string): string {
+	const h = createHash("sha256");
+	const walk = (d: string) => {
+		let entries: string[];
+		try {
+			entries = readdirSync(d).sort();
+		} catch {
+			return;
+		}
+		for (const name of entries) {
+			const p = path.join(d, name);
+			const st = statSync(p);
+			h.update(`${p}\n`);
+			if (st.isDirectory()) walk(p);
+			else h.update(readFileSync(p));
+		}
+	};
+	walk(dir);
+	return h.digest("hex");
+}
+
+{
+	const TMP = mkdtempSync(path.join(tmpdir(), "psa-mbguard-"));
+	const sessionsDir = path.join(TMP, "meta-sessions");
+	const mailboxDir = path.join(TMP, "meta-mailbox");
+	const receiversDir = path.join(TMP, "meta-receivers");
+	for (const d of [sessionsDir, mailboxDir, receiversDir]) mkdirSync(d, { recursive: true });
+
+	// Seed a real claude-code record (recordBacked + self-fetch), but NO receiver
+	// marker → the target is a terminated/absent receiver. A guarded send must refuse.
+	const id = mintMetaIdentity({ backend: "claude-code", nativeSessionId: "n-snap", cwd: "/tmp" });
+	writeFileSync(path.join(sessionsDir, `${id.gardenId}.meta.json`), serializeMetaIdentity(id));
+
+	const deps = {
+		readIdentity: (g: string) =>
+			JSON.parse(readFileSync(path.join(sessionsDir, `${g}.meta.json`), "utf8")) as MetaIdentity,
+		readReceiverMarker: (g: string) => readMetaReceiverMarker({ gardenId: g, receiversDir }),
+	};
+	const realEnqueue = () => enqueueMetaMessage({ gardenId: id.gardenId, body: "SNAP", sessionsDir, mailboxDir });
+
+	const before = snapshot(mailboxDir);
+	const refused = guardedMailboxEnqueue(id.gardenId, deps, realEnqueue);
+	const after = snapshot(mailboxDir);
+	ok("refused send → delivered:false", refused.delivered === false);
+	ok("refused send → mailbox tree byte-identical (no .msg, no signal poke, no state)", before === after);
+
+	// Now arm a live receiver marker (this process is the live owner) → deliverable.
+	writeMetaReceiverMarker({
+		gardenId: id.gardenId,
+		backend: "claude-code",
+		nativeSessionId: "n-snap",
+		ownerPid: process.pid,
+		armProvenance: "session-start",
+		receiversDir,
+	});
+	const accepted = guardedMailboxEnqueue(id.gardenId, deps, realEnqueue);
+	ok("active receiver → delivered:true", accepted.delivered === true);
+	const msgs = readdirSync(path.join(mailboxDir, id.gardenId)).filter((f) => f.endsWith(".msg"));
+	ok("active receiver → exactly one .msg written", msgs.length === 1);
+}
+
+// ── V2-ONLY WIRING: legacy MCP entwurf_send fallback is gone ───────────────
+// v2 mailbox delivery is covered by check-entwurf-v2-mailbox + decider gates; this
+// file keeps the guard primitive pinned for remaining/future conversational enqueue sites.
+const mcpSrc = readFileSync(path.join(REPO_DIR, "mcp", "entwurf-bridge", "src", "index.ts"), "utf8");
+ok("legacy MCP entwurf_send tool removed", !mcpSrc.includes('server.tool(\n\t"entwurf_send"'));
+
+console.log(`\ncheck-entwurf-mailbox-guard: ${passed} checks passed`);

package/scripts/check-entwurf-peers-surface.ts

@@ -0,0 +1,235 @@
+/**
+ * check-entwurf-peers-surface — deterministic gate for the MCP + pi-native `entwurf_peers`
+ * RENDER/PAYLOAD layer (0.11 Stage 0 step 4, slice 4c). Drives the PURE
+ * `renderEntwurfPeers` with a fabricated `EntwurfFactsResult` (no IO) and proves
+ * the surface contract (GPi + Fable 수렴):
+ *
+ *   - legacy `sessions` is a PROJECTION of the facts (alive pi citizens + alive
+ *     socket-only), NOT a second scan — dead / indeterminate / unsupported /
+ *     non-pi never appear in it,
+ *   - sessions[].socketPath === controlSocketPath(gid, dir) — SSOT, no re-concat
+ *     drift of the filename↔gardenId correlation authority (동결결정3, Fable a),
+ *   - count === sessions.length (the legacy projection count, NOT peers.length;
+ *     Fable d),
+ *   - three DISTINCT arrays (peers / socketOnly / diagnostics), never merged,
+ *   - NO verb-routing field anywhere in the JSON (deep key scan) AND no
+ *     verb-routing WORD in the text render (Fable e①: a "resumable peers" title
+ *     leaks routing a key scan would miss),
+ *   - diagnostics appear in BOTH the text and the JSON,
+ *   - empty sections render "(none)"; an `unsupported` peer is shown (never
+ *     dropped); socket-only enrich null renders "(not enriched)",
+ *   - WIRING guard (Fable e②/6): the MCP handler and pi-native tool call
+ *     listEntwurfFacts + renderEntwurfPeers, and the old getLiveSessions is gone from the bridge.
+ *
+ * No IO — the facts are fabricated; only the wiring guard reads the bridge source
+ * as text (a static assertion, not an execution).
+ */
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { EntwurfFactsResult } from "../pi-extensions/lib/entwurf-fact-provider.ts";
+import type { PeerFact, SocketOnlyFact } from "../pi-extensions/lib/entwurf-facts.ts";
+import { renderEntwurfPeers } from "../pi-extensions/lib/entwurf-peers-render.ts";
+import type { FactLiveness } from "../pi-extensions/lib/entwurf-v2-contract.ts";
+import type { MetaBackendV2 } from "../pi-extensions/lib/meta-session.ts";
+import { controlSocketPath } from "../pi-extensions/lib/socket-discovery.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const DIR = "/fake/entwurf-control";
+const FORBIDDEN = ["sendable", "resumable", "dispatch", "action", "transport", "mailboxDeliverable"];
+
+function peer(gardenId: string, backend: MetaBackendV2, liveness: FactLiveness): PeerFact {
+	return {
+		gardenId,
+		backend,
+		nativeSessionId: `n-${gardenId}`,
+		cwd: "/x",
+		model: null,
+		parentGardenId: null,
+		isEntwurf: false,
+		createdAt: "2026-06-11T00:00:00.000Z",
+		recordUpdatedAt: "2026-06-11T00:00:00.000Z",
+		liveness,
+	};
+}
+
+function socketOnly(
+	gardenId: string,
+	liveness: SocketOnlyFact["liveness"],
+	over: Partial<SocketOnlyFact> = {},
+): SocketOnlyFact {
+	return { kind: "socket-only", gardenId, liveness, cwd: null, model: null, idle: null, infoError: null, ...over };
+}
+
+/** Recursively collect every object key in a JSON-able value. */
+function allKeys(value: unknown, acc: Set<string> = new Set()): Set<string> {
+	if (Array.isArray(value)) {
+		for (const v of value) allKeys(v, acc);
+	} else if (value && typeof value === "object") {
+		for (const [k, v] of Object.entries(value)) {
+			acc.add(k);
+			allKeys(v, acc);
+		}
+	}
+	return acc;
+}
+
+const GID_PI_ALIVE = "20260611T111111-aaaaaa"; // pi alive → in sessions
+const GID_PI_DEAD = "20260611T222222-bbbbbb"; // pi dead (dormant) → NOT in sessions
+const GID_PI_INDET = "20260611T333333-cccccc"; // pi indeterminate → NOT in sessions
+const GID_CLAUDE = "20260611T444444-dddddd"; // claude unsupported → shown, NOT in sessions
+const GID_SOCK_ALIVE = "20260611T555555-eeeeee"; // socket-only alive → in sessions
+const GID_SOCK_DEAD = "20260611T666666-ffffff"; // socket-only dead → shown, NOT in sessions
+
+function main(): void {
+	const result: EntwurfFactsResult = {
+		facts: {
+			peers: [
+				peer(GID_PI_ALIVE, "pi", "alive"),
+				peer(GID_PI_DEAD, "pi", "dead"),
+				peer(GID_PI_INDET, "pi", "indeterminate"),
+				peer(GID_CLAUDE, "claude-code", "unsupported"),
+			],
+			socketOnly: [
+				socketOnly(GID_SOCK_ALIVE, "alive", { cwd: "/work/cos", model: "gpt-5.4", idle: false }),
+				socketOnly(GID_SOCK_DEAD, "dead", { infoError: "get_info failed" }),
+			],
+		},
+		diagnostics: [{ kind: "socket-symlink-rejected", gardenId: "20260611T999999-999999", message: "symlink rejected" }],
+	};
+
+	const { text, payload } = renderEntwurfPeers(result, DIR);
+
+	// ── legacy sessions = projection of facts (alive only) ──────────────────────
+	const sessGids = payload.sessions.map((s) => s.sessionId);
+	ok("sessions: alive pi citizen included", sessGids.includes(GID_PI_ALIVE));
+	ok("sessions: alive socket-only included", sessGids.includes(GID_SOCK_ALIVE));
+	ok("sessions: dead pi citizen NOT included", !sessGids.includes(GID_PI_DEAD));
+	ok("sessions: indeterminate pi citizen NOT included", !sessGids.includes(GID_PI_INDET));
+	ok("sessions: unsupported claude citizen NOT included", !sessGids.includes(GID_CLAUDE));
+	ok("sessions: dead socket-only NOT included", !sessGids.includes(GID_SOCK_DEAD));
+	ok("sessions: exactly the 2 alive entries", payload.sessions.length === 2);
+
+	// ── socketPath SSOT (Fable a) ───────────────────────────────────────────────
+	ok(
+		"sessions: socketPath built via controlSocketPath (SSOT, no drift)",
+		payload.sessions.every((s) => s.socketPath === controlSocketPath(s.sessionId, DIR)),
+	);
+
+	// ── count = legacy projection length, NOT peers.length (Fable d) ────────────
+	ok("count === sessions.length (projection, not peers)", payload.count === payload.sessions.length);
+	ok("count is not peers.length (would be 4)", payload.count !== payload.peers.length);
+
+	// ── three distinct arrays, never merged ─────────────────────────────────────
+	ok(
+		"payload keeps peers / socketOnly / diagnostics as three arrays",
+		Array.isArray(payload.peers) && Array.isArray(payload.socketOnly) && Array.isArray(payload.diagnostics),
+	);
+	ok("peers carry all 4 citizens (unsupported NOT dropped)", payload.peers.length === 4);
+	ok(
+		"unsupported citizen present in peers",
+		payload.peers.some((p) => p.gardenId === GID_CLAUDE && p.liveness === "unsupported"),
+	);
+	ok("socketOnly carries both (dead NOT dropped)", payload.socketOnly.length === 2);
+
+	// ── NO verb-routing field in JSON (deep key scan) ───────────────────────────
+	const keys = allKeys(payload as unknown);
+	for (const f of FORBIDDEN) {
+		ok(`JSON has no '${f}' key (facts-only, no verb-routing)`, !keys.has(f));
+	}
+
+	// ── NO verb-routing word in the TEXT render (Fable e①) ──────────────────────
+	const lowerText = text.toLowerCase();
+	for (const f of FORBIDDEN) {
+		ok(`text render has no '${f}' word (no routing leak in titles/labels)`, !lowerText.includes(f.toLowerCase()));
+	}
+
+	// ── diagnostics visible in BOTH surfaces ────────────────────────────────────
+	ok(
+		"diagnostic visible in JSON",
+		payload.diagnostics.length === 1 && payload.diagnostics[0]?.kind === "socket-symlink-rejected",
+	);
+	ok("diagnostic visible in text", text.includes("socket-symlink-rejected"));
+
+	// ── three section titles present + ordering ─────────────────────────────────
+	ok("text has the citizens section", text.includes("Garden citizens (meta-record):"));
+	ok("text has the socket-only section", text.includes("Socket-only control sockets (no meta-record):"));
+	ok("text has the diagnostics section", text.includes("Diagnostics:"));
+
+	// ── empty sections render "(none)" + enrich label ──────────────────────────
+	{
+		const empty = renderEntwurfPeers({ facts: { peers: [], socketOnly: [] }, diagnostics: [] }, DIR);
+		ok("empty diagnostics render '(none)' (trust signal, not hidden)", empty.text.includes("Diagnostics:\n  (none)"));
+		ok("empty citizens render '(none)'", empty.text.includes("Garden citizens (meta-record):\n  (none)"));
+		ok("empty surface → count 0, no sessions", empty.payload.count === 0 && empty.payload.sessions.length === 0);
+	}
+	ok(
+		"socket-only enrich appears in text",
+		text.includes(`${GID_SOCK_ALIVE}  liveness=alive  cwd=/work/cos  model=gpt-5.4  idle=no`),
+	);
+	ok(
+		"socket-only infoError appears in text",
+		text.includes(
+			`${GID_SOCK_DEAD}  liveness=dead  cwd=(not enriched)  model=(not enriched)  infoError=get_info failed`,
+		),
+	);
+	ok("unsupported peer line shown in text", text.includes(`${GID_CLAUDE}  backend=claude-code  liveness=unsupported`));
+
+	// ── human text is bounded: full payload remains structured, not pasted into content ──
+	{
+		const manyPeers = Array.from({ length: 40 }, (_, i) =>
+			peer(`20260612T0000${String(i).padStart(2, "0")}-aaaaaa`, "claude-code", "unsupported"),
+		);
+		const bounded = renderEntwurfPeers({ facts: { peers: manyPeers, socketOnly: [] }, diagnostics: [] }, DIR);
+		ok("bounded text omits older entries when peer list is large", bounded.text.includes("older entries omitted"));
+		ok("bounded text shows latest entries", bounded.text.includes("20260612T000039-aaaaaa"));
+		ok("bounded text omits oldest entry", !bounded.text.includes("20260612T000000-aaaaaa  backend="));
+		ok("bounded payload still carries every peer", bounded.payload.peers.length === 40);
+	}
+
+	// ── WIRING guard: bridge handler calls the provider+render, not getLiveSessions ──
+	{
+		const here = path.dirname(fileURLToPath(import.meta.url));
+		const bridgeSrc = readFileSync(path.join(here, "..", "mcp", "entwurf-bridge", "src", "index.ts"), "utf8");
+		const nativeSrc = readFileSync(path.join(here, "..", "pi-extensions", "entwurf-control.ts"), "utf8");
+		ok("wiring: bridge calls listEntwurfFacts(", bridgeSrc.includes("listEntwurfFacts("));
+		ok("wiring: bridge calls renderEntwurfPeers(", bridgeSrc.includes("renderEntwurfPeers("));
+		ok("wiring: native pi tool calls listEntwurfFacts(", nativeSrc.includes("listEntwurfFacts("));
+		ok("wiring: native pi tool calls renderEntwurfPeers(", nativeSrc.includes("renderEntwurfPeers("));
+		ok(
+			"wiring: native pi tool description no longer claims socket-only discovery",
+			!nativeSrc.includes("List live sessions that expose a control socket. Returns sessionIds only"),
+		);
+		ok(
+			"wiring: bridge does not paste full JSON payload into human text",
+			!bridgeSrc.includes("JSON.stringify(payload)"),
+		);
+		ok(
+			"wiring: native pi tool does not paste full JSON payload into human text",
+			!nativeSrc.includes("JSON.stringify(payload)"),
+		);
+		// `\bname\s*\(` catches a definition OR a call (tolerating a space before the
+		// paren, GPi Q4); a bare prose mention in a removal-note comment (no paren) is
+		// allowed — the guard targets the second scan, not the word.
+		ok(
+			"wiring: no getLiveSessions definition/call in bridge (no second scan)",
+			!/\bgetLiveSessions\s*\(/.test(bridgeSrc),
+		);
+		ok(
+			"wiring: no isSocketAlive definition/call in bridge (legacy probe removed)",
+			!/\bisSocketAlive\s*\(/.test(bridgeSrc),
+		);
+	}
+
+	console.log(`\n[check-entwurf-peers-surface] ${passed} assertions ok`);
+}
+
+main();

package/scripts/check-entwurf-resume-args.ts

@@ -0,0 +1,149 @@
+/**
+ * check-entwurf-resume-args — deterministic gate for the 5c-3b resume-argv SSOT
+ * (`buildResumePiArgs`). It pins the load-bearing A1 difference between the legacy one-shot
+ * worker and the v2 spawn-bg RESIDENT citizen so the two launch shapes can never drift:
+ *
+ *   1. legacy carries `--no-extensions` and NO `--entwurf-control`.
+ *   2. v2-control carries `--entwurf-control` and NO `--no-extensions`.
+ *   3. BOTH keep the headless prefix `--mode json -p` and run the prompt as the final
+ *      positional (the prompt-as-turn authority is unchanged in v2 — `-p` is NOT dropped).
+ *   4. `explicitExtensionArgs` is preserved verbatim, exactly once, in BOTH variants
+ *      (load-bearing for a recorded `provider=entwurf` resume; #29 footgun).
+ *   5. v2-control includes `plan.launchArgs` (`--approve` / empty) as flags BEFORE the
+ *      prompt; legacy ignores launchArgs entirely.
+ *   6. provider/model identity is laid out identically in both; a null/undefined provider
+ *      emits NO `--provider` flag; `--model <m>` and `<prompt>` are the last three tokens.
+ *   7. no cross-contamination: the legacy-only and v2-only flags never leak into the other.
+ *
+ * Pure string assembly — no IO, no spawn.
+ */
+
+import assert from "node:assert/strict";
+import { buildResumePiArgs } from "../pi-extensions/lib/entwurf-resume-args.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const GID = "20260613T091000-98363c";
+// Real production shape: getEntwurfExplicitExtensions emits `-e <path>` (entwurf-core.ts),
+// NOT `--extension`. The builder spreads verbatim, but the fixture mirrors production so the
+// "preserved exactly once" assertion exercises the token the launcher actually passes.
+const EXT = ["-e", "/path/to/entwurf/index.ts"] as const;
+
+// index of token `flag`'s VALUE (the token right after it), or -1 if the flag is absent.
+function valueAfter(args: readonly string[], flag: string): string | undefined {
+	const i = args.indexOf(flag);
+	return i === -1 ? undefined : args[i + 1];
+}
+
+function main(): void {
+	// ── legacy variant ──────────────────────────────────────────────────────────────
+	{
+		const args = buildResumePiArgs({
+			variant: "legacy",
+			sessionId: GID,
+			explicitExtensionArgs: EXT,
+			provider: "entwurf",
+			model: "claude-opus-4-8",
+			prompt: "continue the task",
+		});
+		ok("1 legacy has --no-extensions", args.includes("--no-extensions"));
+		ok("1 legacy has NO --entwurf-control", !args.includes("--entwurf-control"));
+		ok("3 legacy headless prefix --mode json -p", args[0] === "--mode" && args[1] === "json" && args[2] === "-p");
+		ok("3 legacy prompt is the final positional", args[args.length - 1] === "continue the task");
+		ok("4 legacy keeps ext args exactly once", args.filter((a) => a === "-e").length === 1);
+		ok("6 legacy provider laid out", valueAfter(args, "--provider") === "entwurf");
+		ok("6 legacy model laid out", valueAfter(args, "--model") === "claude-opus-4-8");
+		ok("6 legacy session-id laid out", valueAfter(args, "--session-id") === GID);
+		// model + prompt are the last three tokens: --model <m> <prompt>
+		ok(
+			"6 legacy --model <m> <prompt> tail",
+			args[args.length - 3] === "--model" &&
+				args[args.length - 2] === "claude-opus-4-8" &&
+				args[args.length - 1] === "continue the task",
+		);
+	}
+
+	// ── v2-control variant ──────────────────────────────────────────────────────────
+	{
+		const args = buildResumePiArgs({
+			variant: "v2-control",
+			sessionId: GID,
+			explicitExtensionArgs: EXT,
+			provider: "entwurf",
+			model: "claude-opus-4-8",
+			prompt: "resume now",
+			launchArgs: ["--approve"],
+		});
+		ok("2 v2 has --entwurf-control", args.includes("--entwurf-control"));
+		ok("2 v2 has NO --no-extensions", !args.includes("--no-extensions"));
+		ok("3 v2 keeps -p (prompt-as-turn NOT dropped)", args.includes("-p"));
+		ok("3 v2 headless prefix --mode json -p", args[0] === "--mode" && args[1] === "json" && args[2] === "-p");
+		ok("3 v2 prompt is the final positional", args[args.length - 1] === "resume now");
+		ok("4 v2 keeps ext args exactly once", args.filter((a) => a === "-e").length === 1);
+		ok("5 v2 includes launchArgs --approve", args.includes("--approve"));
+		ok("5 v2 --approve is before the prompt", args.indexOf("--approve") < args.length - 1);
+		ok("6 v2 provider laid out", valueAfter(args, "--provider") === "entwurf");
+		ok("6 v2 model laid out", valueAfter(args, "--model") === "claude-opus-4-8");
+		ok("6 v2 session-id laid out", valueAfter(args, "--session-id") === GID);
+		ok(
+			"6 v2 --model <m> <prompt> tail",
+			args[args.length - 3] === "--model" &&
+				args[args.length - 2] === "claude-opus-4-8" &&
+				args[args.length - 1] === "resume now",
+		);
+	}
+
+	// ── 5. legacy IGNORES launchArgs (no --approve leaks in) ──────────────────────────
+	{
+		const args = buildResumePiArgs({
+			variant: "legacy",
+			sessionId: GID,
+			explicitExtensionArgs: [],
+			provider: null,
+			model: "m",
+			prompt: "p",
+			launchArgs: ["--approve"], // present in input but legacy must ignore it
+		});
+		ok("5 legacy ignores launchArgs (no --approve)", !args.includes("--approve"));
+	}
+
+	// ── 6. null/undefined provider emits NO --provider flag ───────────────────────────
+	for (const provider of [null, undefined] as const) {
+		const args = buildResumePiArgs({
+			variant: "v2-control",
+			sessionId: GID,
+			explicitExtensionArgs: [],
+			provider,
+			model: "m",
+			prompt: "p",
+			launchArgs: [],
+		});
+		ok(`6 provider=${provider}: no --provider flag`, !args.includes("--provider"));
+		ok(`6 provider=${provider}: --model <m> <prompt> still tail`, args.slice(-3).join(" ") === "--model m p");
+	}
+
+	// ── 7. no cross-contamination across variants over the same identity ──────────────
+	{
+		const base = {
+			sessionId: GID,
+			explicitExtensionArgs: EXT,
+			provider: "entwurf",
+			model: "m",
+			prompt: "p",
+			launchArgs: ["--approve"],
+		} as const;
+		const legacy = buildResumePiArgs({ ...base, variant: "legacy" });
+		const v2 = buildResumePiArgs({ ...base, variant: "v2-control" });
+		ok("7 legacy-only flag absent from v2", !v2.includes("--no-extensions"));
+		ok("7 v2-only flag absent from legacy", !legacy.includes("--entwurf-control") && !legacy.includes("--approve"));
+	}
+
+	console.log(`\ncheck-entwurf-resume-args: ${passed} checks passed`);
+}
+
+main();