@junghanacs/entwurf 0.12.10 → 0.13.1

package/scripts/check-release-gate-outcomes.ts

@@ -0,0 +1,332 @@
+// Deterministic gate for the release-gate STEP OUTCOME protocol (P1).
+//
+// THE DEFECT THIS OWNS. The aggregate release gate documented — in run.sh's own
+// usage, README, and VERIFY — that a cut needs `LIVE=1` and `SKIP=0`. Nothing
+// enforced it. Exit authority read the FAIL counter alone, so
+// `./run.sh release-gate <dir>` returned 0 while printing 14 SKIPs and the words
+// "all green". And a step that WAS invoked could decline a prerequisite and exit
+// 0 — Cortex without `ENTWURF_ACP_CORTEX_CONNECTION` is the measured case — which
+// the aggregate counted as PASS. Both holes are the same shape: a skip that
+// cannot be told apart from an acceptance, which means a release summary cannot
+// prove the calls it claims.
+//
+// WHAT THIS GATE PINS, in the order the cells run (the order is load-bearing:
+// each mutant must die on ITS claim, so a cell that would fire first on another
+// cell's mutation is deliberately kept narrow):
+//   1. the protocol is ONE number, agreed across the shell and TS halves;
+//   2. the classifier never rounds a skip up to a pass;
+//   3. `--cut` refuses a MUST skip while a bare diagnostic run does not, AND the
+//      refusal names its cause — a step that RAN AND BROKE is a different fact
+//      from one that NEVER RAN, and the counters are never fudged to carry it;
+//   4. no LIVE smoke still carries the pre-P1 exit-0 skip shape;
+//   5. a real smoke invoked with LIVE unset propagates the protocol code out
+//      through run_ts (the "direct LIVE!=1" case);
+//   6. a run.sh wrapper that declines its own prerequisite does the same (the
+//      "internal prerequisite" case, Cortex being the one that was measured).
+//   7. every LIVE smoke is either wired into the aggregate or excluded for a
+//      reason the docs actually state — the protocol cannot vouch for a step the
+//      gate never lists.
+//
+// Cells 5-6 SPAWN the real subcommands rather than reasoning about them: the
+// whole defect was an assumption about what a step would do, so an assumption is
+// exactly what this gate must not make. They are cheap — each smoke declines
+// before it does any work.
+//
+// Pure + subprocess, no network/model — IN pnpm check.
+
+import { strict as assert } from "node:assert";
+import { execFileSync } from "node:child_process";
+import { globSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LIVE_SKIP_EXIT, LIVE_SKIP_MARKER } from "./lib/live-skip.ts";
+
+const REPO_DIR = fileURLToPath(new URL("..", import.meta.url));
+const SHELL_LIB = "scripts/lib/step-outcome.sh";
+
+/** Run a snippet with the shell half sourced; returns trimmed stdout. */
+function inShell(snippet: string): string {
+	return execFileSync("bash", ["-c", `. "${SHELL_LIB}"; ${snippet}`], {
+		cwd: REPO_DIR,
+		encoding: "utf8",
+		timeout: 20_000,
+	}).trim();
+}
+
+/** Invoke a real run.sh subcommand; returns its exit code + combined output. */
+function runSubcommand(sub: string, env: Record<string, string | undefined>): { code: number; output: string } {
+	const childEnv: Record<string, string> = {};
+	for (const [k, v] of Object.entries({ ...process.env, ...env })) {
+		if (v !== undefined) childEnv[k] = v;
+	}
+	try {
+		const out = execFileSync("bash", ["run.sh", sub], {
+			cwd: REPO_DIR,
+			encoding: "utf8",
+			timeout: 120_000,
+			env: childEnv,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		return { code: 0, output: out };
+	} catch (err) {
+		const e = err as { status?: number | null; stdout?: string; stderr?: string };
+		return { code: e.status ?? -1, output: `${e.stdout ?? ""}${e.stderr ?? ""}` };
+	}
+}
+
+// ===========================================================================
+// 1) ONE protocol, two languages. A drifted constant does not degrade
+//    gracefully — it silently reclassifies every skip in the aggregate.
+// ===========================================================================
+{
+	const shellValue = inShell('echo "$ENTWURF_STEP_SKIP_EXIT"');
+	assert.equal(
+		shellValue,
+		String(LIVE_SKIP_EXIT),
+		`[QK:SKIP-EXIT-ONE-PROTOCOL] ${SHELL_LIB} and scripts/lib/live-skip.ts must name the SAME skip exit code. ` +
+			"The smokes exit with the TS constant and the aggregate classifies with the shell one, so a drift between " +
+			"them turns every honest skip into a FAIL (or, the other way, into a PASS) with nothing in the summary " +
+			`saying so. shell=${shellValue} ts=${LIVE_SKIP_EXIT}`,
+	);
+	// The code must also stay clear of the ranges that already mean something
+	// else, or a dependency's unrelated verdict reads as a skip.
+	assert.ok(
+		LIVE_SKIP_EXIT > 4 && LIVE_SKIP_EXIT < 126,
+		"the skip code must avoid the per-tool contract band (0..4) and the shell's signal band (126+)",
+	);
+}
+
+// ===========================================================================
+// 2) The classifier. A skip is its own outcome, never rounded up or down.
+// ===========================================================================
+{
+	const table: Array<[string, string]> = [
+		["0", "PASS"],
+		[String(LIVE_SKIP_EXIT), "SKIP"],
+		["1", "FAIL"],
+		["2", "FAIL"],
+		["127", "FAIL"],
+		["137", "FAIL"],
+	];
+	for (const [code, expected] of table) {
+		const got = inShell(`entwurf_step_outcome ${code}`);
+		assert.equal(
+			got,
+			expected,
+			`[QK:STEP-OUTCOME-SKIP-NOT-PASS] exit ${code} must classify as ${expected}, got ${got}. A skip rounded up to ` +
+				"PASS is exactly the pre-P1 defect: the aggregate then reports acceptance for a step that told it, in the " +
+				"only channel it has, that it never ran. A skip rounded down to FAIL is the mirror error and makes the " +
+				"unattended diagnostic unusable.",
+		);
+	}
+}
+
+// ===========================================================================
+// 3) Cut authority. `--cut` is the executable half of "a CUT needs SKIP=0";
+//    without it the diagnostic must stay green so an unattended run is usable.
+// ===========================================================================
+{
+	const releasable = (failc: number, skipc: number, cut: number): boolean =>
+		inShell(`if entwurf_release_releasable ${failc} ${skipc} ${cut}; then echo YES; else echo NO; fi`) === "YES";
+
+	assert.ok(releasable(0, 0, 1), "a cut with no failures and no skips is releasable");
+	assert.ok(!releasable(1, 0, 1), "a failure blocks a cut");
+	assert.ok(!releasable(1, 0, 0), "a failure blocks the diagnostic too — FAIL was always blocking");
+	assert.ok(
+		releasable(0, 3, 0),
+		"a DIAGNOSTIC run with skips stays exit 0 — an unattended `./run.sh release-gate` must remain runnable, and " +
+			"turning it red was never the ask",
+	);
+	assert.ok(
+		!releasable(0, 3, 1),
+		"[QK:CUT-REFUSES-SKIP] `--cut` must refuse a MUST SKIP. This is the whole point: the release procedure said " +
+			'"a CUT needs LIVE=1, SKIP=0" in prose while the code returned 0 with 14 skips, so a summary could be quoted ' +
+			"as acceptance for calls that never happened. It also removes the need for a separate LIVE assertion — with " +
+			"LIVE unset every LIVE-gated step skips, and the skip count is what blocks.",
+	);
+
+	// …and the refusal must SAY WHICH of the two it is. A blocked cut caused by a
+	// broken call and one caused by an absent prerequisite need different actions
+	// from whoever reads the record, and the counters must not be fudged to carry
+	// that (a synthesized FAIL=1 for a policy block erases the distinction).
+	const verdict = (failc: number, skipc: number, cut: number): string =>
+		inShell(`entwurf_release_verdict ${failc} ${skipc} ${cut}`);
+
+	assert.equal(verdict(0, 0, 1), "cut: OK", "a clean cut says so in one token");
+	assert.equal(
+		verdict(0, 3, 0),
+		"cut: n/a (diagnostic, 3 SKIP)",
+		"a diagnostic run names its skips without claiming a cut",
+	);
+	assert.equal(verdict(0, 0, 0), "cut: n/a (diagnostic)", "a clean diagnostic run still does not claim a cut");
+	assert.equal(
+		verdict(1, 0, 1),
+		"cut: BLOCKED (MUST FAIL)",
+		"a step that RAN AND BROKE must be named as a failure — that is a defect to fix",
+	);
+	assert.equal(
+		verdict(0, 3, 1),
+		"cut: BLOCKED (MUST SKIP)",
+		"[QK:CUT-VERDICT-NAMES-CAUSE] a cut blocked ONLY by skips must say so in its own token, distinct from a failure " +
+			"block. An operator (and the P5 release record) reads two different actions out of these: a MUST FAIL is a " +
+			"broken call to fix, a MUST SKIP is a prerequisite to supply. Collapsing them into one string — or worse, " +
+			"synthesizing FAIL=1 for the policy block — throws away the exact distinction this protocol was built to make.",
+	);
+	assert.equal(
+		verdict(2, 5, 1),
+		"cut: BLOCKED (MUST FAIL)",
+		"when both are present the FAILURE is the headline — a broken call outranks a missing prerequisite",
+	);
+}
+
+// ===========================================================================
+// 4) No LIVE smoke still carries the pre-P1 skip shape (static, all of them).
+//    A future smoke that hand-rolls `exit 0` on a skip re-opens the hole for
+//    one lane only, which is precisely how this survived so long.
+// ===========================================================================
+{
+	const smokes = globSync("scripts/smoke-*live*.ts", { cwd: REPO_DIR }).sort();
+	assert.ok(smokes.length >= 15, `expected the LIVE smoke family, found ${smokes.length}`);
+	let liveGated = 0;
+	for (const rel of smokes) {
+		const src = readFileSync(join(REPO_DIR, rel), "utf8");
+		if (!src.includes("process.env.LIVE")) continue; // gated in run.sh instead (cell 6 owns that surface)
+		liveGated++;
+		// ONE assertion, three ways to fail it: no protocol import, or either of
+		// the two pre-P1 shapes (exit 0 / bare return) still inside the LIVE gate.
+		// Kept as one so the claim owns every way a smoke can go back to being
+		// indistinguishable from success — a split would let a mutation die on an
+		// unclaimed sibling assertion instead of here.
+		const importsProtocol = src.includes('from "./lib/live-skip.ts"');
+		const exitsZero = /LIVE !== "1"[\s\S]{0,400}?process\.exit\(0\)/.test(src);
+		const bareReturns = /LIVE !== "1"[\s\S]{0,400}?\n\t+return;/.test(src);
+		assert.ok(
+			importsProtocol && !exitsZero && !bareReturns,
+			`[QK:NO-SMOKE-SKIPS-WITH-ZERO] ${basename(rel)} gates on LIVE but does not decline through skipLive ` +
+				`(importsProtocol=${importsProtocol} exitsZero=${exitsZero} bareReturns=${bareReturns}). Every LIVE smoke ` +
+				"must take the one protocol exit — a hand-rolled `process.exit(0)` or bare `return` is indistinguishable " +
+				"from success, which is exactly what let the aggregate count a never-run step as PASS.",
+		);
+	}
+	assert.ok(liveGated >= 15, `expected most LIVE smokes to gate on LIVE, got ${liveGated}`);
+}
+
+// ===========================================================================
+// 5) REAL propagation — the direct `LIVE!=1` case, end to end through run_ts.
+//    Static source pins cannot see a transport that swallows the code.
+// ===========================================================================
+{
+	const { code, output } = runSubcommand("smoke-acp-raw-turn-live", { LIVE: undefined });
+	assert.equal(
+		code,
+		LIVE_SKIP_EXIT,
+		`[QK:LIVE-SKIP-IS-PROTOCOL-EXIT] a LIVE smoke invoked with LIVE unset must leave the protocol's SKIP code on ` +
+			`the process, all the way out through run_ts — got exit ${code}. Exit 0 here is the original defect: the ` +
+			`aggregate cannot tell "I declined" from "I passed", so it reports acceptance. Output: ` +
+			`${JSON.stringify(output.slice(-300))}`,
+	);
+	assert.ok(
+		output.includes(LIVE_SKIP_MARKER),
+		`the skip must also be readable by a human in the log — ${LIVE_SKIP_MARKER} names the missing prerequisite so an ` +
+			"operator who hits a red --cut run knows what to supply. Output: " +
+			JSON.stringify(output.slice(-300)),
+	);
+}
+
+// ===========================================================================
+// 6) REAL propagation — a run.sh WRAPPER declining its own prerequisite. This
+//    is the second skip surface: some smokes never reach their .ts file at all.
+// ===========================================================================
+{
+	const viaWrapper = runSubcommand("smoke-acp-cortex-live", { LIVE: undefined });
+	assert.equal(
+		viaWrapper.code,
+		LIVE_SKIP_EXIT,
+		`[QK:WRAPPER-SKIP-IS-PROTOCOL-EXIT] a run.sh smoke WRAPPER that declines a prerequisite must return the protocol ` +
+			`SKIP code, not 0 — got exit ${viaWrapper.code}. The wrapper is a skip surface of its own (cortex, matrix, ` +
+			"spawn-live and spawn-resume all decline before their .ts is ever reached), so fixing only the TypeScript " +
+			`half would leave the aggregate counting those as PASS. Output: ${JSON.stringify(viaWrapper.output.slice(-300))}`,
+	);
+
+	// The measured Cortex cell: LIVE IS set, but the connection the adapter needs
+	// is not. Which branch declines (the wrapper's `cortex` PATH check or the
+	// smoke's own connection check) depends on the host; the OUTCOME must not.
+	const missingPrereq = runSubcommand("smoke-acp-cortex-live", {
+		LIVE: "1",
+		ENTWURF_ACP_CORTEX_CONNECTION: undefined,
+	});
+	assert.equal(
+		missingPrereq.code,
+		LIVE_SKIP_EXIT,
+		"LIVE=1 with no ENTWURF_ACP_CORTEX_CONNECTION must be a SKIP, not a PASS — this is the exact cell that made a " +
+			"cortex-less host look like cortex acceptance. Output: " +
+			JSON.stringify(missingPrereq.output.slice(-300)),
+	);
+}
+
+// ===========================================================================
+// 7) NO SILENT AGGREGATE OMISSION. The protocol tells the truth about the steps
+//    the gate RUNS; it says nothing about steps the gate never lists. Three LIVE
+//    smokes (cortex, spawn-live, claude-native-resume) sat outside the aggregate
+//    with no stated reason until 2026-07-31, so a green cut was silent about the
+//    second backend, the spawn substrate, and native resume.
+//
+//    So: every LIVE smoke is either WIRED into release_gate or EXCLUDED for a
+//    reason an operator can read in the docs. The exclusion half is checked
+//    against the doc text, not against a list in this file — an exclusion that
+//    only this gate believes in is how the omission would come back.
+// ===========================================================================
+{
+	const runSh = readFileSync(join(REPO_DIR, "run.sh"), "utf8");
+	const gateBody = runSh.slice(runSh.indexOf("release_gate() {"), runSh.indexOf("# 5. Summary"));
+	assert.ok(gateBody.length > 1000, "located the release_gate body");
+
+	// name → the sentence in the docs that carries its exclusion, and where.
+	const DOCUMENTED_EXCLUSIONS: Record<string, [file: string, sentence: string]> = {
+		"smoke-acp-long-turn-live": ["VERIFY.md", "on-demand, not part of `release-gate`"],
+		"smoke-agy-native-push-live": ["VERIFY.md", "Aggregate release-gate does not own an agy conversation id"],
+		"smoke-acp-ordering-probe-live": ["docs/acp-backend-rail.md", "opt-in paired observation"],
+		// Cortex needs an external Snowflake connection the HOST owns, so an aggregate
+		// that required it would block every cut taken without that account. Excluded —
+		// NOT waived: its direct call stays required for a Cortex-rail cut, and running
+		// it without the connection still reports protocol SKIP rather than a pass.
+		"smoke-acp-cortex-live": ["VERIFY.md", "The 0.13.1 aggregate does not re-certify Cortex"],
+	};
+
+	const allLive = globSync("scripts/smoke-*live*.{ts,sh}", { cwd: REPO_DIR })
+		.map((p) => basename(p).replace(/\.(ts|sh)$/, ""))
+		.sort();
+	assert.ok(allLive.length >= 18, `expected the full LIVE smoke family, found ${allLive.length}`);
+
+	for (const name of allLive) {
+		const wired = gateBody.includes(`"$self" ${name}\n`) || gateBody.includes(`"$self" ${name} `);
+		const excused = DOCUMENTED_EXCLUSIONS[name];
+		if (wired) {
+			assert.ok(!excused, `${name} is both wired and excused — pick one`);
+			continue;
+		}
+		assert.ok(
+			excused,
+			`[QK:NO-SILENT-AGGREGATE-OMISSION] ${name} is neither wired into release_gate nor excluded in the docs. ` +
+				"A LIVE smoke that exists but is never listed makes a green cut silent about the axis it covers — exactly " +
+				"how cortex (the second shipped backend), spawn-live and claude-native-resume went unrun for releases. " +
+				"Wire it, or state the exclusion where an operator reads it.",
+		);
+		const [file, sentence] = excused as [string, string];
+		assert.ok(
+			readFileSync(join(REPO_DIR, file), "utf8").includes(sentence),
+			`${name} claims a documented exclusion, but ${file} no longer says "${sentence}" — an exclusion only this ` +
+				"gate believes in is not documented",
+		);
+	}
+}
+
+console.log(
+	"[check-release-gate-outcomes] ok — STEP OUTCOME protocol: one skip exit code shared by the shell and TS halves " +
+		`(${LIVE_SKIP_EXIT}, clear of the per-tool 0..4 and shell 126+ bands), classifier maps 0→PASS / skip→SKIP / ` +
+		"everything else→FAIL (never rounding a skip up), `--cut` refuses a MUST SKIP while a bare diagnostic run stays " +
+		"exit 0, no LIVE smoke still carries the pre-P1 exit-0 skip shape, and both real skip surfaces were INVOKED and " +
+		"observed to propagate the code: a smoke with LIVE unset (through run_ts, with its operator-readable marker) and " +
+		"a run.sh wrapper declining its own prerequisite (including the measured LIVE=1 no-cortex-connection cell); and every " +
+		"LIVE smoke is either wired into release_gate or excluded by a sentence the docs still carry",
+);

package/scripts/check-shell-quote.ts

@@ -5,9 +5,10 @@
  * SSH command strings with `JSON.stringify`, which is NOT a shell-safe escape.
  * Backticks and `$(...)` inside a user prompt got executed by the remote shell
  * before pi ever saw them. The fix introduced `shellQuote()` (POSIX `'...'`
- * with `'\''` escape) in two places:
- *   - pi-extensions/lib/entwurf-core.ts (the one remaining site; the entwurf.ts /
+ * with `'\''` escape) in:
+ *   - pi-extensions/lib/entwurf-core.ts (the one remaining core site; the entwurf.ts /
  *     entwurf-async.ts siblings this once cross-checked were removed in 0.12)
+ *   - pi-extensions/lib/acp/backend-adapter.ts (cortex CORTEX_ACP_COMMAND override arg quoting)
  *
  * This script enforces two invariants:
  *   1. `shellQuote()` source matches the reference implementation byte-for-byte.
@@ -15,7 +16,6 @@
  *      payload classes that caused the original incident — backtick command
  *      substitution, `$(...)` command substitution, `$VAR` expansion, embedded
  *      single quotes, whitespace, empty string, non-ASCII text.
- *
  * No process spawn, no SSH, no API. Pure-string verification — safe in `pnpm
  * check` chain.
  */
@@ -38,7 +38,7 @@ const REFERENCE_BODY = `function shellQuote(value: string): string {
 \treturn \`'\${value.replace(/'/g, \`'\\\\''\`)}\`;
 }`;
 
-const SOURCE_SITES = ["pi-extensions/lib/entwurf-core.ts"] as const;
+const SOURCE_SITES = ["pi-extensions/lib/entwurf-core.ts", "pi-extensions/lib/acp/backend-adapter.ts"] as const;
 
 // Match the function block from `function shellQuote` up to the closing brace.
 // Tab indentation is required (matches the rest of the repo).

package/scripts/fixtures/probe-cli-shim

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// §11-7-c B-name-snapshot producer — the launcher the SDK actually execs.
+//
+// EXTENSIONLESS ON PURPOSE, and that is a contract, not a style choice. The SDK
+// picks its launch branch off a pure suffix test: a path ending in one of
+// SDK_SCRIPT_SUFFIXES (.js/.mjs/.tsx/.ts/.jsx) is run as `node|bun <path>`, and
+// anything else is spawned DIRECTLY. The probe asserts the native branch instead
+// of reproducing the interpreter choice (probe-cli-target.ts), so the instrument
+// itself has to sit on that branch too — hence no extension, a shebang, and the
+// executable bit tracked in git. Renaming this file to *.js would silently move
+// the shim onto the other launch branch.
+//
+// It stays two lines because an extensionless file is outside `tsc --noEmit` and
+// outside biome: every behaviour worth typechecking, linting and mutating lives
+// in ../lib/probe-cli-shim.ts, which check-probe-cli-shim drives as a real
+// process. Node >=24 (package.json engines) with "type": "module" resolves this
+// file as ESM and strips types from the imported .ts SSOT.
+import { runProbeCliShim } from "../lib/probe-cli-shim.ts";
+
+runProbeCliShim();

package/scripts/fixtures/probe-mcp-server.ts

@@ -1,4 +1,5 @@
-// Tiny stdio MCP server used ONLY by smoke-acp-mcp-live (S2g LIVE 1).
+// Tiny stdio MCP server used by smoke-acp-mcp-live (S2g LIVE 1) and by the
+// §11-7 ordering probe (smoke-acp-ordering-probe-live).
 //
 // It exposes ONE tool — `probe_nonce` — that returns a per-run secret nonce
 // supplied via the PROBE_NONCE env var. The smoke registers this server in a
@@ -9,25 +10,180 @@
 // is broken (the pre-S2g hardcoded `mcpServers:[]`), the tool never exists and
 // the nonce cannot appear.
 //
+// §11-7 ordering-probe mode — active ONLY when PROBE_MCP_EVENT_LOG is set
+// (smoke-acp-mcp-live never sets it, so its behavior is unchanged):
+//   - PROBE_MCP_STARTUP_DELAY_MS delays the transport connect — the controlled
+//     input the probe injects instead of trying to observe a window that has no
+//     observable signal on this server's ACP surface;
+//   - the tool takes a REQUIRED `probeRunId` argument, the cross-layer join key
+//     (§11-7: the ACP toolCallId and the MCP JSON-RPC id share no namespace, so
+//     correlation must ride an argument we control);
+//   - every wire step appends to the shared NDJSON event log, including THE
+//     wire-availability marker `tools_list_response_forwarded`, emitted only
+//     after the ENTIRE tools/list response frame was write()-n to downstream
+//     stdio AND the write callback fired. The SDK's own send() resolves on
+//     buffered-write/drain — NOT the write callback — which is exactly the
+//     false-green §11-7 forbids, so probe mode swaps in a callback-forwarding
+//     transport instead of trusting send().
+//
 // Lives under the repo's scripts/fixtures/ so its `@modelcontextprotocol/sdk`
 // import resolves against the repo node_modules even though the server is spawned
 // (by the claude ACP child) with an arbitrary scratch cwd. Deliberately minimal:
-// no identity / env coupling beyond PROBE_NONCE, so a failure isolates to "did
-// the operator mcpServers reach newSession" — not to entwurf-bridge wiring.
+// no identity / env coupling beyond the PROBE_* vars, so a failure isolates to
+// "did the operator mcpServers reach newSession" — not to entwurf-bridge wiring.
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
+import { z } from "zod";
+import {
+	appendProbeEvent,
+	PROBE_EXPECTED_TOOL as EXPECTED_TOOL,
+	PROBE_ENV,
+	PROBE_EVENTS,
+	type ProbeEventName,
+} from "../lib/probe-event-log.ts";
+
+const eventLog = process.env[PROBE_ENV.eventLog];
+const probeMode = typeof eventLog === "string" && eventLog.length > 0;
+const runId = process.env[PROBE_ENV.runId] ?? "unknown-run";
+const startupDelayMs = Math.max(0, Number(process.env[PROBE_ENV.startupDelayMs] ?? "0") || 0);
+
+function emit(event: ProbeEventName, payload: Record<string, unknown> = {}): void {
+	if (probeMode && eventLog) appendProbeEvent(eventLog, runId, event, payload);
+}
+
+// ---------------------------------------------------------------------------
+// §11-7 instrumented transport — write-callback semantics + wire markers.
+// ---------------------------------------------------------------------------
+
+type JsonRpcMessage = {
+	id?: string | number;
+	method?: string;
+	params?: { name?: string; arguments?: Record<string, unknown> };
+	result?: { tools?: Array<{ name?: string }> };
+};
+
+class InstrumentedStdioServerTransport extends StdioServerTransport {
+	// JSON-RPC request id → method, so a response frame can be attributed to the
+	// request that caused it (the response itself carries no method).
+	private readonly pendingMethods = new Map<string | number, string>();
+
+	constructor() {
+		super();
+		// The SDK protocol layer assigns `transport.onmessage = handler` after
+		// connect; the base class reads `this.onmessage`. Intercept the assignment
+		// so every inbound frame is stamped BEFORE the handler runs — receipt
+		// markers, not handler-return markers. Installed via defineProperty because
+		// the base declares `onmessage` as a plain property (TS2611 forbids a
+		// static accessor override) yet never assigns it in its constructor, so an
+		// instance accessor here wins cleanly.
+		let raw: ((message: unknown, extra?: unknown) => void) | undefined;
+		const stampInbound = (msg: JsonRpcMessage) => this.stampInbound(msg);
+		Object.defineProperty(this, "onmessage", {
+			get(): ((message: unknown, extra?: unknown) => void) | undefined {
+				if (!raw) return undefined;
+				return (message: unknown, extra?: unknown) => {
+					stampInbound(message as JsonRpcMessage);
+					raw?.(message, extra);
+				};
+			},
+			set(handler: ((message: unknown, extra?: unknown) => void) | undefined) {
+				raw = handler;
+			},
+		});
+	}
+
+	private stampInbound(msg: JsonRpcMessage): void {
+		if (typeof msg?.method !== "string") return;
+		if (msg.id !== undefined) this.pendingMethods.set(msg.id, msg.method);
+		if (msg.method === "initialize") {
+			emit(PROBE_EVENTS.fixtureInitializeReceived, { jsonrpcId: msg.id });
+		} else if (msg.method === "tools/list") {
+			emit(PROBE_EVENTS.fixtureToolsListReceived, { jsonrpcId: msg.id });
+		} else if (msg.method === "tools/call") {
+			emit(PROBE_EVENTS.fixtureToolsCallReceived, {
+				jsonrpcId: msg.id,
+				tool: msg.params?.name,
+				probeRunId: msg.params?.arguments?.probeRunId,
+			});
+		}
+	}
+
+	// Write with the CALLBACK, not the buffered-return the SDK send() settles
+	// for: the callback fires when the frame reached the OS pipe, which is the
+	// §11-7 definition of "forwarded". Markers are emitted inside the callback
+	// so they can never precede the hand-off they claim — and ONLY on a
+	// SUCCESSFUL callback: an errored write (EPIPE, closed stream) must reject,
+	// never stamp, or the marker would claim a hand-off that did not happen.
+	override send(message: unknown): Promise<void> {
+		const json = serializeMessage(message as never);
+		return new Promise((resolve, reject) => {
+			(this as unknown as { _stdout: NodeJS.WriteStream })._stdout.write(json, (err?: Error | null) => {
+				if (err) {
+					reject(err);
+					return;
+				}
+				this.stampOutbound(message as JsonRpcMessage);
+				resolve();
+			});
+		});
+	}
+
+	private stampOutbound(msg: JsonRpcMessage): void {
+		if (msg?.id === undefined || typeof msg.method === "string") return;
+		const requestMethod = this.pendingMethods.get(msg.id);
+		if (requestMethod === undefined) return;
+		this.pendingMethods.delete(msg.id);
+		if (requestMethod === "tools/list") {
+			const toolNames = (msg.result?.tools ?? []).map((t) => t?.name).filter((n): n is string => !!n);
+			if (toolNames.includes(EXPECTED_TOOL)) {
+				emit(PROBE_EVENTS.toolsListResponseForwarded, { jsonrpcId: msg.id, tools: toolNames });
+			}
+		} else if (requestMethod === "tools/call") {
+			emit(PROBE_EVENTS.fixtureToolsCallReplied, { jsonrpcId: msg.id });
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Server — one tool in both modes; probe mode adds the REQUIRED join key.
+// ---------------------------------------------------------------------------
+
+emit(PROBE_EVENTS.fixtureProcessStart, { startupDelayMs });
 
 const server = new McpServer({ name: "probe", version: "0.0.1" });
 
-server.tool(
-	"probe_nonce",
-	"Return this session's secret probe nonce. Call this when asked for the probe nonce.",
-	{},
-	async () => ({
-		content: [{ type: "text", text: `PROBE_NONCE=${process.env.PROBE_NONCE ?? "MISSING"}` }],
-	}),
-);
+if (probeMode) {
+	server.tool(
+		EXPECTED_TOOL,
+		"Return this session's secret probe nonce. Call this when asked for the probe nonce, " +
+			"passing the exact probeRunId given in the prompt.",
+		{ probeRunId: z.string().describe("The exact probeRunId string given in the prompt.") },
+		async () => ({
+			content: [{ type: "text", text: `PROBE_NONCE=${process.env[PROBE_ENV.nonce] ?? "MISSING"}` }],
+		}),
+	);
+} else {
+	server.tool(
+		EXPECTED_TOOL,
+		"Return this session's secret probe nonce. Call this when asked for the probe nonce.",
+		{},
+		async () => ({
+			content: [{ type: "text", text: `PROBE_NONCE=${process.env[PROBE_ENV.nonce] ?? "MISSING"}` }],
+		}),
+	);
+}
+
+// The injected startup delay sits BEFORE the transport exists at all — the
+// probe's controlled input models a slow-to-serve MCP server, so nothing may be
+// readable on the wire until the delay elapses.
+if (startupDelayMs > 0) {
+	emit(PROBE_EVENTS.fixtureDelayStart, { delayMs: startupDelayMs });
+	await new Promise((resolve) => setTimeout(resolve, startupDelayMs));
+	emit(PROBE_EVENTS.fixtureDelayEnd, { delayMs: startupDelayMs });
+}
 
-const transport = new StdioServerTransport();
+const transport = probeMode ? new InstrumentedStdioServerTransport() : new StdioServerTransport();
 await server.connect(transport);
+emit(PROBE_EVENTS.fixtureTransportConnected, {});

package/scripts/lib/live-skip.ts

@@ -0,0 +1,33 @@
+// The TypeScript half of the release-gate STEP OUTCOME protocol
+// (scripts/lib/step-outcome.sh owns the contract prose and the shell half).
+//
+// A LIVE smoke that lacks a prerequisite must be DISTINGUISHABLE from one that
+// ran and passed. Before P1 every smoke exited 0 on a skip, so `run_live_step`
+// counted it PASS and the release summary could not prove a required call had
+// happened at all. `skipLive` is the single exit any smoke takes when it
+// declines: one reserved code the aggregate classifies as SKIP, plus one marker
+// line so an operator reading the log sees WHICH prerequisite was missing
+// without decoding a number.
+//
+// The two halves must agree. `check-release-gate-outcomes` reads this constant
+// and the shell one and refuses a mismatch — a protocol that drifted between
+// languages would silently reclassify every skip as a failure (or worse).
+
+/** SKIP. Must equal `ENTWURF_STEP_SKIP_EXIT` in scripts/lib/step-outcome.sh. */
+export const LIVE_SKIP_EXIT = 97;
+
+/** The machine-greppable prefix every skip line carries. */
+export const LIVE_SKIP_MARKER = "[entwurf:skip]";
+
+/**
+ * Decline this smoke: print the marker + reason on stderr and exit with the
+ * protocol's SKIP code. Never returns.
+ *
+ * `label` is the smoke's own name (so a multi-step aggregate log stays
+ * attributable); `reason` states the missing prerequisite AND how to supply it —
+ * an operator who hits a SKIP in a cut run needs the fix, not the diagnosis.
+ */
+export function skipLive(label: string, reason: string): never {
+	console.error(`${LIVE_SKIP_MARKER} ${label} — ${reason}`);
+	process.exit(LIVE_SKIP_EXIT);
+}