@junghanacs/entwurf 0.14.1 → 0.15.0

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/pi-extensions/lib/copilot-fresh-preflight.ts

@@ -0,0 +1,251 @@
+/**
+ * copilot-fresh-preflight — the pre-mutation capability check a Copilot fresh call needs
+ * (#82 RAIL 9, `docs/adding-a-harness.md` step 9 clauses 3 and 4).
+ *
+ * ── Why this is a leaf and not a doctor ──
+ *
+ * A doctor answers "is this host correctly wired?" and is allowed to be slow, to spawn the
+ * vendor CLI, and to read live processes. This is not that. It answers ONE narrower question
+ * at ONE moment: *before* `mux-fresh-call` mutates the operator's tmux session, are the four
+ * things the fresh contract requires actually in place on this filesystem?
+ *
+ *   birth            — without the birth plugin the session mints no record, so the callback
+ *                      would carry no garden id and the sibling never becomes addressable.
+ *   MCP hand         — without the bridge server the callback tool does not exist in that
+ *                      session, and the first turn has nothing to call.
+ *   receive          — without the receiver unit the sibling can be launched and can call
+ *                      home, and then nothing can ever be delivered TO it.
+ *   visible identity — without the custom footer the citizen has a garden id nobody can see,
+ *                      which step 4 refuses to call lifecycle parity.
+ *
+ * ── Ordering is the whole point ──
+ *
+ * `scripts/copilot-launch.sh` already fails closed on the receiver, and that check is kept as
+ * it is: it guards every manual `entwurf copilot`, whose accepted contract stays receive-only.
+ * But a launcher runs INSIDE the window tmux just made, so its refusal leaves a dead window
+ * behind and the caller reads a launch receipt for a sibling that never was. `mux-fresh-call`'s
+ * rule is that nothing above the single mutation may leave a window behind, so the fresh lane
+ * decides the same facts one layer earlier. The overlap on the receiver axis is deliberate and
+ * each side names the other; the other three axes are the FRESH lane's requirement only.
+ *
+ * ── What this deliberately does NOT claim ──
+ *
+ * Ownership/configuration truth only: entwurf's units are installed and the settings the
+ * vendor will read say what they must say. It does NOT prove the Copilot CLI loaded the
+ * plugin, connected the MCP server, scanned the extension, or rendered a garden id in its
+ * footer — that is runtime truth, and it belongs to `doctor-copilot-*` (which may spawn the
+ * vendor) and to the step 9 clause 7 LIVE receipt. A green preflight is a statement about this
+ * filesystem, not a prediction about the next process.
+ *
+ * Every predicate below MIRRORS the shipped adapter that owns that file, deliberately
+ * including its environment seams — a preflight that resolved a path its own installer never
+ * writes would refuse a correctly installed host and send the operator hunting.
+ *
+ * No vendor spawn, no network, no await, no mutation.
+ */
+
+import { accessSync, constants, existsSync, lstatSync, readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+
+/** One reason per capability. These strings are stable contract — they cross the public
+ * surfaces as `entwurf_fresh_call` refusals, so a caller can act on them. */
+export type CopilotPreflightRejectReason =
+	| "copilot-birth-unit-missing"
+	| "copilot-mcp-hand-missing"
+	| "copilot-receive-unit-missing"
+	| "copilot-visible-identity-missing";
+
+const BIRTH_PLUGIN = "entwurf-meta-receive-copilot";
+const RECEIVE_UNIT = "entwurf-receive";
+const MCP_SERVER_KEY = "entwurf-bridge";
+/** Same default and same env seam as `scripts/copilot-statusline-bridge.sh`. */
+const DEFAULT_STATUSLINE_COMMAND = "entwurf-copilot-statusline";
+
+function dataHome(env: NodeJS.ProcessEnv): string | null {
+	const xdg = env.XDG_DATA_HOME;
+	if (typeof xdg === "string" && xdg.length > 0) return xdg;
+	const home = env.HOME;
+	if (typeof home === "string" && home.length > 0) return path.join(home, ".local", "share");
+	return null;
+}
+
+/** A JSON object or nothing. Failure to read, parse, or find an object is the SAME answer
+ * here — absent — because the caller's next move is identical in all of them: run the
+ * installer. Telling a corrupt state file apart from a missing one is the doctor's job. */
+function readJsonObject(file: string): Record<string, unknown> | null {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+		return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+			? (parsed as Record<string, unknown>)
+			: null;
+	} catch {
+		// Bounded environment probing, Hard Rule 15's stated exception.
+		return null;
+	}
+}
+
+function isDir(p: string): boolean {
+	try {
+		return statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function isSymlink(p: string): boolean {
+	try {
+		return lstatSync(p).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+
+/** Same DEST the managed launcher will arm from (`scripts/copilot-launch.sh`).
+ * `COPILOT_EXTENSIONS_DIR` wins; otherwise `$HOME/.copilot/extensions/<unit>`.
+ * String equality, not realpath: the launcher compares with `[ = ]`. */
+function receiveDest(env: NodeJS.ProcessEnv): string | null {
+	const override = env.COPILOT_EXTENSIONS_DIR;
+	if (typeof override === "string" && override.length > 0) {
+		return path.join(override, RECEIVE_UNIT);
+	}
+	const home = env.HOME;
+	if (typeof home !== "string" || home.length === 0) return null;
+	return path.join(home, ".copilot", "extensions", RECEIVE_UNIT);
+}
+
+function isExecutableFile(p: string): boolean {
+	try {
+		// `X_OK` for THIS user, which is what `command -v` answers and what Copilot will need.
+		// A mode-bit test would call a root-owned 0700 binary executable for everyone.
+		accessSync(p, constants.X_OK);
+		return statSync(p).isFile();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The statusline command as the shipped adapter resolves it: a value containing a separator is
+ * a path and must be executable; a bare name is looked up on PATH. This is a small local
+ * search rather than `mux-launch`'s resolver because the import fence keeps `mux-launch` to
+ * exactly two importers — a third would be a decision, and this leaf does not need one.
+ */
+function commandResolvable(command: string, env: NodeJS.ProcessEnv): boolean {
+	if (command.includes("/")) return isExecutableFile(command);
+	const raw = env.PATH;
+	if (typeof raw !== "string" || raw.length === 0) return false;
+	for (const dir of raw.split(path.delimiter)) {
+		if (dir.length === 0) continue;
+		if (isExecutableFile(path.join(dir, command))) return true;
+	}
+	return false;
+}
+
+/**
+ * The visible-identity axis, step 9 clause 4. The subject is the EFFECTIVE settings the vendor
+ * will read, not entwurf's ownership record: a host can carry a correct footer configuration
+ * with no install-state (measured on the acceptance host, 2026-08-24 — `doctor-copilot-statusline`
+ * reported `settings: configured (resolvable)` / `state: absent` / rc=0), and refusing that host
+ * would be refusing a working visible identity because of a missing receipt.
+ *
+ * The install-state, when present, is checked for the ONE thing it can still contradict: that
+ * it manages the very file Copilot reads. A state pointing somewhere else means two settings
+ * files disagree about who owns the footer, and which one wins is not decidable from here.
+ */
+function visibleIdentityMissing(env: NodeJS.ProcessEnv, data: string): boolean {
+	const command = env.COPILOT_STATUSLINE_COMMAND || DEFAULT_STATUSLINE_COMMAND;
+	const configured = env.COPILOT_SETTINGS_CONFIG;
+	let settingsPath: string;
+	if (typeof configured === "string" && configured.length > 0) {
+		settingsPath = configured;
+	} else {
+		const home = env.HOME;
+		if (typeof home !== "string" || home.length === 0) return true;
+		settingsPath = path.join(home, ".copilot", "settings.json");
+	}
+	// A symlinked settings file is somebody else's SSOT; the adapter refuses to touch it and
+	// this refuses to certify it.
+	if (isSymlink(settingsPath)) return true;
+	const settings = readJsonObject(settingsPath);
+	if (settings === null) return true;
+	const statusLine = settings.statusLine;
+	if (typeof statusLine !== "object" || statusLine === null || Array.isArray(statusLine)) return true;
+	if ((statusLine as Record<string, unknown>).command !== command) return true;
+	const footer = settings.footer;
+	if (typeof footer !== "object" || footer === null || Array.isArray(footer)) return true;
+	// `showCustom` must be exactly true. A truthy string would render nothing.
+	if ((footer as Record<string, unknown>).showCustom !== true) return true;
+	if (!commandResolvable(command, env)) return true;
+
+	const state = readJsonObject(path.join(data, "entwurf", "copilot-statusline", "install-state.json"));
+	if (state === null) return false; // absent state is not drift — see the doc comment above
+	const managed = state.managedSettingsPath;
+	if (typeof managed !== "string" || !path.isAbsolute(managed)) return true;
+	return path.resolve(managed) !== path.resolve(settingsPath);
+}
+
+/**
+ * Answer for ONE fresh Copilot launch. `null` means every required capability is in place on
+ * this filesystem; anything else is the first missing one, in the order the fresh contract
+ * consumes them: be born, hold the hand, be reachable, be visible.
+ */
+export function copilotFreshPreflight(env: NodeJS.ProcessEnv = process.env): CopilotPreflightRejectReason | null {
+	const data = dataHome(env);
+	// With no HOME and no XDG_DATA_HOME there is no place any of these could be installed.
+	// Report the FIRST capability rather than inventing a fifth reason for "no home".
+	if (data === null) return "copilot-birth-unit-missing";
+
+	// 1. Birth. The assembly is what the installer bakes and what the birth doctor certifies
+	// statically; `hooks.json` is what makes it a hook unit rather than a directory. There is
+	// no install-state for this unit — the artifact IS its ownership record.
+	const birthUnit = path.join(data, "entwurf", "meta-bridge-copilot", ".assembled", BIRTH_PLUGIN);
+	if (!isDir(birthUnit) || !existsSync(path.join(birthUnit, "hooks", "hooks.json"))) {
+		return "copilot-birth-unit-missing";
+	}
+
+	// 2. MCP hand. The install-state names the config it owns, so the config path is READ from
+	// ownership truth rather than re-derived — a preflight that guessed would refuse a
+	// correctly installed host whose config lives somewhere else.
+	const mcpState = readJsonObject(path.join(data, "entwurf", "copilot-mcp", "install-state.json"));
+	if (mcpState === null || mcpState.serverKey !== MCP_SERVER_KEY) return "copilot-mcp-hand-missing";
+	const managedConfigPath = mcpState.managedConfigPath;
+	if (typeof managedConfigPath !== "string" || !path.isAbsolute(managedConfigPath)) return "copilot-mcp-hand-missing";
+	const servers = readJsonObject(managedConfigPath)?.mcpServers;
+	if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return "copilot-mcp-hand-missing";
+	// The state can be current while the config drifted (hand-edited, restored from a backup,
+	// replaced by another tool). The server key present in the file the CLI actually reads is
+	// the fact the first turn depends on.
+	if (!Object.hasOwn(servers as Record<string, unknown>, MCP_SERVER_KEY)) return "copilot-mcp-hand-missing";
+
+	// 3. Receive. The same facts `scripts/copilot-launch.sh` checks — unit name, recorded
+	// path, DEST equality against this env's extensions root, then the entry file.
+	const recvState = readJsonObject(path.join(data, "entwurf", "copilot-receive", "install-state.json"));
+	if (recvState === null || recvState.unit !== RECEIVE_UNIT) return "copilot-receive-unit-missing";
+	const recvPath = recvState.path;
+	if (typeof recvPath !== "string" || !path.isAbsolute(recvPath)) return "copilot-receive-unit-missing";
+	// Mirror the launcher's path-mismatch predicate PRE-MUTATION. A state that names a
+	// real unit in a different extensions root than this env will scan still opens a
+	// window today if we only check that the files exist — then `entwurf copilot`
+	// refuses inside it and the caller holds a launch receipt for a dead sibling.
+	const dest = receiveDest(env);
+	if (dest === null || recvPath !== dest) return "copilot-receive-unit-missing";
+	if (!isDir(recvPath) || !existsSync(path.join(recvPath, "extension.mjs"))) return "copilot-receive-unit-missing";
+
+	// 4. Visible identity.
+	if (visibleIdentityMissing(env, data)) return "copilot-visible-identity-missing";
+
+	return null;
+}
+
+/** Repair text, one line per reason. A reason a caller cannot act on is a reason they will
+ * guess about — each names the exact command that installs the missing capability. */
+export const COPILOT_PREFLIGHT_HINT: Record<CopilotPreflightRejectReason, string> = {
+	"copilot-birth-unit-missing":
+		"the Copilot BIRTH plugin is not installed here, so the sibling would mint no record and its callback would carry no garden id — run: entwurf install-copilot-bridge",
+	"copilot-mcp-hand-missing":
+		"the entwurf-bridge MCP server is not registered in the Copilot config this host owns, so the callback tool would not exist in that session — run: entwurf install-copilot-mcp",
+	"copilot-receive-unit-missing":
+		"the Copilot RECEIVER extension is not installed here, so the sibling could call home but nothing could ever be delivered to it — run: entwurf install-copilot-receive",
+	"copilot-visible-identity-missing":
+		"Copilot's custom footer is not configured to entwurf's resolvable statusline command (or an install-state manages a different settings file), so the sibling's garden id would be visible nowhere — run: entwurf doctor-copilot-statusline, then entwurf install-copilot-statusline",
+};

package/pi-extensions/lib/meta-sender-identity.ts

@@ -48,8 +48,16 @@ import {
 } from "./meta-session.ts";
 import { type NativePushAdapter, resolveNativePushAdapter } from "./native-push/adapter.ts";
 
-/** Every native backend that mints a garden-id from its own hook and writes a sender marker. */
-export const META_SENDER_BACKENDS: readonly MetaBackend[] = ["claude-code", "antigravity"];
+/** Every native backend that mints a garden-id from its own hook and writes a sender marker.
+ *
+ * WRITER AND READER OPEN TOGETHER OR NOT AT ALL. A backend listed here whose hook writes no
+ * marker costs one wasted directory read; a backend whose hook writes a marker but is absent
+ * here is INVISIBLE — the bridge holds the owner pid, never looks in that directory, and the
+ * citizen's sends are refused as anonymous for a reason nothing in the log names. That was
+ * exactly the #46 defect on agy, and copilot joined the list only once its own hook wrote one
+ * (#82 RAIL 5b). Membership says a marker may EXIST, never that a reply can land: the reply
+ * rail is chosen from `nativePushSupported` at the bridge, not from this list. */
+export const META_SENDER_BACKENDS: readonly MetaBackend[] = ["claude-code", "antigravity", "copilot"];
 
 /** A marker that passed BOTH guards, together with the record that vouches for it. */
 export interface TrustedMetaSender {