@junghanacs/entwurf 0.14.1 → 0.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.14.1",
+	"version": "0.14.2",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for Claude Code, Codex, Antigravity, and pi harnesses.",
 	"license": "MIT",
 	"author": {
@@ -74,23 +74,23 @@
 		"claudeCodeFloor": ">=2.1.217"
 	},
 	"dependencies": {
-		"@agentclientprotocol/claude-agent-acp": "0.66.0",
+		"@agentclientprotocol/claude-agent-acp": "0.70.0",
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@anthropic-ai/sdk": "0.100.1",
 		"@modelcontextprotocol/sdk": "^1.12.1",
 		"zod": "^3.25.0 || ^4.0.0"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-ai": ">=0.84.1 <0.85",
-		"@earendil-works/pi-coding-agent": ">=0.84.1 <0.85",
-		"@earendil-works/pi-tui": ">=0.84.1 <0.85",
+		"@earendil-works/pi-ai": ">=0.84.2 <0.85",
+		"@earendil-works/pi-coding-agent": ">=0.84.2 <0.85",
+		"@earendil-works/pi-tui": ">=0.84.2 <0.85",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.13",
-		"@earendil-works/pi-ai": "0.84.1",
-		"@earendil-works/pi-coding-agent": "0.84.1",
-		"@earendil-works/pi-tui": "0.84.1",
+		"@earendil-works/pi-ai": "0.84.2",
+		"@earendil-works/pi-coding-agent": "0.84.2",
+		"@earendil-works/pi-tui": "0.84.2",
 		"@types/node": "^24.3.0",
 		"husky": "^9.1.7",
 		"rregex": "1.13.1",
@@ -145,7 +145,7 @@
 		"check:toolchain": "pnpm lint && pnpm typecheck",
 		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface",
 		"check:contracts": "./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-lock && ./run.sh check-entwurf-v2-decider && ./run.sh check-entwurf-v2-matrix && ./run.sh check-entwurf-v2-release && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-send-fallback && ./run.sh check-entwurf-v2-mailbox && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-runner && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-entwurf-resume-args && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-entwurf-facts && ./run.sh check-control-socket-path && ./run.sh check-socket-discovery && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment",
-		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-meta-facts && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex",
+		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex",
 		"check:package": "./run.sh check-install-surface && ./run.sh smoke-meta-install-state && ./run.sh smoke-agy-install-state && ./run.sh check-package-source-routing && ./run.sh check-install-preflight && ./run.sh check-pack"
 	},
 	"pi": {

package/pi-extensions/lib/acp/backend.ts

@@ -161,6 +161,35 @@ interface AcpBridgeEvent {
 	decision?: "approved" | "cancelled";
 }
 
+/**
+ * A one-shot latch for "the child has ended", created at spawn and settled by
+ * `onChildGone`. `settled` answers the question with no waiting at all; the
+ * promise is only for the bounded post-mortem window (settleChildEnd).
+ */
+interface ChildEndLatch {
+	settled: boolean;
+	promise: Promise<void>;
+	/** Called exactly once by onChildGone; cleared so a second end is a no-op. */
+	settle?: () => void;
+}
+
+function makeChildEndLatch(): ChildEndLatch {
+	let settle!: () => void;
+	const promise = new Promise<void>((resolve) => {
+		settle = resolve;
+	});
+	const latch: ChildEndLatch = {
+		settled: false,
+		promise,
+		settle: () => {
+			latch.settled = true;
+			latch.settle = undefined;
+			settle();
+		},
+	};
+	return latch;
+}
+
 interface BridgeSession {
 	key: string;
 	cwd: string;
@@ -183,8 +212,36 @@ interface BridgeSession {
 	stderrTail: string[];
 	/** How the child ended, once it has — folded into the prompt-phase error. */
 	exit?: { code: number | null; signal: NodeJS.Signals | null };
+	/**
+	 * LATCH for the child's end, readable at ANY time — deliberately not a
+	 * callback.
+	 *
+	 * `notifyChildGone` lives only between the two lines of
+	 * `awaitAcpPromptTurn`'s try/finally, so it can carry the exit status only
+	 * when the child's `exit` event wins the race against the transport — and on
+	 * the shape this backend actually runs, it does not. With piped stdio on
+	 * Linux the child's stdout EOF was measured landing about a millisecond BEFORE
+	 * node emits `exit`, for a clean exit and for SIGKILL alike (issue #72). The
+	 * SDK's generic "ACP connection closed" therefore settles the race first,
+	 * `finally` clears the callback, and the exit status arriving one tick later
+	 * has nowhere to go — which is how #72's field sample reached the operator
+	 * naming neither exit code nor signal. The opposite order stays possible and
+	 * is still handled (notifyChildGone), so both are covered by the gate.
+	 *
+	 * The latch outlives the race: `settled` is the durable fact and `promise`
+	 * lets a failing turn wait a BOUNDED moment for a late end (settleChildEnd).
+	 */
+	childEnd: ChildEndLatch;
 	/** Set while a prompt is in flight so a child death can close it (awaitAcpPromptTurn). */
 	notifyChildGone?: (err: Error) => void;
+	/**
+	 * This TURN owns reporting the child's end, so the next turn must not also
+	 * announce it. Raised at the top of a failure path — BEFORE the bounded
+	 * settle and before any teardown — so an end observed during that window is
+	 * still a natural one (we have not signalled anything yet) but is reported
+	 * exactly once, by the turn that failed on it.
+	 */
+	reporting?: boolean;
 	/**
 	 * We are tearing this child down ON PURPOSE (turn-scoped teardown, config
 	 * drift, error/abort cleanup). Its exit is then expected, not news: without
@@ -229,10 +286,13 @@ function onChildGone(session: BridgeSession, exit?: { code: number | null; signa
 	if (exit) session.exit = exit;
 	if (bridgeSessions.get(session.key) === session) bridgeSessions.delete(session.key);
 	retainedChildren.delete(session.child);
+	// Close the latch FIRST and unconditionally: it is the durable fact, and a
+	// failing turn may already be waiting on it inside its bounded settle window.
+	session.childEnd.settle?.();
 	if (session.notifyChildGone) {
 		// A turn was waiting on this child — it reports the death itself.
 		session.notifyChildGone(childEndedError(session));
-	} else if (!session.retiring) {
+	} else if (!session.retiring && !session.reporting) {
 		// Died BETWEEN turns with no turn to fail and nobody tearing it down, so
 		// nobody has seen it. Without this the next turn would silently open a
 		// fresh child and read as an ordinary cold start, hiding that the backend
@@ -281,6 +341,139 @@ function childEndedError(session: BridgeSession): Error {
 	);
 }
 
+/**
+ * The BOUNDED post-mortem window a turn that ALREADY failed may wait for the
+ * child's exit status.
+ *
+ * This is NOT a prompt deadline and must never become one: nothing here can end
+ * a running turn. It opens only after the prompt has already settled as a
+ * transport closure, and it closes on the child's own `exit` — which follows the
+ * stdout EOF by about a millisecond, so this is headroom, not a felt wait.
+ */
+const CHILD_END_SETTLE_MS = 500;
+
+/**
+ * The SDK's exact words for "the transport ended under a pending request"
+ * (`@agentclientprotocol/sdk` jsonrpc.js / acp.js:
+ * `closeSignal.reason ?? new Error("ACP connection closed")`).
+ *
+ * Matched EXACTLY, not by substring: this text appears only when the close
+ * carried NO reason — a clean stdout EOF rather than an errored stream — which
+ * is the one failure shape that arrives with no lifecycle facts of its own. A
+ * close that DID carry a reason already explains itself and must not be given a
+ * settle delay, and our own `childEndedError` already names the exit status.
+ * Widening this to a substring test would put that delay on errors that do not
+ * need it.
+ */
+const ACP_CONNECTION_CLOSED_TEXT = "ACP connection closed";
+
+function isAcpConnectionClosure(err: unknown): boolean {
+	const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+	return message.trim() === ACP_CONNECTION_CLOSED_TEXT;
+}
+
+/**
+ * Wait a BOUNDED moment for a child end that the transport already implied.
+ *
+ * Resolves immediately when the latch is already closed (the common case once
+ * the ~1ms gap has passed) and never rejects. The timer is deliberately NOT
+ * unref'd: it is the only thing that ends this wait, so letting the loop drain
+ * past it would leave a failing turn unsealed — the opposite of the honesty this
+ * exists for. It is cleared on both exits, so it holds nothing open.
+ */
+async function settleChildEnd(latch: ChildEndLatch, ms: number): Promise<void> {
+	if (latch.settled) return;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		await Promise.race([
+			latch.promise,
+			new Promise<void>((resolve) => {
+				timer = setTimeout(resolve, ms);
+			}),
+		]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+/**
+ * The lifecycle line appended to a transport-closure failure, so the operator
+ * reads WHICH phase died and HOW the child ended.
+ *
+ * Wording is load-bearing for the same reason `childEndedError`'s is: pi
+ * classifies a failed assistant message against `RETRYABLE_PROVIDER_ERROR_PATTERN`
+ * (@earendil-works/pi-ai `utils/retry`), whose terms include "timed out",
+ * "timeout", "terminated", "connection lost" and "ended without". None of those
+ * may appear here, or a dead child would put a full cold prompt replay back on
+ * the table — with the tool side effects this turn already produced.
+ *
+ * That pattern is a bare substring alternation (`new RegExp(terms.join("|"), "i")`
+ * — NO word boundaries) and its terms enumerate the HTTP statuses "429", "500",
+ * "502", "503", "504" and "524". So the settle bound is deliberately NOT interpolated: rendering
+ * CHILD_END_SETTLE_MS made this line say "within 500ms", which pi read as an
+ * HTTP 500 and classified as transient. Naming the window in prose keeps a later
+ * change of that constant from silently re-arming the replay — do not "improve"
+ * this by putting the number back; the bound belongs in the code and the gate.
+ *
+ * The three endings are kept DISTINCT on purpose (issue #72 Done-when): an
+ * exit code, a signal, and "we waited and it never said" are three different
+ * facts, and collapsing them is what made the original sample unreadable.
+ */
+function childEndLifecycleLine(opts: {
+	/** "pre-prompt" covers a new turn's bootstrap AND a reuse turn's pre-send steps. */
+	phase: "pre-prompt" | "prompt";
+	exit?: { code: number | null; signal: NodeJS.Signals | null };
+	ended: boolean;
+}): string {
+	const where =
+		opts.phase === "prompt"
+			? "the ACP backend connection closed while the prompt was still in flight"
+			: "the ACP backend connection closed before this turn's prompt was sent";
+	const how = opts.ended
+		? `the child ended (${describeChildEnd(opts.exit)})`
+		: "the child reported no exit status within the bounded post-mortem window";
+	return `[acp] lifecycle: ${where} — ${how}; this turn has no answer`;
+}
+
+/**
+ * The failure path's post-mortem: enrich ONLY the transport-closure shape, and
+ * only after waiting a bounded moment for the exit status the close implies.
+ *
+ * Returns `undefined` for every other failure — an abort, a bootstrap throw, or
+ * a child death our own `notifyChildGone` already diagnosed — so no other error
+ * pays a delay and none is double-reported.
+ *
+ * Callers MUST run this BEFORE tearing the child down: our teardown SIGTERMs the
+ * process group, so an exit read after it would be OUR signal recorded as the
+ * child's cause of death.
+ *
+ * The stderr claim is deliberately NARROW. Running before teardown means the tail
+ * already collected is not cut short by our own cleanup, and stderr arriving
+ * during this window still lands in it. It does NOT promise the child's last
+ * words: node's `exit` can precede the stdio drain, and nothing here waits for
+ * the stderr pipe to close. Draining it is a separate lever, not this one.
+ */
+async function diagnoseTransportClosure(opts: {
+	err: unknown;
+	session: BridgeSession | undefined;
+	phase: "pre-prompt" | "prompt";
+	aborted: boolean;
+}): Promise<string | undefined> {
+	if (opts.aborted || !opts.session) return undefined;
+	if (!isAcpConnectionClosure(opts.err)) return undefined;
+	const session = opts.session;
+	// This turn owns the announcement from here on, so the next turn must not
+	// repeat it. Raised BEFORE the wait and before any signal of ours, so an end
+	// observed inside the window is still a natural one.
+	session.reporting = true;
+	await settleChildEnd(session.childEnd, CHILD_END_SETTLE_MS);
+	return childEndLifecycleLine({
+		phase: opts.phase,
+		exit: session.exit,
+		ended: session.childEnd.settled,
+	});
+}
+
 // ---------------------------------------------------------------------------
 // timeout / launch / permission / stopReason / teardown helpers
 // ---------------------------------------------------------------------------
@@ -728,12 +921,16 @@ export function streamAcpTurn(
 		stream.end();
 	}
 
-	function finishError(err: unknown, aborted: boolean, stderrTail?: string[]): void {
+	function finishError(err: unknown, aborted: boolean, stderrTail?: string[], lifecycle?: string): void {
 		finalizeAcpStreamState(state);
 		state.output.stopReason = aborted ? "aborted" : "error";
 		const base = err instanceof Error ? err.message : String(err);
+		// The FIRST failure stays first and verbatim (it is what the backend
+		// actually said); the lifecycle line is added, never substituted, so a
+		// reader can still match the transport's own text.
+		const diagnosed = lifecycle ? `${base}\n${lifecycle}` : base;
 		const tail = (stderrTail ?? []).join("").trim().slice(-1_000);
-		const full = tail ? `${base}\n--- backend stderr (tail) ---\n${tail}` : base;
+		const full = tail ? `${diagnosed}\n--- backend stderr (tail) ---\n${tail}` : diagnosed;
 		// A-c: a real failure (not an abort) that looks like a context-window
 		// overflow gets an actionable hint appended, so "API Error" stops hiding
 		// the turn-scoped full-transcript-replay cause.
@@ -924,6 +1121,8 @@ export function streamAcpTurn(
 		let child: AcpChildLike | undefined;
 		let session: BridgeSession | undefined;
 		let onAbort: (() => void) | undefined;
+		/** Which phase a failure belongs to — flipped once the prompt is on the wire. */
+		let phase: "pre-prompt" | "prompt" = "pre-prompt";
 		const stderrTail: string[] = [];
 		const sessionKey = resolveSessionKey(opts, cwd);
 		try {
@@ -1012,6 +1211,9 @@ export function streamAcpTurn(
 				// this turn with the session, so a later reuse turn can still report
 				// the child's dying words.
 				stderrTail,
+				// Armed at spawn, before ANY turn can fail on this child — the latch
+				// must already exist when the `exit` listener below can fire.
+				childEnd: makeChildEndLatch(),
 			};
 			const sess = session;
 			spawned.once("exit", (...args: unknown[]) =>
@@ -1102,6 +1304,9 @@ export function streamAcpTurn(
 				signal.removeEventListener("abort", onAbort);
 				onAbort = undefined;
 			}
+			// From here the prompt is on the wire: a transport closure now is a
+			// PROMPT-phase failure, and the catch says so.
+			phase = "prompt";
 			const promptResult = await awaitAcpPromptTurn(session, wireParams, {
 				signal,
 				graceMs: deps.abortGraceMs ?? ABORT_CANCEL_GRACE_MS,
@@ -1134,6 +1339,13 @@ export function streamAcpTurn(
 				session.busy = false;
 				if (bridgeSessions.get(sessionKey) === session) bridgeSessions.delete(sessionKey);
 			}
+			// ORDER IS THE CONTRACT (#72): natural settle → seal → teardown.
+			// The bounded wait for the child's own exit status runs BEFORE we signal
+			// anything, so what we report is how the child actually ended and not our
+			// own SIGTERM; the tail collected by then is sealed before our cleanup
+			// touches the stderr pipe.
+			const lifecycle = await diagnoseTransportClosure({ err, session, phase, aborted });
+			finishError(err, aborted, session?.stderrTail ?? stderrTail, lifecycle);
 			// error/abort → drop the (uncertain) session and close its child; an
 			// uncertain connection must never be reused (GPT ④).
 			if (child) {
@@ -1142,7 +1354,6 @@ export function streamAcpTurn(
 				session?.connection.close?.(err);
 				teardownChild(child);
 			}
-			finishError(err, aborted, session?.stderrTail ?? stderrTail);
 		} finally {
 			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
 		}
@@ -1150,6 +1361,8 @@ export function streamAcpTurn(
 
 	// --- reuse: send only the latest user delta to the live ACP session
 	async function runReuseTurn(session: BridgeSession, ctxSigs: string[]): Promise<void> {
+		/** Same phase discipline as a new turn — reuse just has no bootstrap to lose. */
+		let phase: "pre-prompt" | "prompt" = "pre-prompt";
 		try {
 			if (signal?.aborted) throw new Error("aborted before prompt");
 
@@ -1171,6 +1384,7 @@ export function streamAcpTurn(
 			// ahead of the wire write; the prompt driver then owns the abort surface.
 			const wireParams = await applyProviderPayloadHook(options, { sessionId: session.acpSessionId, prompt }, model);
 			if (signal?.aborted) throw new Error("aborted during payload hook");
+			phase = "prompt";
 			const promptResult = await awaitAcpPromptTurn(session, wireParams, {
 				signal,
 				graceMs: deps.abortGraceMs ?? ABORT_CANCEL_GRACE_MS,
@@ -1188,16 +1402,22 @@ export function streamAcpTurn(
 			const aborted = Boolean(signal?.aborted);
 			session.activePromptHandler = undefined;
 			session.busy = false;
-			// error/abort on a reused session → drop it and close the child (GPT ④).
 			if (bridgeSessions.get(session.key) === session) bridgeSessions.delete(session.key);
+			// The SAME diagnostics a new turn reports, in the SAME order (#72):
+			// natural settle → seal → teardown. This is the path the field sample
+			// took — a retained child that died after its tool phase — so the
+			// ordering matters most here: teardown first would have overwritten the
+			// child's own exit status with our SIGTERM.
+			const lifecycle = await diagnoseTransportClosure({ err, session, phase, aborted });
+			// Without the session-scoped tail a mid-turn child death on a resident
+			// session surfaced as a bare "ACP connection closed" with nothing to read
+			// it by.
+			finishError(err, aborted, session.stderrTail, lifecycle);
+			// error/abort on a reused session → drop it and close the child (GPT ④).
 			session.retiring = true;
 			retainedChildren.delete(session.child);
 			session.connection.close?.(err);
 			teardownChild(session.child);
-			// The SAME diagnostics a new turn reports. Without the session-scoped
-			// tail a mid-turn child death on a resident session surfaced as a bare
-			// "ACP connection closed" with nothing to read it by.
-			finishError(err, aborted, session.stderrTail);
 		}
 	}
 

package/run.sh

@@ -120,7 +120,7 @@ usage() {
   cat <<'EOF'
 Usage:
   ./run.sh setup [project-dir]        # ONE confident install: pnpm install + install + meta-bridge (if native harness) + v2 install smoke (LIVE substrate = release-gate)
-  ./run.sh release-gate [project-dir] [--cut] [--allow-skip-gemini]  # SINGLE release gate: full static (pnpm run check:full) + the v2-native live gates (v2 matrix-live, check-bridge, RGG) + the ACP plugin acceptance floor (12 LIVE smokes: socket-citizen/raw-turn/overlay/provider/session-reuse/carrier-augment/memory-containment/rgg/mcp/skill/bundled-mcp/v2-send) + the one surviving axis the aggregate used to omit silently (claude-native-resume; Cortex stays a documented on-demand direct call) + the cross-harness delivery chain (smoke-entwurf-chain-live). TWO-TIER summary: MUST (release-blocking, owns the exit code — "green" applies here) + BEHAVIOR (advisory, non-blocking: RGG positives model-in-loop turn). STEP OUTCOME protocol: every step is INVOKED and reports its own PASS / SKIP (exit 97, a prerequisite it does not have) / FAIL — a skip is never counted as a pass. Without --cut this is the unattended diagnostic (SKIPs reported, exit 0). WITH --cut it is read as release acceptance and ANY MUST SKIP is red, which is what makes "a CUT needs LIVE=1, SKIP=0" executable instead of prose. --allow-skip-gemini accepted-but-ignored (back-compat). final cut authorization is GLG's.
+  ./run.sh release-gate [project-dir] [--cut] [--allow-skip-gemini]  # SINGLE release gate: full static (pnpm run check:full) + the v2-native live gates (v2 matrix-live, check-bridge, doctor-pi-provider, RGG) + the ACP plugin acceptance floor (12 LIVE smokes: socket-citizen/raw-turn/overlay/provider/session-reuse/carrier-augment/memory-containment/rgg/mcp/skill/bundled-mcp/v2-send) + the one surviving axis the aggregate used to omit silently (claude-native-resume; Cortex stays a documented on-demand direct call) + the cross-harness delivery chain (smoke-entwurf-chain-live). TWO-TIER summary: MUST (release-blocking, owns the exit code — "green" applies here) + BEHAVIOR (advisory, non-blocking: RGG positives model-in-loop turn). STEP OUTCOME protocol: every step is INVOKED and reports its own PASS / SKIP (exit 97, a prerequisite it does not have) / FAIL — a skip is never counted as a pass. Without --cut this is the unattended diagnostic (SKIPs reported, exit 0). WITH --cut it is read as release acceptance and ANY MUST SKIP is red, which is what makes "a CUT needs LIVE=1, SKIP=0" executable instead of prose. --allow-skip-gemini accepted-but-ignored (back-compat). final cut authorization is GLG's.
   ./run.sh check-bridge               # entwurf-bridge direct MCP smoke + protocol/negative-path test.sh (live substrate = v2 live smokes)
   ./run.sh check-entwurf-bridge-boot # deterministic gate (5d-5-pre, G1a/G1b/G1e/G1f, IN pnpm run check:full): boot start.sh under strip-types + assert v2 fence graph loads + entwurf_v2 and entwurf_resume_call registered/schema + the tools/list surface is EXACTLY the seven shipped garden verbs; tools/list only, no auth/side-effect
   ./run.sh check-entwurf-bridge-pi-free # deterministic gate (0.12.1 A, IN pnpm check): static — bridge index eager value-import closure must carry no @earendil-works/pi-* (type-only + dynamic import excluded); proves the meta-bridge boots pi-free
@@ -156,8 +156,8 @@ Usage:
   ./run.sh check-mux-launcher-fence   # deterministic gate for the shared operator-launcher fence (issue #67): scripts/lib/claude-launcher-fence.ts + its wiring into BOTH mux LIVE smokes. Replants the observed install-destruction shape (real HOME + fixture XDG_DATA_HOME → self-update retargets the real `claude` launcher into the fixture tree, teardown deletes it) wholly inside disposable mkdtemp roots — the real launcher is never inspected. Pins fail-closed preflight, retarget/content-change detection before cleanup, removal BLOCKED on fixture reference / unproven safety / surviving tracked panes, exact operator-parity XDG restore (absent = DELETED, not canonical defaults), the lifecycle cell-branch topology, and one shared helper consumed by both smokes
   ./run.sh check-entwurf-v2-visible-resume # deterministic gate: S1 visible-resume COMPOSITION (entwurf-v2-visible-resume.ts) with every seam injected — the whole state machine incl. the timeout branch runs with no tmux/lock/socket/clock. Pins lock BEFORE liveness, identity under the lock and before any window (no-transcript citizen fails loud, opens nothing), live/indeterminate/address-conflict refused unlaunched, observation as a BOUNDED WAIT (measured: socket answers ~2–4s after launch, so one immediate probe would call a successful resume unobserved), exactly ONE launch on every path, timeout → lock released + window left open + nothing retried/killed, failed release throws, and the two receipts staying separate in type and text
   ./run.sh check-resume-launch-identity # deterministic gate for resume-launch-identity.ts, the record-authoritative launch-identity leaf preserved through the visible-first cut (spawn-bg and all its callers are gone; this leaf answers "which being is this, and which conversation is theirs"). Temp meta-store fixture: gardenId→record.transcriptPath happy path with header cwd/provider/model; C3 integrity (header id ≠ record.nativeSessionId → refused, never resumed); #52 ADDRESSABLE read (a gid that no longer holds its nativeSessionId alone is refused from EITHER side — the plain targeted read would resume one transcript twice under two locks); cause fidelity per impossible resume incl. the F7 pin (recorded-but-deleted transcript → MISSING, not "no recorded model"); header↔gate SSOT. No spawn/socket/timer
-  ./run.sh smoke-entwurf-v2-matrix-live # LIVE sentinel (0.11 Stage 0 step 5d-5, D4-b) — OUT of pnpm check, needs LIVE=1. Drives REAL production runEntwurfV2 deps over REAL OS objects, 4 cells: C1 control-socket (real pi --entwurf-control resident → RPC send → lock acquire→release ×1), C1b record-less socket (#50 C4: live record-less pi → EVERY intent rejected pre-probe record-less-socket, no lock, rendered hint names record authority + fresh-cut), C2 meta-mailbox deliverable (armed self-fetch citizen → real .msg enqueue, lock-free), C3 meta-mailbox guard (no armed receiver → reject, no garbage). Model-in-loop OUT (transport/lock/enqueue gate, GPT Q2); negative/timeout stay deterministic. Model: ENTWURF_LIVE_TARGET=<provider>/<model> (default openai-codex/gpt-5.4). LIVE=1 ./run.sh smoke-entwurf-v2-matrix-live
-  ./run.sh smoke-agy-native-push-live  # 봉인 8 LIVE acceptance for the native-push (agy) rail — OUT of pnpm check, needs LIVE=1 + AGY_CONVERSATION_ID (a live agy conversation). Drives the REAL antigravity adapter + register core + runEntwurfV2 (production deps): doctor-static preflight (dangling→FAIL, the ③ gate), probe route, register create/attach idempotency, fire→native-push delivered, post-send re-probe (D7 partial), bogus-conv→native-push-probe-indeterminate. Meta-store isolated to a temp dir (only the agy round-trip is real; no real-store residue). LIVE=1 AGY_CONVERSATION_ID=<convId> ./run.sh smoke-agy-native-push-live
+  ./run.sh smoke-entwurf-v2-matrix-live # LIVE sentinel (0.11 Stage 0 step 5d-5, D4-b) — OUT of pnpm check, needs LIVE=1. Drives REAL production runEntwurfV2 deps over REAL OS objects, 4 cells: C1 control-socket (real pi --entwurf-control resident → RPC send → lock acquire→release ×1), C1b record-less socket (#50 C4: live record-less pi → EVERY intent rejected pre-probe record-less-socket, no lock, rendered hint names record authority + fresh-cut), C2 meta-mailbox deliverable (armed self-fetch citizen → real .msg enqueue, lock-free), C3 meta-mailbox guard (no armed receiver → reject, no garbage). Model-in-loop OUT (transport/lock/enqueue gate, GPT Q2); negative/timeout stay deterministic. Model: ENTWURF_LIVE_TARGET=<provider>/<model> (default openai-codex/gpt-5.6-luna). LIVE=1 ./run.sh smoke-entwurf-v2-matrix-live
+  ./run.sh smoke-agy-native-push-live  # 봉인 8 LIVE acceptance for the native-push (agy) rail — OUT of pnpm check, needs LIVE=1 + AGY_CONVERSATION_ID (a live agy conversation). Drives the REAL antigravity adapter + register core + runEntwurfV2 (production deps): doctor-static preflight (dangling→FAIL, the ③ gate), probe route, register create/attach idempotency, fire→native-push delivered, post-send re-probe (D7 partial), bogus-conv→native-push-probe-indeterminate. Meta-store isolated to a temp dir (only the agy round-trip is real; no real-store residue). COST FENCE: open that agy conversation on gemini-3.6-flash (free account) — never a Pro tier; entwurf never selects the agy model and no assertion reads it. LIVE=1 AGY_CONVERSATION_ID=<convId> ./run.sh smoke-agy-native-push-live
   ./run.sh smoke-mux-lifecycle-live  # RELEASE MUST integrated LIVE lifecycle acceptance for mux, through the REAL MCP surface — OUT of pnpm check, needs LIVE=1 and spends model turns (two pi siblings: native + recorded-ACP provider, each resumed once; one Claude Code sibling). tools/call fresh_call -> nonce callback sender envelope -> v2 control send landing in the sibling's own transcript -> resume_call REFUSED while live (window count unchanged) -> stable-handle close (pane gone, socket dead, record kept) -> dormant delivery refused honestly -> public entwurf_resume_call with LAUNCH and OBSERVATION receipts kept apart, same-gid socket alive, zero new citizens, zero lock residue, resumed pane_start_path == RECORD cwd (separate tmux query), transcript byte-identical across the resume -> v2 recall of the pre-close fact. claude-code resume refused target-not-pi, no window opened and no lock residue. LIVE=1 ./run.sh smoke-mux-lifecycle-live
   ./run.sh check-entwurf-facts         # deterministic gate (0.11 Stage 0 step 4, fact-provider slice 1+2): PURE PeerFact core + resolveFactList union — R1 out-of-domain→unsupported, R3b socket-domain 4-value, facts-only keyset; union: PeerFact + RecordLessSocketFact by gardenId (#50 C4: record-less socket = diagnostic subject, gid+liveness only), dormant→dead, F3 indeterminate preserved, out-of-socket-domain+socket fail-loud; pure, no IO
   ./run.sh check-socket-discovery      # deterministic gate (0.11 Stage 0 step 4, fact-provider slice 3): SOCKET-axis scanSocketProbes — probes (dir sockets) ∪ (in-domain citizen canonical paths) 3-valued; dormant citizen no-file → dead (resumable, not unprobed), stall → indeterminate (F3), dir hygiene/dedup/missing-dir + e2e → resolveFactList; readdir/probe injected, no IO
@@ -197,6 +197,7 @@ Usage:
   ./run.sh doctor-meta-bridge         # THE RELEASE ORACLE (#51, Linux-certified repair axis). exit 0 = every required layer was MEASURED on this Linux host: toolchain + state + plugin/MCP + resolved-artifact launch-form classification (all 3 owner hooks + doorbell static contract) + synthetic owner join + store scan + hook errors + SessionStart evidence + REQUIRED live MCP↔marker join + writer-version parity. Missing live evidence is NOT CERTIFIED (open a Claude session and re-run), never a pass; Darwin is not yet verified/certified and stays nonzero for this cut (future validation may reopen it). Detection power is held by check-meta-doctor-oracle
   ./run.sh install-agy-bridge         # 봉인 7: agy MCP install adapter — register ONE entwurf-bridge server in the agy mcp_config (adopt file / create / REFUSE symlink), stable bin command, install-state under $XDG_DATA_HOME/entwurf/agy-bridge/
   ./run.sh uninstall-agy-bridge       # 봉인 7: honest inverse of install-agy-bridge from install-state (restore preimage / remove key; refuse if config became a symlink)
+  ./run.sh probe-bridge-command <cmd> [args...]  # #81: BOOT the given bridge invocation and require the entwurf MCP tool surface back. `--invocation-json '{"command":"…","args":[],"env":{}}'` preserves a harness config exactly. It waits for a valid initialize response, then sends initialized + tools/list only (no tools/call, lock, record, or delivery). exit 0 = it serves the bridge; 1 = it does not. The pi/agy doctors use this leaf.
   ./run.sh doctor-agy-bridge          # fail-loud doctor: MCP config + exact permission rule + state + live probe label
   ./run.sh install-agy-statusline     # own the agy statusLine subtree with bare entwurf-agy-statusline; preserve unrelated settings
   ./run.sh uninstall-agy-statusline   # honest inverse from statusline install-state
@@ -1356,7 +1357,7 @@ smoke_acp_cortex_live() {
   # (ACP rail Cortex verification boundary). Drives one real
   # cortex ACP turn through the entwurf provider path (outbound entwurf_v2 +
   # dual-HOME overlay facts + process-group reclaim — CP2).
-  # HONEST-SKIP (exit 0) when LIVE!=1 OR `cortex` is not on PATH OR no
+  # HONEST-SKIP (protocol exit 97, never 0) when LIVE!=1 OR `cortex` is not on PATH OR no
   # connection is pinned — the live turn needs `cortex` installed with the
   # operator's own web-login auth already present (there is no `cortex auth`
   # subcommand — CP0 D6), reached through the overlay's narrow credential
@@ -1389,7 +1390,7 @@ smoke_entwurf_v2_matrix_live() {
   # reject, no garbage). Model-in-loop is OUT (GPT Q2): "does the sender model call entwurf_v2"
   # is a separate behavior test — this is a transport/lock/enqueue gate. Negative/timeout/contention
   # stay deterministic. Honest skip when LIVE!=1 so the release-gate is runnable unattended.
-  # Model: ENTWURF_LIVE_TARGET=<provider>/<model> (default openai-codex/gpt-5.4).
+  # Model: ENTWURF_LIVE_TARGET=<provider>/<model> (default openai-codex/gpt-5.6-luna).
   #   LIVE=1 ./run.sh smoke-entwurf-v2-matrix-live
   entwurf_require_step_outcome
   if [ "${LIVE:-}" != "1" ]; then
@@ -1628,13 +1629,13 @@ assert.equal(peerTui, piAi,
 // floor tracks the devDep pin so a consumer can't install against a pi lacking
 // the public trust exports the bridge imports at the pinned minor, AND an upper
 // bound at the next minor stops a fresh install from silently pulling a future
-// pi (past the declared ceiling — 0.85+ at the current 0.84.1 pin) whose
+// pi (past the declared ceiling — 0.85+ at the current 0.84.2 pin) whose
 // internal export surface has drifted from the one we typecheck against.
 // pi moves its public surface every minor (the 0.79→0.80 getModels→provider-
 // factory churn is exactly this), so an open `>=` floor is exactly how the next
 // installer re-acquires the drift. The floor is also the HARD MINIMUM a consumer
-// install resolves: at `>=0.84.1` an existing 0.83.x host is upgraded, not kept.
-// Expected shape: `>=<devDep> <0.<minor+1>` (e.g. `>=0.84.1 <0.85`).
+// install resolves: at `>=0.84.2` an existing 0.83.x host is upgraded, not kept.
+// Expected shape: `>=<devDep> <0.<minor+1>` (e.g. `>=0.84.2 <0.85`).
 const [piMaj, piMin] = piAi.split('.').map(Number);
 assert.equal(piMaj, 0,
   `pi pin major must stay 0 for the next-minor ceiling rule (got ${piAi}); revisit check-dep-versions when pi reaches 1.x`);
@@ -2741,6 +2742,9 @@ check_pack() {
     "mcp/entwurf-bridge/dist/scripts/doctor-pi-provider.js"
     "mcp/entwurf-bridge/dist/scripts/new-session-id.js"
     "mcp/entwurf-bridge/dist/scripts/meta-bridge-prune.js"
+    # #81 — the boot probe doctor-pi-provider imports (and `entwurf probe-bridge-command` runs).
+    # Without the twin the installed doctor dies on the import before printing a verdict.
+    "mcp/entwurf-bridge/dist/scripts/probe-bridge-command.js"
     # The generation verb. The hosts that need it are installed hosts on a
     # previous-generation store; without this twin the prescription every
     # v3-only rejection names would be dead exactly where it matters.
@@ -2940,6 +2944,8 @@ _check_pack_install_impl() {
     "mcp/entwurf-bridge/dist/scripts/doctor-pi-provider.js"
     "mcp/entwurf-bridge/dist/scripts/new-session-id.js"
     "mcp/entwurf-bridge/dist/scripts/meta-bridge-prune.js"
+    # #81 — the boot probe the installed doctor imports (see check-pack).
+    "mcp/entwurf-bridge/dist/scripts/probe-bridge-command.js"
     # The generation verb (see check-pack). The installed-command regression below
     # opens a fresh generation on a 0-record sandbox through the real bin.
     "mcp/entwurf-bridge/dist/scripts/meta-bridge-fresh-cut.js"
@@ -3021,7 +3027,7 @@ _check_pack_install_impl() {
   printf '%s\n' '{ "name": "entwurf-install-smoke", "version": "0.0.0", "private": true }' > "$tmp/package.json"
 
   # pi-agent-core is pinned even though we never import it: pi-coding-agent depends
-  # on it by CARET (`^0.84.1`), so with no lockfile in this fresh temp project it
+  # on it by CARET (`^0.84.2`), so with no lockfile in this fresh temp project it
   # floats to whatever pi published last — and that newer core then drags a NESTED
   # pi-ai of its own. Measured 2026-07-21: pinning only the three we import left
   # pi-agent-core@0.80.10 + pi-ai@0.80.10 in the tree while the gate still announced
@@ -3040,12 +3046,12 @@ _check_pack_install_impl() {
   local install_log
   install_log=$(cd "$tmp" && pnpm add \
     "$tgz_path" \
-    "@earendil-works/pi-ai@0.84.1" \
-    "@earendil-works/pi-coding-agent@0.84.1" \
-    "@earendil-works/pi-tui@0.84.1" \
-    "@earendil-works/pi-agent-core@0.84.1" \
-    "@earendil-works/pi-client@0.84.1" \
-    "@earendil-works/pi-protocol@0.84.1" \
+    "@earendil-works/pi-ai@0.84.2" \
+    "@earendil-works/pi-coding-agent@0.84.2" \
+    "@earendil-works/pi-tui@0.84.2" \
+    "@earendil-works/pi-agent-core@0.84.2" \
+    "@earendil-works/pi-client@0.84.2" \
+    "@earendil-works/pi-protocol@0.84.2" \
     "typebox@latest" \
     --ignore-workspace --ignore-scripts 2>&1) || {
     fail "[check-pack-install] pnpm add failed:"
@@ -3055,17 +3061,17 @@ _check_pack_install_impl() {
 
   # A pin is a wish until the resolved tree is read back. Assert it: EVERY
   # @earendil-works pi package present — direct or transitive, top level or nested —
-  # must be the pinned 0.84.1. Anything else means an unpinned caret floated and the
+  # must be the pinned 0.84.2. Anything else means an unpinned caret floated and the
   # rest of this gate would be exercising a runtime nobody verified, while still
-  # printing "pinned pi 0.84.1". Fail loud instead of proving the wrong floor.
+  # printing "pinned pi 0.84.2". Fail loud instead of proving the wrong floor.
   local leaked_pi
-  leaked_pi=$(ls "$tmp/node_modules/.pnpm" 2>/dev/null | grep '^@earendil-works+pi-' | grep -v '@0\.84\.1' || true)
+  leaked_pi=$(ls "$tmp/node_modules/.pnpm" 2>/dev/null | grep '^@earendil-works+pi-' | grep -v '@0\.84\.2' || true)
   if [ -n "$leaked_pi" ]; then
-    fail "[check-pack-install] UNVERIFIED pi runtime resolved into the install tree (expected only 0.84.1):"
+    fail "[check-pack-install] UNVERIFIED pi runtime resolved into the install tree (expected only 0.84.2):"
     printf '%s\n' "$leaked_pi" | sed 's/^/    /' >&2
     return 1
   fi
-  echo "[check-pack-install] pi runtime tree pin verified: every @earendil-works pi package is 0.84.1"
+  echo "[check-pack-install] pi runtime tree pin verified: every @earendil-works pi package is 0.84.2"
 
   # Resolve the installed package.json and confirm pi.extensions
   # arrived intact. If pi.extensions is empty or missing, the
@@ -4463,6 +4469,23 @@ release_gate() {
   # is gated behind SMOKE_RGG_POSITIVE=1 in the BEHAVIOR lane below.
   run_step "smoke-resident-garden-guard (3c citizen: record birth / record-keyed socket / attach-on-reopen, 0-token)" gate env SMOKE_RGG_POSITIVE=0 bash "$self" smoke-resident-garden-guard
   run_step "check-bridge"                   gate bash "$self" check-bridge
+  # check-bridge booted the launcher THIS CHECKOUT ships; this boots the invocation the operator's
+  # pi provider actually EXECS. Two different strings, and only the second one reaches a live ACP
+  # session. 2026-08-19 measured the gap at full price: `~/.local/bin/entwurf-bridge` had been
+  # relocated onto a pnpm cmd-shim (basedir derived from $0, so not relocatable), it exited 127, the
+  # bundled bridge never booted, and the model had no `mcp__entwurf-bridge__*` tool — while
+  # `command -v` answered yes throughout. #81's probe already settles that in under a second and
+  # doctor-pi-provider consumes it; it was simply never a step, so the verdict first surfaced at
+  # smoke-acp-bundled-mcp-live, sixteen LIVE steps and ~20 minutes of real model spend later.
+  # `run_step`, not `run_live_step`: this doctor is not LIVE-gated and never emits 97, so it has no
+  # prerequisite to decline. It exits 1 for a configured invocation that will not boot and for
+  # state-owned drift; a host that never installed the circuit keeps its existing exit 0 note, and
+  # the bundled smokes below still fail loud there. So this tightens nothing — it only moves an
+  # existing red earlier. cwd is REPO_DIR regardless of `gate` (run_ts cds there), so the scope
+  # judged is this checkout's `.pi/settings.json` shadowing the operator's global: deterministic,
+  # but not in principle the smokes' global-only subject if the two ever diverge.
+  # Position and classifier arm are pinned by [QK:PI-DOCTOR-IS-RELEASE-MUST].
+  run_step "doctor-pi-provider (#81: the operator's CONFIGURED bridge invocation actually boots)" gate bash "$self" doctor-pi-provider
   # D4-c: the v2 dispatch substrate sentinel (5d-5). A SINGLE run (NOT backend-looped — it proves
   # production runEntwurfV2 deps + real pi control-socket RPC + real mailbox enqueue + v2 lock, not
   # per-backend model behavior). Placed right after check-bridge: the MCP/protocol substrate must be
@@ -5103,12 +5126,34 @@ case "$cmd" in
     # Fail-loud doctor for agy hooks.json imprint wiring.
     (cd "$REPO_DIR" && bash scripts/agy-hooks-bridge.sh doctor "$@")
     ;;
+  check-probe-bridge-command)
+    # #81: contract gate for the boot probe both doctors stake their verdict on — the reason
+    # taxonomy (each value = a different operator repair) plus the one side effect the probe owns,
+    # reaping the child it spawned. Hermetic stubs only; boots no bridge of ours.
+    run_ts scripts/check-probe-bridge-command.ts
+    ;;
+  probe-bridge-command)
+    # #81: does a configured bridge command actually BOOT and serve MCP? `command -v` answering
+    # yes is not that claim — a relocated launcher can resolve and still exit 127, which is how a
+    # host ran with NO bridge in its ACP turns while every doctor printed ok. It waits for the
+    # initialize RESPONSE before it sends notifications/initialized + `tools/list` (no tools/call),
+    # so it takes no lock, writes no record, and delivers nothing. Both doctors route their boot
+    # cell here so one leaf owns the verdict — agy for every configured {command,args,env}, pi for
+    # every effective stdio invocation.
+    shift || true
+    run_ts scripts/probe-bridge-command.ts "$@"
+    ;;
   doctor-pi-provider)
-    # #46 Task 2: read-only fail-loud doctor for the pi provider ownership (entwurfProvider.
-    # mcpServers.entwurf-bridge). Uses config.ts readProviderSettingsFile SSOT for the EFFECTIVE
-    # (project-shadows-user) command — never a re-implemented merge. Reports user/project/effective,
-    # gates on stable-bin resolvability, and distinguishes state-owned drift (FAIL) from an
-    # unowned user override (honest note). No agy/pi process needed — pure settings inspection.
+    # #46 Task 2 + #81: fail-loud doctor for the pi provider ownership (entwurfProvider.
+    # mcpServers.entwurf-bridge). Uses the config.ts SSOT for the EFFECTIVE (project-shadows-user)
+    # entry — per-name merge then ONE normalize, exactly as resolveProviderConfig does; never a
+    # re-implemented merge. Reports user/project/effective and distinguishes state-owned drift
+    # (FAIL) from an unowned user override (honest note).
+    # This doctor no longer merely reads files: it BOOTS every effective stdio invocation and
+    # requires the entwurf verb set back, because `command -v` succeeding was never evidence that
+    # pi gets a bridge. Runtime evidence and ownership are separate: an unowned override is not
+    # repaired, but a dead one is still red. It writes no operator state, but it does exec the
+    # configured command on this host. No agy/pi process is needed.
     run_ts scripts/doctor-pi-provider.ts "$@"
     ;;
   wire-agy-statusline)