@junghanacs/entwurf 0.13.0 → 0.13.1

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

@@ -1,9 +1,10 @@
 // ACP backend adapter rail — the PRODUCT seam by which a curated model id selects
-// which ACP backend (claude / future backend / …) drives a turn. See docs/acp-backend-rail.md §9.
+// which ACP backend (claude / future backend / …) drives a turn. See the adapter contract in
+// docs/acp-backend-rail.md.
 //
 // This seam is DISTINCT from `AcpTurnDeps` (backend.ts), which is the test/runtime
-// seam (fake spawn/connection/clock for the gates). The two are kept apart on
-// purpose (GPT-agreed §9-2): merging them would make a fake-deps fixture look like
+// seam (fake spawn/connection/clock for the gates). Merging them would make a
+// fake-deps fixture look like
 // a fake backend and force the adapter to carry clock/sessionDir/createConnection.
 // The wiring is `defaultDeps(adapter)` — the turn loop in backend.ts stays
 // backend-invariant; only these per-backend functions change with `adapter`.
@@ -217,7 +218,7 @@ function resolveClaudeLaunch(): AcpLaunchSpec {
 export const claudeAdapter: AcpBackendAdapter = {
 	backend: "claude",
 
-	// Claude owns its UNPREFIXED curated ids only (GPT-agreed §9-1). The native id
+	// Claude owns its UNPREFIXED curated ids only (rail “Adapter contract”). The native id
 	// equals the curated id — claude carries no curation prefix to strip.
 	routeModel(modelId) {
 		return SUPPORTED_CLAUDE_IDS.has(modelId) ? { nativeModelId: modelId } : undefined;
@@ -298,13 +299,13 @@ export const claudeAdapter: AcpBackendAdapter = {
  *  adapters claim one id. */
 // ---------------------------------------------------------------------------
 // cortex adapter — Snowflake Cortex Code, the first non-claude backend on the
-// rail (docs/acp-backend-rail.md §4/§6). It adds ZERO to the common layer:
+// rail (docs/acp-backend-rail.md, “Shipped adapters”). It adds ZERO to the common layer:
 // everything cortex-specific lives here + models.ts + overlay.ts + the gates.
 // ---------------------------------------------------------------------------
 
 const SUPPORTED_CORTEX_IDS: ReadonlySet<string> = new Set(SUPPORTED_CORTEX_MODEL_IDS);
 
-/** Cortex's OWN settings (§10 B): a Snowflake connection name, or null. Opaque to
+/** Cortex's OWN settings: a Snowflake connection name, or null. Opaque to
  *  config.ts / backend.ts — only cortexAdapter reads it (casting back). */
 export interface CortexAdapterSettings {
 	cortexConnection: string | null;
@@ -318,7 +319,7 @@ export const CORTEX_CONNECTION_ENV = "ENTWURF_ACP_CORTEX_CONNECTION";
 export const cortexAdapter: AcpBackendAdapter = {
 	backend: "cortex",
 
-	// Cortex owns the reserved `cortex-` prefix (§9-1). routeModel strips it to the
+	// Cortex owns the reserved `cortex-` prefix (rail “Adapter contract”). routeModel strips it to the
 	// native id: `cortex-auto` → "auto", `cortex-claude-sonnet-5` → "claude-sonnet-5".
 	routeModel(modelId) {
 		if (!SUPPORTED_CORTEX_IDS.has(modelId)) return undefined;
@@ -406,7 +407,7 @@ export const cortexAdapter: AcpBackendAdapter = {
 		return { envOverrides: { HOME: overlay.home, SNOWFLAKE_HOME: overlay.snowflakeHome } };
 	},
 
-	// System-prompt-carrier-less (§9-4/§11-8): Cortex ACP exposes no
+	// System-prompt-carrier-less (ACP rail “Cortex Code audit”): Cortex ACP exposes no
 	// `_meta.systemPrompt` and has no developer_instructions / GEMINI_SYSTEM_MD
 	// equivalent. (It does READ `_meta` — a caller-session-id seam, measured but
 	// unexplored and deliberately not part of this contract.) loadCarrier returns
@@ -438,7 +439,7 @@ export const cortexAdapter: AcpBackendAdapter = {
 		await setConfig.call(connection, { sessionId: acpSessionId, configId: "model", value: nativeModelId });
 	},
 
-	// A connection change must invalidate a reused session (§4/§7). Flat,
+	// A connection change must invalidate a reused session (rail: Adapter contract). Flat,
 	// sorted-stable primitive map; reads ONLY the opaque adapterSettings. `backend`
 	// + `nativeModelId` are added by backend.ts.
 	configSignatureFields(adapterSettings) {
@@ -452,7 +453,7 @@ const ADAPTERS: readonly AcpBackendAdapter[] = [claudeAdapter, cortexAdapter];
 /**
  * Resolve the backend adapter that owns `modelId`.
  *
- * GPT-agreed §9-1 fail-fast contract:
+ * Routing fail-fast contract (rail “Adapter contract”):
  *  - 0 matches  → throw (unknown model — no silent default).
  *  - 2+ matches → throw (prefix collision — a startup-visible registry bug).
  *
@@ -476,7 +477,7 @@ export function resolveAcpBackendAdapter(modelId: string): { adapter: AcpBackend
 }
 
 /** Every curated model row across all registered adapters — for provider registration.
- *  GPT-agreed §9-6 registration-time fail-fast: every curated id must route to EXACTLY
+ *  Registration-time fail-fast (rail “Adapter contract”): every curated id must route to EXACTLY
  *  one adapter and no id may be duplicated across adapters. Catching it here means a
  *  prefix-collision / duplicate surfaces at provider registration, not mid-turn. */
 export function allCuratedModels(): AcpModelRow[] {

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

@@ -55,7 +55,7 @@ import {
 	type ResolvedAcpConfig,
 	resolveProviderConfig,
 } from "./config.js";
-import { buildAcpPrompt } from "./context.js";
+import { type AcpTextBlock, buildAcpPrompt } from "./context.js";
 import {
 	type AcpPiStreamState,
 	applyAcpSessionUpdate,
@@ -78,10 +78,31 @@ import {
 } from "./session-store.js";
 import { assertExcludeToolsHonored, PI_BUILTIN_BACKED_TOOLS } from "./tool-surface.js";
 
+// Bootstrap boundaries ONLY. initialize / newSession / set-model are handshake
+// steps that make no model progress, so a stuck one is a dead session and a cold
+// retry costs nothing — a wall-clock bound is honest there.
+//
+// There is deliberately NO prompt boundary. A running turn is not a failure for
+// having taken long: tool use, reasoning, and provider queueing all legitimately
+// outlive any number we could pick, and the previous 600s absolute cutoff killed
+// turns that were still actively producing tool calls. Worse, the cutoff's own
+// message ("prompt timed out after 600000ms") lands inside pi's transient-error
+// dictionary (`RETRYABLE_PROVIDER_ERROR_PATTERN` in @earendil-works/pi-ai
+// `utils/retry.ts` matches `timed? out` / `timeout`), so pi replayed the SAME
+// full prompt from a cold ACP session up to `retry.maxRetries` times — paying the
+// whole turn again to arrive at the same wall. Elapsed time is not evidence.
+// A prompt now ends only on lifecycle events: it resolves, the operator aborts,
+// or the child dies / its stdio ends (see awaitAcpPromptTurn).
 const INITIALIZE_TIMEOUT_MS = 30_000;
 const NEW_SESSION_TIMEOUT_MS = 30_000;
 const SET_MODEL_TIMEOUT_MS = 30_000;
-const PROMPT_TIMEOUT_MS = 600_000;
+
+// Bounded CLEANUP window after a user abort — not a turn deadline. On abort we
+// send the ACP `session/cancel` notification and give the agent this long to
+// answer the pending prompt with `cancelled` (the protocol's own ending, which
+// maps to aborted). Only if it does not do so within the window do we escalate
+// to process-group teardown, so an abort always returns promptly.
+const ABORT_CANCEL_GRACE_MS = 5_000;
 
 type StdioChild = ChildProcessByStdio<Writable, Readable, Readable>;
 
@@ -121,6 +142,12 @@ export interface AcpTurnDeps {
 	now(): string;
 	/** Record dir override (tests). Defaults to the real session cache dir. */
 	sessionDir?: string;
+	/**
+	 * Post-abort cleanup grace (gates). Defaults to ABORT_CANCEL_GRACE_MS. This is
+	 * the ONLY injectable clock left on the turn path and it bounds cleanup after
+	 * an abort — never a running prompt.
+	 */
+	abortGraceMs?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -147,6 +174,24 @@ interface BridgeSession {
 	busy: boolean;
 	/** Mutable per-turn router — see the CRITICAL note in the file header. */
 	activePromptHandler?: (event: AcpBridgeEvent) => void;
+	/**
+	 * The child's own dying words, SESSION-scoped on purpose. The stderr drain is
+	 * installed once at spawn; keeping the buffer on the turn that spawned would
+	 * leave every later reuse turn reporting a bare "ACP connection closed" with
+	 * nothing to diagnose it by (observed 2026-07-30 on a live sonnet reuse turn).
+	 */
+	stderrTail: string[];
+	/** How the child ended, once it has — folded into the prompt-phase error. */
+	exit?: { code: number | null; signal: NodeJS.Signals | null };
+	/** Set while a prompt is in flight so a child death can close it (awaitAcpPromptTurn). */
+	notifyChildGone?: (err: Error) => void;
+	/**
+	 * We are tearing this child down ON PURPOSE (turn-scoped teardown, config
+	 * drift, error/abort cleanup). Its exit is then expected, not news: without
+	 * this flag every ordinary turn-scoped turn would announce its own routine
+	 * teardown to the NEXT turn as if the session had died.
+	 */
+	retiring?: boolean;
 }
 
 const bridgeSessions = new Map<string, BridgeSession>();
@@ -173,21 +218,78 @@ function registerGlobalCleanup(): void {
 	});
 }
 
-/** A retained child died between turns: mark dead + drop from map + retained set. */
-function onChildGone(session: BridgeSession): void {
+/**
+ * The child died: mark dead + drop from map + retained set, RECORD how it ended,
+ * and close any prompt that was waiting on it. Without that last step a
+ * mid-prompt death is only observable through the SDK's generic "ACP connection
+ * closed" rejection, which names neither the exit status nor the stderr.
+ */
+function onChildGone(session: BridgeSession, exit?: { code: number | null; signal: NodeJS.Signals | null }): void {
 	session.alive = false;
+	if (exit) session.exit = exit;
 	if (bridgeSessions.get(session.key) === session) bridgeSessions.delete(session.key);
 	retainedChildren.delete(session.child);
+	if (session.notifyChildGone) {
+		// A turn was waiting on this child — it reports the death itself.
+		session.notifyChildGone(childEndedError(session));
+	} else if (!session.retiring) {
+		// 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
+		// session the operator was talking to is gone. A DELIBERATE teardown is
+		// excluded — announcing our own routine cleanup would be noise, not news.
+		unreportedChildEnds.set(session.key, session.exit ?? { code: null, signal: null });
+	}
+}
+
+/** Deaths no turn observed, keyed by sessionKey and announced once by the next turn. */
+const unreportedChildEnds = new Map<string, { code: number | null; signal: NodeJS.Signals | null }>();
+
+/** Read-and-clear: an unreported death is announced exactly once. */
+function takeUnreportedChildEnd(
+	sessionKey: string,
+): { code: number | null; signal: NodeJS.Signals | null } | undefined {
+	const end = unreportedChildEnds.get(sessionKey);
+	if (end) unreportedChildEnds.delete(sessionKey);
+	return end;
+}
+
+/** "exit code 1" / "signal SIGKILL" / "exit code 0, signal SIGTERM" / "no exit status". */
+function describeChildEnd(exit?: { code: number | null; signal: NodeJS.Signals | null }): string {
+	if (!exit) return "no exit status";
+	const parts = [
+		exit.code !== null ? `exit code ${exit.code}` : undefined,
+		exit.signal ? `signal ${exit.signal}` : undefined,
+	].filter(Boolean);
+	return parts.length > 0 ? parts.join(", ") : "no exit status";
+}
+
+/**
+ * The prompt-phase error for a child that died under a live turn.
+ *
+ * Wording is load-bearing: pi classifies a failed assistant message by matching
+ * its errorMessage against `RETRYABLE_PROVIDER_ERROR_PATTERN`, so anything we
+ * author here that reads like "timed out" / "timeout" / "terminated" /
+ * "connection lost" would put a full cold prompt replay back on the table. This
+ * text names the lifecycle fact and nothing that looks transient.
+ * (The appended backend stderr tail is the child's text, not ours.)
+ */
+function childEndedError(session: BridgeSession): Error {
+	return new Error(
+		`entwurf: the ACP backend process ended while the prompt was still in flight (${describeChildEnd(session.exit)}) — ` +
+			"this turn has no answer",
+	);
 }
 
 // ---------------------------------------------------------------------------
 // timeout / launch / permission / stopReason / teardown helpers
 // ---------------------------------------------------------------------------
 
-// Race a promise against a timeout, ALWAYS clearing the timer afterwards. A
-// naive `Promise.race([p, sleep(ms)])` leaves the timer pending when `p` wins —
-// a dangling (here 10-minute) timer that keeps pi's event loop alive long after
+// Race a BOOTSTRAP phase against its timeout, ALWAYS clearing the timer
+// afterwards. A naive `Promise.race([p, sleep(ms)])` leaves the timer pending
+// when `p` wins — a dangling timer that keeps pi's event loop alive long after
 // the turn, so pi would never exit a `-p` run. clearTimeout in finally fixes it.
+// Only initialize / newSession / set-model use this; the prompt has no deadline.
 function withTimeout<T>(label: string, p: Promise<T>, ms: number): Promise<T> {
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	const timeout = new Promise<never>((_, reject) => {
@@ -199,6 +301,80 @@ function withTimeout<T>(label: string, p: Promise<T>, ms: number): Promise<T> {
 	});
 }
 
+/**
+ * Await ONE ACP prompt with NO wall-clock deadline — the turn ends on lifecycle
+ * events only. Shared by the new and the reuse turn so both close the same way.
+ *
+ * The three endings:
+ *
+ *   resolve      the agent answered `session/prompt` (any stopReason — the
+ *                verdict mapping is the caller's job).
+ *   child gone   the child exited or its stdio ended. Both are already fatal to
+ *                the request — the SDK rejects every pending response when the
+ *                read loop hits EOF — but the SDK's own error says only "ACP
+ *                connection closed". `notifyChildGone` gets there first with the
+ *                exit status, and the caller appends the session stderr tail.
+ *   abort        the operator cancelled. We send ACP `session/cancel` and let
+ *                the agent end its own turn (`cancelled` → aborted). Escalation
+ *                to process-group teardown happens only after a bounded grace,
+ *                and closing the connection rejects the pending request, so an
+ *                abort is always answered even against a wedged child.
+ *
+ * A stalled-but-alive child is deliberately NOT an ending: a silent turn is not
+ * a failed turn, and nothing here may kill one for being quiet.
+ */
+async function awaitAcpPromptTurn(
+	session: BridgeSession,
+	promptArgs: { sessionId: string; prompt: AcpTextBlock[] },
+	opts: { signal?: AbortSignal; graceMs: number },
+): Promise<{ stopReason?: string }> {
+	let rejectLifecycle: ((err: Error) => void) | undefined;
+	const lifecycle = new Promise<never>((_, reject) => {
+		rejectLifecycle = reject;
+	});
+	// The race's loser stays pending forever when the prompt wins; a rejection
+	// nobody observed would surface as an unhandled rejection at that point.
+	lifecycle.catch(() => {});
+
+	let graceTimer: ReturnType<typeof setTimeout> | undefined;
+	const escalateAbort = (): void => {
+		killChildGroup(session.child, "SIGTERM");
+		// Closing rejects the still-pending ACP request, so the await below settles
+		// even when the child ignores both the cancel notification and the signal.
+		session.connection.close?.(new Error("entwurf: ACP prompt cancelled by the operator"));
+		rejectLifecycle?.(new Error("entwurf: the ACP prompt was cancelled by the operator"));
+	};
+	const onAbort = (): void => {
+		try {
+			session.connection.cancel?.({ sessionId: promptArgs.sessionId });
+		} catch {
+			// best-effort: escalation below is what guarantees the abort returns.
+		}
+		// NOT unref'd, deliberately. This timer is the only thing that finishes an
+		// abort against an agent that ignores session/cancel, so letting the event
+		// loop drain past it would leave the turn unsettled and the child alive.
+		// It is bounded (graceMs) and cleared in the finally below, so the worst it
+		// can do is hold an exiting process for that grace — which is the cleanup
+		// we asked for.
+		graceTimer = setTimeout(escalateAbort, opts.graceMs);
+	};
+
+	session.notifyChildGone = (err) => rejectLifecycle?.(err);
+	const signal = opts.signal;
+	if (signal) {
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+	}
+
+	try {
+		return await Promise.race([session.connection.prompt(promptArgs), lifecycle]);
+	} finally {
+		if (graceTimer) clearTimeout(graceTimer);
+		signal?.removeEventListener("abort", onAbort);
+		session.notifyChildGone = undefined;
+	}
+}
+
 /** Approve-all permission policy (YOLO — oracle F). options empty → cancelled. */
 function resolvePermissionResponse(params: { options?: Array<{ optionId: string; kind?: string }> }): {
 	outcome: { outcome: "selected"; optionId: string } | { outcome: "cancelled" };
@@ -209,15 +385,61 @@ function resolvePermissionResponse(params: { options?: Array<{ optionId: string;
 	return { outcome: { outcome: "selected", optionId: (allow ?? options[0]).optionId } };
 }
 
-/** ACP prompt stopReason → pi stopReason. */
-function mapPromptStopReason(stopReason: string | undefined): AssistantMessage["stopReason"] {
+/** Verdict for one ACP prompt result — what pi should report, and why. */
+export type AcpStopVerdict = {
+	stopReason: AssistantMessage["stopReason"];
+	/** The raw ACP reason, preserved whenever the wire carried one. */
+	rawStopReason?: string;
+	/** Set exactly when `stopReason` is "error" — carries the reason into the UI. */
+	errorMessage?: string;
+};
+
+/**
+ * ACP prompt stopReason → pi verdict.
+ *
+ * The ACP terminal set is closed (`@agentclientprotocol/sdk` 1.3.0
+ * `schema/types.gen`): end_turn | max_tokens | max_turn_requests | refusal |
+ * cancelled. Only three of those are successful or benign ends. The previous
+ * implementation returned a bare StopReason with `default: "stop"`, which turned
+ * `refusal`, `max_turn_requests`, any future member, AND a missing reason into a
+ * clean successful turn — pi then rendered a silently truncated answer as if the
+ * model had finished. pi 0.83 closed the same hole in its own providers (#7272:
+ * unmapped terminal reasons surface as provider errors, never successful stops)
+ * and added `rawStopReason` so the wire value survives the mapping. This mirrors
+ * that contract rather than inventing a local one.
+ */
+export function mapPromptStopReason(stopReason: string | undefined): AcpStopVerdict {
 	switch (stopReason) {
+		case "end_turn":
+			return { stopReason: "stop", rawStopReason: stopReason };
 		case "max_tokens":
-			return "length";
+			return { stopReason: "length", rawStopReason: stopReason };
 		case "cancelled":
-			return "aborted";
+			return { stopReason: "aborted", rawStopReason: stopReason };
+		case "refusal":
+			return {
+				stopReason: "error",
+				rawStopReason: stopReason,
+				errorMessage: "ACP backend stopped with: refusal (the model declined to answer; the turn is incomplete)",
+			};
+		case "max_turn_requests":
+			return {
+				stopReason: "error",
+				rawStopReason: stopReason,
+				errorMessage:
+					"ACP backend stopped with: max_turn_requests (the backend's per-turn request budget was exhausted; the turn is incomplete)",
+			};
+		case undefined:
+			return {
+				stopReason: "error",
+				errorMessage: "ACP backend ended the turn without a stop reason",
+			};
 		default:
-			return "stop";
+			return {
+				stopReason: "error",
+				rawStopReason: stopReason,
+				errorMessage: `ACP backend stopped with an unrecognized reason: ${stopReason}`,
+			};
 	}
 }
 
@@ -426,15 +648,30 @@ export function streamAcpTurn(
 		};
 	}
 
+	/**
+	 * Seal the turn from the ACP prompt result. "Success" here means the RPC
+	 * returned, not that the turn ended well — a returned `refusal` /
+	 * `max_turn_requests` / unknown / absent reason is sealed as an error event,
+	 * never a `done`. `rawStopReason` carries the wire value out either way.
+	 */
 	function finishSuccess(promptResult: { stopReason?: string }): void {
 		finalizeAcpStreamState(state);
-		const mapped = mapPromptStopReason(promptResult?.stopReason);
-		if (signal?.aborted || mapped === "aborted") {
+		const verdict = mapPromptStopReason(promptResult?.stopReason);
+		if (verdict.rawStopReason !== undefined) state.output.rawStopReason = verdict.rawStopReason;
+		if (signal?.aborted || verdict.stopReason === "aborted") {
 			state.output.stopReason = "aborted";
 			stream.push({ type: "error", reason: "aborted", error: state.output });
+		} else if (verdict.stopReason === "error") {
+			state.output.stopReason = "error";
+			state.output.errorMessage = verdict.errorMessage;
+			stream.push({ type: "error", reason: "error", error: state.output });
 		} else {
-			state.output.stopReason = mapped;
-			stream.push({ type: "done", reason: mapped === "length" ? "length" : "stop", message: state.output });
+			state.output.stopReason = verdict.stopReason;
+			stream.push({
+				type: "done",
+				reason: verdict.stopReason === "length" ? "length" : "stop",
+				message: state.output,
+			});
 		}
 		stream.end();
 	}
@@ -601,6 +838,7 @@ export function streamAcpTurn(
 		// connection + child so it is not orphaned in retainedChildren (GPT blocker 2).
 		if (decision.path === "new" && existing) {
 			existing.alive = false;
+			existing.retiring = true;
 			if (bridgeSessions.get(sessionKey) === existing) bridgeSessions.delete(sessionKey);
 			retainedChildren.delete(existing.child);
 			existing.connection.close?.();
@@ -639,10 +877,23 @@ export function streamAcpTurn(
 		try {
 			if (signal?.aborted) throw new Error("aborted before launch");
 
+			// A backend session that died BETWEEN turns is announced here, before
+			// the bootstrap notice — otherwise this turn looks like an ordinary
+			// cold start and the operator never learns that the session they were
+			// talking to ended. Announced once (read-and-clear); the turn continues
+			// normally, since opening a fresh child for a NEW user turn is not a
+			// replay of anything.
+			const priorEnd = takeUnreportedChildEnd(sessionKey);
+			if (priorEnd) {
+				pushAcpLifecycleNotice(
+					state,
+					`previous ${adapter.backend} session ended between turns (${describeChildEnd(priorEnd)}) — opening a new one`,
+				);
+			}
 			// S2f visibility: surface the otherwise-silent bootstrap so a slow
 			// overlay/spawn/init does not read as a hang. Display-only (marked).
 			pushAcpLifecycleNotice(state, `preparing ${adapter.backend} session`);
-			// GPT §9-5: materialize the overlay first, then spawn with launchEnvDefaults
+			// Overlay ordering (rail “Adapter contract”): materialize the overlay first, then spawn with launchEnvDefaults
 			// + overlay.envOverrides merged over process.env (defaultDeps spawnChild).
 			// sessionKey is the AUTHORITATIVE per-session identity (resolveSessionKey:
 			// opts.sessionId → PI_SESSION_ID → cwd) — a session-scoped overlay must
@@ -659,6 +910,11 @@ export function streamAcpTurn(
 				if (stderrTail.length > 50) stderrTail.shift();
 			});
 
+			// Abort during BOOTSTRAP (spawn → initialize → newSession → set-model):
+			// there is no prompt turn for the agent to cancel yet, so the child is
+			// simply torn down. This listener is handed off before the prompt —
+			// awaitAcpPromptTurn installs the protocol-cancel-first one for that
+			// window, and two live listeners would race SIGTERM against the cancel.
 			if (signal) {
 				onAbort = () => killChildGroup(spawned, "SIGTERM");
 				signal.addEventListener("abort", onAbort, { once: true });
@@ -700,9 +956,15 @@ export function streamAcpTurn(
 				alive: true,
 				busy: true,
 				activePromptHandler: undefined,
+				// SAME array the stderr drain above pushes into: the buffer outlives
+				// this turn with the session, so a later reuse turn can still report
+				// the child's dying words.
+				stderrTail,
 			};
 			const sess = session;
-			spawned.once("exit", () => onChildGone(sess));
+			spawned.once("exit", (...args: unknown[]) =>
+				onChildGone(sess, { code: (args[0] as number | null) ?? null, signal: (args[1] as NodeJS.Signals) ?? null }),
+			);
 			spawned.once("error", () => onChildGone(sess));
 
 			await withTimeout(
@@ -730,7 +992,7 @@ export function streamAcpTurn(
 				modelId: model.id,
 				piSessionId: process.env.PI_SESSION_ID?.trim() || undefined,
 			});
-			// GPT §9-4: omit the `_meta` KEY entirely for a carrier-less backend
+			// Carrier-less shape (rail “Adapter contract”): omit the `_meta` KEY entirely for a carrier-less backend
 			// (sessionMeta === undefined), not `_meta: undefined`.
 			const newSessionArgs =
 				sessionMeta === undefined
@@ -776,10 +1038,16 @@ export function streamAcpTurn(
 			// prompt could still sync-reject before the wire write; the next visible
 			// event after this is the backend's own first token / tool notice.
 			pushAcpLifecycleNotice(state, "sending prompt");
-			const promptResult = await withTimeout(
-				"prompt",
-				connection.prompt({ sessionId: acpSessionId, prompt }),
-				PROMPT_TIMEOUT_MS,
+			// Hand the abort window over to the prompt driver: from here on an abort
+			// is a protocol `session/cancel` first, teardown only after the grace.
+			if (signal && onAbort) {
+				signal.removeEventListener("abort", onAbort);
+				onAbort = undefined;
+			}
+			const promptResult = await awaitAcpPromptTurn(
+				session,
+				{ sessionId: acpSessionId, prompt },
+				{ signal, graceMs: deps.abortGraceMs ?? ABORT_CANCEL_GRACE_MS },
 			);
 
 			session.activePromptHandler = undefined;
@@ -798,6 +1066,7 @@ export function streamAcpTurn(
 				unrefRetainedChild(spawned);
 				persistRecord(session, deps);
 			} else {
+				session.retiring = true;
 				connection.close?.();
 				teardownChild(spawned);
 			}
@@ -811,11 +1080,12 @@ export function streamAcpTurn(
 			// error/abort → drop the (uncertain) session and close its child; an
 			// uncertain connection must never be reused (GPT ④).
 			if (child) {
+				if (session) session.retiring = true;
 				retainedChildren.delete(child);
 				session?.connection.close?.(err);
 				teardownChild(child);
 			}
-			finishError(err, aborted, stderrTail);
+			finishError(err, aborted, session?.stderrTail ?? stderrTail);
 		} finally {
 			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
 		}
@@ -823,7 +1093,6 @@ export function streamAcpTurn(
 
 	// --- reuse: send only the latest user delta to the live ACP session
 	async function runReuseTurn(session: BridgeSession, ctxSigs: string[]): Promise<void> {
-		let onAbort: (() => void) | undefined;
 		try {
 			if (signal?.aborted) throw new Error("aborted before prompt");
 
@@ -832,10 +1101,6 @@ export function streamAcpTurn(
 			pushAcpLifecycleNotice(state, "reusing live session");
 			session.busy = true;
 			session.activePromptHandler = makePromptHandler(session);
-			if (signal) {
-				onAbort = () => killChildGroup(session.child, "SIGTERM");
-				signal.addEventListener("abort", onAbort, { once: true });
-			}
 
 			// The live ACP session already remembers the prior turns → send only the
 			// latest user delta (re-sending the transcript would duplicate history).
@@ -844,10 +1109,12 @@ export function streamAcpTurn(
 
 			// S2f visibility: about to send the delta to the resident child.
 			pushAcpLifecycleNotice(state, "sending prompt");
-			const promptResult = await withTimeout(
-				"prompt",
-				session.connection.prompt({ sessionId: session.acpSessionId, prompt }),
-				PROMPT_TIMEOUT_MS,
+			// A reuse turn has no bootstrap window at all — the prompt driver owns
+			// the whole abort surface (protocol cancel first, teardown after grace).
+			const promptResult = await awaitAcpPromptTurn(
+				session,
+				{ sessionId: session.acpSessionId, prompt },
+				{ signal, graceMs: deps.abortGraceMs ?? ABORT_CANCEL_GRACE_MS },
 			);
 
 			session.activePromptHandler = undefined;
@@ -864,12 +1131,14 @@ export function streamAcpTurn(
 			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);
+			session.retiring = true;
 			retainedChildren.delete(session.child);
 			session.connection.close?.(err);
 			teardownChild(session.child);
-			finishError(err, aborted);
-		} finally {
-			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+			// 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/acp/config.ts

@@ -23,7 +23,7 @@
 // the backend-invariant exclude-tools preflight and folds every one of them into
 // `bridgeConfigSignature` (so changing one still invalidates a reused cortex
 // session). Backend-OWNED settings never land here: they ride the opaque
-// `adapterSettings` seam (§10 B), which is what keeps a backend-named key like
+// `adapterSettings` seam (rail “Adapter contract”), which is what keeps a backend-named key like
 // `cortexConnection` off this common shape.
 //
 // PURITY / SIGNATURE contract (NEXT oracle C / 핀1 / GPT `…2f9325` boost):