@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/modes/acp/acp-agent.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import {
 	type Agent,
@@ -5,15 +6,11 @@ import {
 	type AuthenticateRequest,
 	type AuthenticateResponse,
 	type AuthMethod,
-	type AvailableCommand,
 	type ClientCapabilities,
 	type CloseSessionRequest,
 	type CloseSessionResponse,
-	type CreateElicitationResponse,
 	type DeleteSessionRequest,
 	type DeleteSessionResponse,
-	type ElicitationContentValue,
-	type ElicitationPropertySchema,
 	type ForkSessionRequest,
 	type ForkSessionResponse,
 	type InitializeRequest,
@@ -22,7 +19,6 @@ import {
 	type ListSessionsResponse,
 	type LoadSessionRequest,
 	type LoadSessionResponse,
-	type McpServer,
 	type NewSessionRequest,
 	type NewSessionResponse,
 	PROTOCOL_VERSION,
@@ -30,471 +26,576 @@ import {
 	type PromptResponse,
 	type ResumeSessionRequest,
 	type ResumeSessionResponse,
-	type SessionConfigOption,
 	type SessionInfo,
-	type SessionModeState,
 	type SessionNotification,
-	type SessionUpdate,
 	type SetSessionConfigOptionRequest,
 	type SetSessionConfigOptionResponse,
 	type SetSessionModeRequest,
 	type SetSessionModeResponse,
-	type Usage,
 } from "@agentclientprotocol/sdk";
-import type { AssistantMessage, Model } from "@gajae-code/ai";
-import { logger } from "@gajae-code/utils";
+import { getAgentDir } from "@gajae-code/utils";
 import packageJson from "../../../package.json" with { type: "json" };
-import { disableProvider, enableProvider, reset as resetCapabilities } from "../../capability";
-import { Settings } from "../../config/settings";
-import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../../discovery/helpers";
-import type { ExtensionUIContext, ExtensionUIDialogOptions } from "../../extensibility/extensions";
-import { runExtensionCompact } from "../../extensibility/extensions/compact-handler";
-import { getSessionSlashCommands } from "../../extensibility/extensions/get-commands-handler";
-import { resolveSubskillActivationForSkillInvocation } from "../../extensibility/gjc-plugins";
 import {
-	buildSkillPromptMessage,
-	getSkillSlashCommandNames,
-	isNamespacedSkillSlashCommandName,
-	isSkillSlashCommandName,
-	parseSkillInvocations,
-} from "../../extensibility/skills";
-import { loadSlashCommands } from "../../extensibility/slash-commands";
-import { loadAllExtensions } from "../../modes/components/extensions/state-manager";
-import { theme } from "../../modes/theme/theme";
-import { MCPManager } from "../../runtime-mcp/manager";
-import type { MCPServerConfig } from "../../runtime-mcp/types";
-import type { AgentSession, AgentSessionEvent } from "../../session/agent-session";
-import { isSilentAbort, SKILL_PROMPT_MESSAGE_TYPE } from "../../session/messages";
-import { isLegacyProviderSafetyStopMessage } from "../../session/provider-safety-stop";
-import {
-	SessionManager,
-	type SessionInfo as StoredSessionInfo,
-	type StrictInventoryCandidate,
-	type UsageStatistics,
-} from "../../session/session-manager";
-import {
-	FileSessionStorage,
-	type SessionStorageFileIdentity,
-	type VerifiedSessionDeleteResult,
-	type VerifiedSessionDeleteTarget,
-} from "../../session/session-storage";
-import { ACP_BUILTIN_SLASH_COMMANDS, executeAcpBuiltinSlashCommand } from "../../slash-commands/acp-builtins";
-import { parseThinkingLevel } from "../../thinking";
-import { toAgentWireEventPayload } from "../shared/agent-wire/event-envelope";
-import { createAcpClientBridge } from "./acp-client-bridge";
-import {
-	buildToolCallStartUpdate,
-	mapAgentWireEventPayloadToAcpSessionUpdates,
-	normalizeReplayToolArguments,
-} from "./acp-event-mapper";
+	type AcpProviderRegistration,
+	type AcpReverseConnection,
+	AcpSdkAdapter,
+	AcpSdkAdapterError,
+} from "../../sdk/acp";
+import { ensureBroker } from "../../sdk/broker/ensure";
+import { readSdkBrokerDiscovery, SdkClient } from "../../sdk/client";
+import { mapAgentWireEventPayloadToAcpSessionUpdates } from "./acp-event-mapper";
+import { resolveAcpPermissionMode } from "./permission-mode";
+import type { AcpStartupOptions } from "./startup-options";
 import { ACP_TERMINAL_AUTH_FLAG } from "./terminal-auth";
 
 const ACP_DEFAULT_MODE_ID = "default";
 const ACP_PLAN_MODE_ID = "plan";
-const DEFAULT_PLAN_FILE_URL = "local://PLAN.md";
 const MODE_CONFIG_ID = "mode";
 const MODEL_CONFIG_ID = "model";
 const THINKING_CONFIG_ID = "thinking";
-const THINKING_OFF = "off";
 const SESSION_PAGE_SIZE = 50;
+export const ACP_BOOTSTRAP_RACE_GUARD_MS = 50;
+const MAX_ACP_REPLAY_PAGES = 10_000;
 
+type JsonObject = Record<string, unknown>;
 /**
- * One immutable authorization snapshot built from a complete strict scoped inventory.
- * `entries` maps every discovered session id to either the single exact-identity
- * candidate (authoritative) or a conflict tombstone (duplicate/unsafe). The snapshot
- * is built once, before pagination, so a duplicate beyond page 1 is known before the
- * first page response. Lifecycle changes bump {@link #authorityGeneration} and
- * invalidate the snapshot.
+ * ACP prompt completion is tied to a post-acknowledgement lifecycle boundary.
+ * AgentSession events do not carry the command identity themselves, so the
+ * host stamps command/turn identities into its replay ring and ACP also keeps
+ * a per-endpoint ingress sequence. A frame observed before an acknowledgement
+ * can never settle the waiter that acknowledgement creates.
  */
-type AcpAuthorityEntry =
-	| { kind: "candidate"; candidate: StrictInventoryCandidate }
-	| { kind: "conflict"; reason: string };
-/**
- * Phase-aware same-connection retry evidence for an incomplete verified delete.
- * The transcript identity is always recorded and re-verified on retry; the
- * artifacts identity is recorded only when the failure occurred at the
- * artifacts phase (the artifact directory still existed at failure time).
- */
-type PendingDeleteEvidence = {
-	transcriptIdentity: SessionStorageFileIdentity;
-	artifactsIdentity?: SessionStorageFileIdentity;
-};
+interface PromptWaiter {
+	cancelRequested: boolean;
+	acknowledged: boolean;
+	activityObserved: boolean;
+	/** The prompt was accepted while the host was already busy, so its next valid idle ends the steer. */
+	steeringAtAcknowledgement: boolean;
+	/** Highest inbound frame sequence already observed when the prompt was acknowledged. */
+	boundary: number;
+	correlation: PromptCorrelation;
+	pendingTerminal?: PromptCorrelation;
+	resolve: (response: PromptResponse) => void;
+	reject: (error: Error) => void;
+}
 
-type AcpAuthoritySnapshot = {
-	scope: string;
-	entries: Map<string, AcpAuthorityEntry>;
-	/** Ordered unique session ids (conflicts appear once at first sight) for paging. */
-	orderedIds: string[];
-	generation: number;
-};
-/**
- * Delay between `session/new` (or `session/load` / `session/resume` /
- * `unstable_session/fork`) returning and the agent firing the first
- * notifications against the new session id. Mitigates Zed's
- * `Received session notification for unknown session` race — see
- * `#scheduleBootstrapUpdates`. Exported so the ACP test harness can
- * wait past this guard without hard-coding the literal.
- */
-export const ACP_BOOTSTRAP_RACE_GUARD_MS = 50;
-const CODING_AGENT_VERSION: string = packageJson.version;
-const ACP_CANCEL_CLEANUP_TIMEOUT_MS = 5_000;
-const ACP_ASYNC_DELIVERY_DRAIN_TIMEOUT_MS = 250;
-const ACP_ASYNC_DELIVERY_DRAIN_MAX_PASSES = 3;
-
-type AgentImageContent = {
-	type: "image";
-	data: string;
-	mimeType: string;
+type PromptCorrelation = { commandId?: string; turnId?: string };
+
+type BrokerConnection = { adapter: AcpSdkAdapter; client: SdkClient };
+type PendingAttachment = { epoch: number; task: Promise<void> };
+
+type SessionRecord = {
+	cwd: string;
+	adapter: AcpSdkAdapter;
+	unsubscribe: () => void;
+	reconnectUnsubscribe: () => void;
+	/** Per-session frame work queue; callbacks never race prompt ownership. */
+	frameTail: Promise<void>;
+	/** Monotonic at WebSocket ingress, before queued work begins. */
+	inboundSequence: number;
+	/** Updated at ingress so a prompt acknowledgement can distinguish a steer from a fresh turn. */
+	busy: boolean;
+	activePrompt?: PromptWaiter;
 };
+type Endpoint = { url: string; token: string };
 
-type PromptQueueState = {
-	promise: Promise<void>;
-	release: (() => void) | undefined;
+type BrokerSession = {
+	sessionId: string;
+	locator?: { repo?: string };
+	live?: boolean;
+	endpointGeneration?: number;
 };
 
-type PromptTurnState = {
-	userMessageId: string;
-	cancelRequested: boolean;
-	settled: boolean;
-	/**
-	 * `abort()` is in-flight (or its bounded-timeout race). `undefined` while the turn is
-	 * running normally and after cleanup completes. The turn occupies `record.promptTurn`
-	 * for as long as either `!settled` or `cleanup` is set — that combined window is the
-	 * "turn in flight" predicate (`isPromptTurnInFlight`) every consumer gates on.
-	 */
-	cleanup: Promise<void> | undefined;
-	usageBaseline: UsageStatistics;
-	unsubscribe: (() => void) | undefined;
-	resolve: (value: PromptResponse) => void;
-	reject: (reason?: unknown) => void;
-	promise: Promise<PromptResponse>;
-};
+function parseAcpStartupOptions(value: unknown): AcpStartupOptions | undefined {
+	const candidate = object(value);
+	if (!candidate) return undefined;
+	const modelId = typeof candidate.modelId === "string" ? candidate.modelId : undefined;
+	const modelPreset = typeof candidate.modelPreset === "string" ? candidate.modelPreset : undefined;
+	const thinkingLevel = typeof candidate.thinkingLevel === "string" ? candidate.thinkingLevel : undefined;
+	return modelId || modelPreset || thinkingLevel
+		? {
+				...(modelId ? { modelId } : {}),
+				...(modelPreset ? { modelPreset } : {}),
+				...(thinkingLevel ? { thinkingLevel } : {}),
+			}
+		: undefined;
+}
 
-/**
- * A turn is "in flight" from the moment `prompt()` reserves the slot until `settled` is
- * true AND any cancel cleanup has completed. Fork/queue/event gating all depend on this
- * combined window — a settled-but-still-aborting turn is not safe to fork from, queue
- * onto, or forward late events for.
- */
-function isPromptTurnInFlight(turn: PromptTurnState | undefined): turn is PromptTurnState {
-	return turn !== undefined && (!turn.settled || turn.cleanup !== undefined);
+function object(value: unknown): JsonObject | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as JsonObject) : undefined;
+}
+
+function aggregateAcpFailure(code: string, message: string, failures: unknown[]): AcpSdkAdapterError {
+	const aggregate = new AggregateError(failures, message);
+	return Object.assign(new AcpSdkAdapterError(code, aggregate.message), {
+		cause: aggregate,
+		errors: aggregate.errors,
+	});
+}
+
+/** Applies ACP's offset cursor after narrowing the broker listing to the requested cwd. */
+export function paginateAcpSessions(listed: unknown[], cwd: string | undefined, offset: number): ListSessionsResponse {
+	const filtered = listed
+		.map(value => object(value) as BrokerSession | undefined)
+		.filter(
+			(value): value is BrokerSession & { locator: { repo: string } } =>
+				typeof value?.sessionId === "string" && typeof value.locator?.repo === "string",
+		)
+		.filter(value => !cwd || value.locator.repo === cwd);
+	const sessions = filtered
+		.slice(offset, offset + SESSION_PAGE_SIZE)
+		.map(
+			value =>
+				({ sessionId: value.sessionId, cwd: value.locator.repo, title: value.sessionId }) satisfies SessionInfo,
+		);
+	return {
+		sessions,
+		nextCursor: offset + sessions.length < filtered.length ? String(offset + sessions.length) : undefined,
+	};
+}
+
+function endpoint(value: unknown): Endpoint {
+	const candidate = object(value);
+	const result = object(candidate?.result) ?? candidate;
+	const nested = object(result?.endpoint) ?? result;
+	if (typeof nested?.url !== "string" || typeof nested.token !== "string")
+		throw new AcpSdkAdapterError("unavailable", "SDK lifecycle response omitted a session endpoint.");
+	return { url: nested.url, token: nested.token };
+}
+
+function sessionId(value: unknown): string {
+	const candidate = object(value);
+	const result = object(candidate?.result) ?? candidate;
+	if (typeof result?.sessionId !== "string" || !result.sessionId)
+		throw new AcpSdkAdapterError("unavailable", "SDK lifecycle response omitted a session id.");
+	return result.sessionId;
 }
 
+function pageItems(value: unknown): unknown[] {
+	const response = object(value);
+	const result = object(response?.result) ?? response;
+	const page = object(result?.page);
+	return Array.isArray(page?.items) ? page.items : [];
+}
+
+function correlationFrom(...values: unknown[]): PromptCorrelation {
+	const correlation: PromptCorrelation = {};
+	for (const value of values) {
+		const candidate = object(value);
+		for (const record of [candidate, object(candidate?.result)]) {
+			if (!record) continue;
+			if (!correlation.commandId) {
+				const commandId = record.commandId ?? record.command_id;
+				if (typeof commandId === "string" && commandId) correlation.commandId = commandId;
+			}
+			if (!correlation.turnId) {
+				const turnId = record.turnId ?? record.turn_id;
+				if (typeof turnId === "string" && turnId) correlation.turnId = turnId;
+			}
+		}
+	}
+	return correlation;
+}
+
+function correlationsConflict(expected: PromptCorrelation, actual: PromptCorrelation): boolean {
+	return (
+		(expected.commandId !== undefined && actual.commandId !== undefined && expected.commandId !== actual.commandId) ||
+		(expected.turnId !== undefined && actual.turnId !== undefined && expected.turnId !== actual.turnId)
+	);
+}
+
+function correlationsMatch(expected: PromptCorrelation, actual: PromptCorrelation): boolean {
+	return (
+		(expected.commandId !== undefined && expected.commandId === actual.commandId) ||
+		(expected.turnId !== undefined && expected.turnId === actual.turnId)
+	);
+}
+
+function isPromptActivity(eventType: string): boolean {
+	return [
+		"agent_start",
+		"turn_start",
+		"message_start",
+		"message_update",
+		"message_end",
+		"tool_execution_start",
+		"tool_execution_update",
+		"tool_execution_end",
+	].includes(eventType);
+}
+
+export type TranscriptReplayBlock = { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
+
 /**
- * Per-record terminal state machine for session deletion.
- * - `active`: normal operation; all lifecycle methods allowed.
- * - `deleting`: a terminal delete has reserved the record; prompt/config/close/
- *   load/resume/fork reject, concurrent deletes join the terminal promise.
- * - `pre_dispatch_retryable`: close_failed_retryable before verified-delete
- *   dispatch; normal ops rejected but a subsequent delete may retry.
- * - `cleanup_pending`: verified delete returned cleanup_pending with identity
- *   evidence; normal ops rejected but a subsequent delete may retry.
- * - `terminal_failure`: close_unknown or quiescence failure (or any unexpected
- *   failure); normal ops rejected and delete NEVER reopens — subsequent deletes
- *   share the settled terminal failure error.
- * - `deleted`: verified delete succeeded; record removed from the active map.
+ * The production transcript query exposes durable `{ body, textSummary }`
+ * entries, not an ACP-shaped `content` array. Historical session JSONL has no
+ * recoverable image bytes, so replay exposes that boundary rather than
+ * pretending images were restored.
  */
-type AcpSessionTerminalState =
-	| "active"
-	| "deleting"
-	| "pre_dispatch_retryable"
-	| "cleanup_pending"
-	| "terminal_failure"
-	| "deleted";
-
-type ManagedSessionRecord = {
-	session: AgentSession;
-	mcpManager: MCPManager | undefined;
-	promptTurn: PromptTurnState | undefined;
-	promptQueue: PromptQueueState;
-	liveMessageId: string | undefined;
-	liveMessageProgress: { textEmitted: boolean; thoughtEmitted: boolean } | undefined;
-	toolArgsById: Map<string, unknown>;
-	extensionsConfigured: boolean;
-	// Installed after the bootstrap race guard or eagerly when the client starts a prompt;
-	// released in `#disposeSessionRecord`. Lives independent of any prompt turn.
-	lifetimeUnsubscribe: (() => void) | undefined;
-	// Per-record terminal state machine (see AcpSessionTerminalState). After ANY
-	// delete failure the record stays non-`active` so prompt/config/close/load/
-	// resume/fork remain rejected. Only `pre_dispatch_retryable` and
-	// `cleanup_pending` permit a retry delete; `terminal_failure` never reopens.
-	terminalState: AcpSessionTerminalState;
-	// The settled terminal failure error, shared with subsequent delete callers
-	// so a terminal_failure is observable without re-running the terminal op.
-	terminalFailure: Error | undefined;
-	// Resolves when an in-progress terminal delete settles. Concurrent delete
-	// callers and abort/shutdown join this promise.
-	terminalPromise: Promise<DeleteSessionResponse> | undefined;
-};
-
-type ReplayableMessage = {
-	role: string;
-	content?: unknown;
-	errorMessage?: string;
-	toolCallId?: string;
-	toolName?: string;
-	details?: unknown;
-	isError?: boolean;
-};
+export interface TranscriptReplayContent {
+	blocks: TranscriptReplayBlock[];
+	images: { available: false; reason: "historical_transcript_images_unavailable" };
+}
 
-type ReplayableToolItem = {
-	type?: unknown;
-	id?: unknown;
-	name?: unknown;
-	arguments?: unknown;
-	input?: unknown;
-};
+export function transcriptReplayContent(entry: unknown): TranscriptReplayContent {
+	const record = object(entry);
+	if (typeof record?.body !== "string")
+		throw new AcpSdkAdapterError(
+			"transcript_body_unavailable",
+			"ACP cannot replay a transcript entry without its production body.",
+		);
+	return {
+		blocks: record.body.length > 0 ? [{ type: "text", text: record.body }] : [],
+		images: { available: false, reason: "historical_transcript_images_unavailable" },
+	};
+}
 
-type MCPConfigMap = {
-	[name: string]: MCPServerConfig;
+type ReceivedSdkEvent = {
+	event: JsonObject;
+	/** Event payload accepted by the ACP event mapper, when this is an agent-wire frame. */
+	wirePayload?: JsonObject;
 };
 
-type MCPSource = {
-	provider: string;
-	providerName: string;
-	path: string;
-	level: "project";
-};
+/**
+ * Native session hosts emit `activity` directly; test-only/legacy adapters may
+ * wrap agent-wire events in `{ type: "event", payload }`. Normalize both
+ * without treating notification-specific frames as agent lifecycle truth.
+ */
+function receivedSdkEvent(frame: JsonObject): ReceivedSdkEvent | undefined {
+	if (frame.type === "activity") {
+		const type = frame.state === "busy" ? "agent_start" : frame.state === "idle" ? "agent_end" : undefined;
+		return type ? { event: { type, ...correlationFrom(frame) } } : undefined;
+	}
+	if (frame.type !== "event") return undefined;
+	const payload = object(frame.payload);
+	if (!payload) return undefined;
+	const replayPayload = object(payload.payload);
+	const event = object(payload.event) ?? replayPayload ?? payload;
+	if (typeof event.type !== "string") return undefined;
+	return {
+		event,
+		...(object(payload.event) ? { wirePayload: payload } : {}),
+	};
+}
 
-type MCPSourceMap = {
-	[name: string]: MCPSource;
+const ACP_CONFIG_OPTIONS = [
+	{ id: MODEL_CONFIG_ID, name: "Model", options: [] },
+	{ id: THINKING_CONFIG_ID, name: "Thinking", options: [] },
+	{
+		id: "steeringMode",
+		name: "Steering queue",
+		options: [
+			{ value: "all", name: "All" },
+			{ value: "one-at-a-time", name: "One at a time" },
+		],
+	},
+	{
+		id: "followUpMode",
+		name: "Follow-up queue",
+		options: [
+			{ value: "all", name: "All" },
+			{ value: "one-at-a-time", name: "One at a time" },
+		],
+	},
+	{
+		id: "interruptMode",
+		name: "Interrupt mode",
+		options: [
+			{ value: "immediate", name: "Immediate" },
+			{ value: "wait", name: "Wait" },
+		],
+	},
+] as const;
+
+const ACP_CONFIG_CONTROL_OPERATIONS: Record<string, string> = {
+	steeringMode: "queue.steering_mode.set",
+	followUpMode: "queue.follow_up_mode.set",
+	interruptMode: "queue.interrupt_mode.set",
 };
 
-type CreateAcpSession = (cwd: string) => Promise<AgentSession>;
+function configValues(query: unknown): Map<string, string> {
+	const values = new Map<string, string>();
+	for (const item of pageItems(query)) {
+		const record = object(item);
+		if (!record) continue;
+		if (typeof record.id === "string" && typeof record.value === "string") {
+			values.set(record.id, record.value);
+			continue;
+		}
+		for (const [id, value] of Object.entries(record)) {
+			if (typeof value === "string") values.set(id, value);
+		}
+	}
+	return values;
+}
 
-/**
- * Bridge a single ExtensionUIContext call to the ACP `unstable_createElicitation`
- * surface. Skills/extensions ask for one value at a time (a chosen option, a
- * confirmation, a piece of text), so every elicitation here uses a one-property
- * `value` schema; the caller narrows the resulting `ElicitationContentValue`
- * back to its concrete primitive type.
- *
- * `dialogOptions.signal` short-circuits the elicitation if it is already
- * aborted and races the in-flight request against the abort event. The SDK
- * exposes no `cancel_elicitation` surface for form-mode elicitations
- * (`unstable_completeElicitation` is URL-mode only), so the ACP request itself
- * keeps running on the client side until the user dismisses it — but
- * resolving the local promise unblocks the caller (matches the RPC mode
- * pattern in `requestRpcEditor`). The abort listener is removed once the
- * elicitation settles so that callers which reuse the same signal across many
- * elicitations (e.g. `ask` multi-select loops) don't accumulate listeners and
- * trip Node's `MaxListeners` warning.
- *
- * `dialogOptions.timeout` mirrors `RpcExtensionUIContext.#createDialogPromise`:
- * when the timer fires before the client responds, `onTimeout` is invoked and
- * the caller's promise resolves to the stub fallback. Late SDK responses that
- * arrive after abort/timeout — both rejections and successful `accept`s —
- * are dropped silently (no `logger.warn`) to keep operator logs clean.
- */
-async function elicitFromAcpClient(
-	connection: AgentSideConnection,
-	sessionId: string,
-	method: "select" | "confirm" | "input",
-	message: string,
-	property: ElicitationPropertySchema,
-	dialogOptions: ExtensionUIDialogOptions | undefined,
-): Promise<ElicitationContentValue | undefined> {
-	const signal = dialogOptions?.signal;
-	if (signal?.aborted) {
-		return undefined;
+function modelConfigOptions(query: unknown, current: string | undefined): { value: string; name: string }[] {
+	const options = new Map<string, string>();
+	for (const item of pageItems(query)) {
+		const model = object(item);
+		if (!model || typeof model.provider !== "string" || typeof model.id !== "string") continue;
+		const value = `${model.provider}/${model.id}`;
+		options.set(value, typeof model.name === "string" ? model.name : value);
 	}
-	const { promise, resolve } = Promise.withResolvers<CreateElicitationResponse | undefined>();
-	let settled = false;
-	let timeoutId: NodeJS.Timeout | undefined;
-	const finish = (value: CreateElicitationResponse | undefined) => {
-		if (settled) return;
-		settled = true;
-		if (timeoutId !== undefined) clearTimeout(timeoutId);
-		signal?.removeEventListener("abort", onAbort);
-		resolve(value);
+	if (current && !options.has(current)) options.set(current, current);
+	return [...options].map(([value, name]) => ({ value, name }));
+}
+
+const THINKING_CONFIG_OPTIONS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"].map(value => ({
+	value,
+	name: value,
+}));
+
+/** Maps live canonical SDK config and model queries into the ACP 1.2.1 session state surface. */
+export function acpSessionStateFromConfig(query: unknown, modelsQuery?: unknown) {
+	const values = configValues(query);
+	const currentModeId = values.get(MODE_CONFIG_ID) === ACP_PLAN_MODE_ID ? ACP_PLAN_MODE_ID : ACP_DEFAULT_MODE_ID;
+	return {
+		configOptions: [
+			{
+				id: MODE_CONFIG_ID,
+				name: "Mode",
+				type: "select" as const,
+				currentValue: currentModeId,
+				options: [
+					{ value: ACP_DEFAULT_MODE_ID, name: "Default" },
+					{ value: ACP_PLAN_MODE_ID, name: "Plan" },
+				],
+			},
+			...ACP_CONFIG_OPTIONS.flatMap(option => {
+				const value = values.get(option.id);
+				if (value === undefined) return [];
+				const options =
+					option.id === MODEL_CONFIG_ID
+						? modelConfigOptions(modelsQuery, value)
+						: option.id === THINKING_CONFIG_ID
+							? THINKING_CONFIG_OPTIONS
+							: [...option.options];
+				return [{ ...option, type: "select" as const, currentValue: value, options }];
+			}),
+		],
+		modes: {
+			availableModes: [
+				{ id: ACP_DEFAULT_MODE_ID, name: "Default" },
+				{ id: ACP_PLAN_MODE_ID, name: "Plan" },
+			],
+			currentModeId,
+		},
 	};
-	const onAbort = () => finish(undefined);
-	signal?.addEventListener("abort", onAbort, { once: true });
-	if (dialogOptions?.timeout !== undefined) {
-		timeoutId = setTimeout(() => {
-			if (settled) return;
-			try {
-				dialogOptions.onTimeout?.();
-			} catch (error) {
-				// A throwing `onTimeout` must not leave the elicitation promise
-				// pending — settle it via `finish` below regardless.
-				logger.warn("ACP elicitation onTimeout threw", { sessionId, method, error });
+}
+
+/** Convert every ACP prompt block the agent advertises without silently discarding context. */
+export function acpPromptPayload(blocks: PromptRequest["prompt"]): {
+	text: string;
+	images: Array<{ data: string; mimeType: string }>;
+} {
+	const text: string[] = [];
+	const images: Array<{ data: string; mimeType: string }> = [];
+	for (const block of blocks) {
+		switch (block.type) {
+			case "text":
+				text.push(block.text);
+				break;
+			case "image":
+				if (block.uri) text.push(`[Image URI: ${block.uri}]`);
+				images.push({ data: block.data, mimeType: block.mimeType });
+				break;
+			case "resource_link":
+				text.push(
+					[
+						`[Resource: ${block.name}]`,
+						`URI: ${block.uri}`,
+						...(block.title ? [`Title: ${block.title}`] : []),
+						...(block.description ? [block.description] : []),
+						...(block.mimeType ? [`MIME: ${block.mimeType}`] : []),
+						...(typeof block.size === "number" ? [`Size: ${block.size}`] : []),
+					].join("\n"),
+				);
+				break;
+			case "resource": {
+				const resource = block.resource;
+				if ("text" in resource) {
+					text.push(
+						[
+							`[Resource: ${resource.uri}]`,
+							...(resource.mimeType ? [`MIME: ${resource.mimeType}`] : []),
+							resource.text,
+						].join("\n"),
+					);
+					break;
+				}
+				const mimeType = resource.mimeType ?? "application/octet-stream";
+				if (!mimeType.startsWith("image/"))
+					throw new AcpSdkAdapterError(
+						"unsupported_content",
+						`Unsupported embedded resource MIME type: ${mimeType}`,
+					);
+				text.push(`[Resource: ${resource.uri}]\nMIME: ${mimeType}`);
+				images.push({ data: resource.blob, mimeType });
+				break;
 			}
-			finish(undefined);
-		}, dialogOptions.timeout);
-		// A long pending timeout alone shouldn't keep the event loop alive when
-		// the rest of the agent has shut down — matches `job-manager.ts` /
-		// `executor.ts` timer hygiene. Connection + session lifetimes keep the
-		// loop alive on the happy path.
-		timeoutId.unref();
+			case "audio":
+				throw new AcpSdkAdapterError("unsupported_content", "ACP audio prompts are not supported.");
+			default:
+				throw new AcpSdkAdapterError("unsupported_content", "Unsupported ACP prompt content.");
+		}
 	}
-	connection
-		.unstable_createElicitation({
-			mode: "form",
-			sessionId,
+	if (text.length === 0 && images.length === 0)
+		throw new AcpSdkAdapterError("invalid_input", "ACP prompt must contain at least one supported content block.");
+	return { text: text.join("\n"), images };
+}
+
+/** Registers a permission provider only when the ACP client requires prompts. */
+export function acpProviderRegistrations(
+	capabilities: ClientCapabilities | undefined,
+	env: NodeJS.ProcessEnv = process.env,
+): AcpProviderRegistration[] {
+	return [
+		...(capabilities?.fs?.readTextFile || capabilities?.fs?.writeTextFile
+			? [{ capability: "fs", definitions: [] }]
+			: []),
+		...(capabilities?.terminal ? [{ capability: "terminal", definitions: [] }] : []),
+		...(resolveAcpPermissionMode(capabilities, env) === "prompt"
+			? [{ capability: "permission", definitions: [] }]
+			: []),
+		{ capability: "ui", definitions: [] },
+	];
+}
+
+/** Maps ACP permission handling to the session's canonical SDK policy. */
+export async function applyAcpPermissionMode(
+	adapter: Pick<AcpSdkAdapter, "control">,
+	capabilities: ClientCapabilities | undefined,
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+	const mode = resolveAcpPermissionMode(capabilities, env);
+	await adapter.control("permission_mode.set", { mode: mode === "prompt" ? "prompt" : "allow" });
+}
+
+/** Applies CLI-provided ACP startup settings through SDK controls before session exposure. */
+export async function applyAcpStartupOptions(
+	adapter: Pick<AcpSdkAdapter, "setModel" | "control">,
+	options: AcpStartupOptions | undefined,
+): Promise<void> {
+	if (options?.modelId) await adapter.setModel(options.modelId);
+	if (options?.thinkingLevel) await adapter.control("thinking.set", { level: options.thinkingLevel });
+}
+
+/** ACP form elicitation uses the client-facing reverse surface without owning a session runtime. */
+export function createAcpExtensionUiContext(
+	connection: AgentSideConnection,
+	getSessionId: () => string,
+	capabilities: ClientCapabilities | undefined,
+): {
+	select: (
+		message: string,
+		options: string[],
+		dialog?: { signal?: AbortSignal; timeout?: number; onTimeout?: () => void },
+	) => Promise<string | undefined>;
+	confirm: (
+		message: string,
+		detail?: string,
+		dialog?: { signal?: AbortSignal; timeout?: number; onTimeout?: () => void },
+	) => Promise<boolean>;
+	input: (
+		message: string,
+		placeholder?: string,
+		dialog?: { signal?: AbortSignal; timeout?: number; onTimeout?: () => void },
+	) => Promise<string | undefined>;
+} {
+	const elicit = async (
+		kind: "select" | "confirm" | "input",
+		message: string,
+		options: string[] | undefined,
+		dialog: { signal?: AbortSignal; timeout?: number; onTimeout?: () => void } | undefined,
+	): Promise<unknown> => {
+		if (!capabilities?.elicitation?.form || dialog?.signal?.aborted) return undefined;
+		const request = (
+			connection as unknown as { unstable_createElicitation(input: JsonObject): Promise<JsonObject> }
+		).unstable_createElicitation({
+			sessionId: getSessionId(),
 			message,
 			requestedSchema: {
 				type: "object",
-				properties: { value: property },
+				properties: {
+					value:
+						kind === "confirm" ? { type: "boolean" } : { type: "string", ...(options ? { enum: options } : {}) },
+				},
 				required: ["value"],
 			},
-		})
-		.then(finish, error => {
-			// Caller may already have moved on via abort/timeout; suppress noise.
-			if (settled) return;
-			logger.warn("ACP elicitation failed", { sessionId, method, error });
-			finish(undefined);
 		});
-	const response = await promise;
-	if (
-		response?.action !== "accept" ||
-		typeof response.content !== "object" ||
-		response.content === null ||
-		!("value" in response.content)
-	) {
-		return undefined;
-	}
-	const value = response.content.value;
-	if (
-		typeof value === "string" ||
-		typeof value === "number" ||
-		typeof value === "boolean" ||
-		(Array.isArray(value) && value.every(item => typeof item === "string"))
-	) {
-		return value;
-	}
-	return undefined;
-}
-
-/**
- * Build an {@link ExtensionUIContext} that translates skill/extension UI
- * requests into ACP elicitations against `connection` for the session
- * returned by `getSessionId()`. The id is read lazily at each elicitation
- * because `AgentSession.sessionId` is a getter over `sessionManager` state
- * that mutates when an extension command calls `ctx.newSession` /
- * `ctx.switchSession` — snapshotting it once at factory time would route
- * later elicitations to the pre-switch id. Live reads keep the bridge
- * symmetric with every other `sessionUpdate` call in this file
- * (`record.session.sessionId` is always evaluated at emit time).
- *
- * The non-elicitation surface (custom components, editor, theming,
- * terminal input) remains stubbed — ACP clients render those themselves
- * or not at all. Capability gating respects the client's `initialize`
- * advertisement.
- */
-export function createAcpExtensionUiContext(
-	connection: AgentSideConnection,
-	getSessionId: () => string,
-	clientCapabilities: ClientCapabilities | undefined,
-): ExtensionUIContext {
-	const supportsForm = clientCapabilities?.elicitation?.form != null;
+		let timer: NodeJS.Timeout | undefined;
+		const timeout =
+			dialog?.timeout === undefined
+				? undefined
+				: new Promise<undefined>(resolve => {
+						timer = setTimeout(() => {
+							dialog.onTimeout?.();
+							resolve(undefined);
+						}, dialog.timeout);
+					});
+		try {
+			const response = timeout ? await Promise.race([request, timeout]) : await request;
+			return object(object(response)?.content)?.value;
+		} catch {
+			return undefined;
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	};
 	return {
-		select: async (title, options, dialogOptions) => {
-			if (!supportsForm) return undefined;
-			const value = await elicitFromAcpClient(
-				connection,
-				getSessionId(),
-				"select",
-				title,
-				{ type: "string", enum: options },
-				dialogOptions,
-			);
-			return typeof value === "string" ? value : undefined;
-		},
-		confirm: async (title, message, dialogOptions) => {
-			if (!supportsForm) return false;
-			const value = await elicitFromAcpClient(
-				connection,
-				getSessionId(),
-				"confirm",
-				message.trim().length > 0 ? `${title}\n\n${message}` : title,
-				{ type: "boolean" },
-				dialogOptions,
-			);
-			return typeof value === "boolean" ? value : false;
+		select: async (message, options, dialog) => {
+			const value = await elicit("select", message, options, dialog);
+			return typeof value === "string" && options.includes(value) ? value : undefined;
 		},
-		input: async (title, placeholder, dialogOptions) => {
-			if (!supportsForm) return undefined;
-			const value = await elicitFromAcpClient(
-				connection,
-				getSessionId(),
-				"input",
-				title,
-				// ACP's `StringPropertySchema` has no `placeholder` field, so we
-				// surface the placeholder text as `description` — the closest
-				// semantic field a client can render alongside the input.
-				// Empty / whitespace-only placeholders are treated as absent.
-				{ type: "string", ...(placeholder?.trim() ? { description: placeholder } : {}) },
-				dialogOptions,
-			);
+		confirm: async (message, detail, dialog) =>
+			(await elicit("confirm", detail ? `${message}\n\n${detail}` : message, undefined, dialog)) === true,
+		input: async (message, placeholder, dialog) => {
+			const value = await elicit("input", placeholder ? `${message}\n\n${placeholder}` : message, undefined, dialog);
 			return typeof value === "string" ? value : undefined;
 		},
-		notify: (message, type) => {
-			logger.debug("ACP extension notification", { message, type });
-		},
-		onTerminalInput: () => () => {},
-		setStatus: () => {},
-		setWorkingMessage: () => {},
-		setWidget: () => {},
-		setFooter: () => {},
-		setHeader: () => {},
-		setTitle: () => {},
-		custom: async () => undefined as never,
-		pasteToEditor: () => {},
-		setEditorText: () => {},
-		getEditorText: () => "",
-		editor: async () => undefined,
-		setEditorComponent: () => {},
-		get theme() {
-			return theme;
-		},
-		getAllThemes: async () => [],
-		getTheme: async () => undefined,
-		setTheme: async () => ({ success: false, error: "Theme changes are unavailable in ACP mode" }),
-		getToolsExpanded: () => false,
-		setToolsExpanded: () => {},
 	};
 }
 
+/**
+ * ACP is a pure SDK client. Session processes are created and resumed by the
+ * broker, while all per-session operations use that session's authenticated SDK
+ * endpoint. This class deliberately imports neither AgentSession nor any local
+ * runtime host component.
+ */
 export class AcpAgent implements Agent {
-	#connection: AgentSideConnection;
-	#initialSession: AgentSession | undefined;
-	#createSession: CreateAcpSession;
-	#sessions = new Map<string, ManagedSessionRecord>();
-	#disposePromise: Promise<void> | undefined;
-	#cleanupRegistered = false;
+	readonly #connection: AgentSideConnection;
+	readonly #agentDir: string;
+	readonly #sessions = new Map<string, SessionRecord>();
+	readonly #attaching = new Map<string, PendingAttachment>();
+	readonly #resolvingExisting = new Map<string, PendingAttachment>();
+	readonly #knownSessionCwds = new Map<string, string>();
+	readonly #sessionEpochs = new Map<string, number>();
+	readonly #tearingDown = new Map<string, number>();
 	#clientCapabilities: ClientCapabilities | undefined;
-	#cancelCleanupTimeoutMs = ACP_CANCEL_CLEANUP_TIMEOUT_MS;
-	/** Immutable canonical cwd locked by the first successful explicit-cwd lifecycle/list call. */
-	#canonicalCwdScope: string | undefined;
-	/** Authority snapshot from the last complete strict scoped inventory. Invalidation bumps this. */
-	#authorityGeneration = 0;
-	#authoritySnapshot: AcpAuthoritySnapshot | undefined;
-	/**
-	 * Same-connection retry evidence for an incomplete verified delete. Keyed by
-	 * session id. Phase-aware: every cleanup_pending carries the transcript
-	 * identity at failure time, which is re-verified against the fresh candidate
-	 * on retry so a replaced transcript cannot authorize a replacement; the
-	 * artifacts-phase result additionally carries the artifact directory
-	 * identity to re-accept. Cleared once a delete reaches `kind: "deleted"`.
-	 */
-	#pendingDeleteEvidence = new Map<string, PendingDeleteEvidence>();
-	#shutdownPromise: Promise<void> | undefined;
-	#lifecycleOperations = new Set<Promise<unknown>>();
-	#shuttingDown = false;
+	#broker: Promise<BrokerConnection> | undefined;
+	readonly #startupOptions: AcpStartupOptions | undefined;
+	#disposed = false;
+	#disposePromise: Promise<void> | undefined;
 
-	constructor(connection: AgentSideConnection, createSession: CreateAcpSession, initialSession?: AgentSession) {
+	constructor(
+		connection: AgentSideConnection,
+		options?: { agentDir?: string; startupOptions?: AcpStartupOptions } | unknown,
+	) {
 		this.#connection = connection;
-		this.#initialSession = initialSession;
-		this.#createSession = createSession;
-	}
-
-	setCancelCleanupTimeoutForTesting(timeoutMs: number): void {
-		this.#cancelCleanupTimeoutMs = Math.max(1, timeoutMs);
+		const candidate = object(options);
+		this.#agentDir = typeof candidate?.agentDir === "string" ? candidate.agentDir : getAgentDir();
+		this.#startupOptions = parseAcpStartupOptions(candidate?.startupOptions);
+		queueMicrotask(() => {
+			if (connection.signal.aborted) {
+				this.#beginDispose();
+			} else {
+				connection.signal.addEventListener("abort", () => this.#beginDispose(), { once: true });
+			}
+		});
 	}
 
 	async initialize(params: InitializeRequest): Promise<InitializeResponse> {
-		this.#registerConnectionCleanup();
 		this.#clientCapabilities = params.clientCapabilities;
 		const authMethods: AuthMethod[] = [
 			{
@@ -514,2377 +615,892 @@ export class AcpAgent implements Agent {
 		}
 		return {
 			protocolVersion: PROTOCOL_VERSION,
-			agentInfo: {
-				name: "gajae-code",
-				title: "Gajae Code",
-				version: CODING_AGENT_VERSION,
-			},
+			agentInfo: { name: "gajae-code", title: "Gajae Code", version: packageJson.version },
 			authMethods,
 			agentCapabilities: {
 				loadSession: true,
-				mcpCapabilities: {
-					http: true,
-					sse: true,
-				},
-				promptCapabilities: {
-					embeddedContext: true,
-					image: true,
-				},
-				sessionCapabilities: {
-					list: {},
-					fork: {},
-					resume: {},
-					close: {},
-					delete: {},
-				},
+				promptCapabilities: { embeddedContext: true, image: true },
+				sessionCapabilities: { list: {}, fork: {}, resume: {}, close: {}, delete: {} },
 			},
 		};
 	}
 
 	async authenticate(params: AuthenticateRequest): Promise<AuthenticateResponse> {
-		// ACP spec: `methodId` must be one of the methods advertised by `initialize`.
-		// Reject anything else so malformed clients fail fast rather than appearing
-		// authenticated and surfacing a downstream model failure later.
-		const supportsTerminalAuth = this.#clientCapabilities?.auth?.terminal === true;
-		const validMethods = supportsTerminalAuth ? ["agent", "terminal"] : ["agent"];
-		if (!validMethods.includes(params.methodId)) {
-			throw new Error(`Unknown ACP auth method: ${params.methodId}`);
-		}
+		const methods = this.#clientCapabilities?.auth?.terminal ? ["agent", "terminal"] : ["agent"];
+		if (!methods.includes(params.methodId)) throw new Error(`Unknown ACP auth method: ${params.methodId}`);
 		return {};
 	}
 
 	async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
-		this.#rejectIfShuttingDown();
-		// Stage scope before the lifecycle op; commit only after it succeeds so a
-		// failed first call does not pin the connection to a cwd it never served.
-		const canonical = this.#stageCanonicalScope(params.cwd);
-		const record = await this.#trackLifecycle(() => this.#createNewSessionRecord(params.cwd, params.mcpServers));
-		this.#rejectIfShuttingDown();
-		this.#commitCanonicalScope(canonical);
-		this.#invalidateAuthority();
-		const response: NewSessionResponse = {
-			sessionId: record.session.sessionId,
-			configOptions: this.#buildConfigOptions(record.session),
-			modes: this.#buildModeState(record.session),
-		};
-		this.#scheduleBootstrapUpdates(record.session.sessionId);
-		return response;
-	}
-
-	async loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
-		this.#rejectIfShuttingDown();
-		const canonical = this.#stageCanonicalScope(params.cwd);
-		const existingRecord = this.#sessions.get(params.sessionId);
-		const record = await this.#trackLifecycle(() =>
-			this.#loadManagedSession(params.sessionId, params.cwd, params.mcpServers),
+		this.#assertNoMcpServers(params);
+		this.#assertAbsoluteCwd(params.cwd);
+		const result = await (await this.#brokerAdapter()).global(
+			"session.create",
+			{
+				cwd: params.cwd,
+				target: { path: params.cwd },
+				...(this.#startupOptions?.modelPreset ? { modelPreset: this.#startupOptions.modelPreset } : {}),
+			},
+			randomUUID(),
 		);
+		const id = sessionId(result);
+		this.#knownSessionCwds.set(id, params.cwd);
 		try {
-			this.#rejectIfShuttingDown();
-			await this.#replaySessionHistory(record);
-			this.#rejectIfShuttingDown();
-			// Construct every fallible response/bootstrap value inside the
-			// transaction so a build/schedule failure rolls back the prepared
-			// record and never pins the connection.
-			const response: LoadSessionResponse = {
-				configOptions: this.#buildConfigOptions(record.session),
-				modes: this.#buildModeState(record.session),
-			};
-			this.#scheduleBootstrapUpdates(record.session.sessionId);
-			// Commit the cwd scope only after replay, response construction, and
-			// bootstrap scheduling all succeed — a failed first load leaves no
-			// half-loaded session and does not pin the connection.
-			this.#commitCanonicalScope(canonical);
-			this.#invalidateAuthority();
-			return response;
+			await this.#attach(id, params.cwd, endpoint(result));
+			await applyAcpStartupOptions(this.#adapter(id), this.#startupOptions);
+			this.#scheduleBootstrap(id);
+			return { sessionId: id, ...(await this.#sessionState(id)) };
 		} catch (error) {
-			// Any pre-return failure: roll back the prepared record so a failed
-			// first load leaves no half-loaded session and does not pin the
-			// connection, and commit no cwd scope.
-			if (record !== existingRecord) {
-				this.#sessions.delete(record.session.sessionId);
-				await this.#disposeSessionRecord(record);
-			}
+			await this.#discardNewSession(id);
 			throw error;
 		}
 	}
 
-	async listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse> {
-		this.#rejectIfShuttingDown();
-		const scope = params.cwd ? this.#stageCanonicalScope(params.cwd) : undefined;
-		for (const record of this.#sessions.values()) {
-			await record.session.sessionManager.flush();
-		}
-		this.#rejectIfShuttingDown();
-		// Cwd-less / global listing stays display-only and non-authorizing.
-		if (!scope) {
-			const sessions = await this.#listStoredSessions(undefined);
-			const offset = this.#parseCursor(params.cursor ?? undefined);
-			const paged = sessions.slice(offset, offset + SESSION_PAGE_SIZE);
-			const nextOffset = offset + paged.length;
-			return {
-				sessions: paged.map(session => this.#toSessionInfo(session)),
-				nextCursor: nextOffset < sessions.length ? String(nextOffset) : undefined,
-			};
-		}
-		// Explicit scoped list: stage scope, strict raw inventory, build the full
-		// authorization/conflict snapshot BEFORE page slicing so duplicate ids
-		// beyond page 1 are known before the first page response. Scope commits
-		// only after cursor validation, stored-session read, and full response
-		// construction succeed — a failed first list never pins the connection.
-		if (params.cursor === undefined) {
-			// A new first-page request is a new issuance event. Refresh the complete
-			// snapshot and invalidate cursors minted by the previous issuance.
-			this.#invalidateAuthority();
-		}
-		const snapshot = this.#buildAuthoritySnapshot(scope);
-		// Scoped cursors carry the authority generation at which they were minted
-		// (form `${generation}:${offset}`). A lifecycle change between page 1 and
-		// page 2 bumps the generation, so the old cursor is rejected instead of
-		// silently rebuilding at the new generation. The cwd-less display cursor
-		// stays a plain offset (see #parseCursor).
-		const offset = this.#parseScopedCursor(params.cursor ?? undefined, snapshot.generation);
-		const stored = await this.#listStoredSessions(scope);
-		const storedById = new Map(stored.map(s => [s.id, s] as const));
-		const pageIds = snapshot.orderedIds.slice(offset, offset + SESSION_PAGE_SIZE);
-		const nextOffset = offset + pageIds.length;
-		const pageSessions = pageIds.map(id => storedById.get(id)).filter((s): s is StoredSessionInfo => s !== undefined);
-		const response: ListSessionsResponse = {
-			sessions: pageSessions.map(session => this.#toSessionInfo(session)),
-			nextCursor: nextOffset < snapshot.orderedIds.length ? `${snapshot.generation}:${nextOffset}` : undefined,
-		};
-		// Commit the scope only after cursor validation, stored-session read, and
-		// full response construction succeed.
-		this.#commitCanonicalScope(scope);
-		return response;
+	async loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
+		this.#assertNoMcpServers(params);
+		this.#assertAbsoluteCwd(params.cwd);
+		await this.#attachExisting(params.sessionId, params.cwd);
+		await this.#replaySession(params.sessionId);
+		this.#scheduleBootstrap(params.sessionId);
+		return await this.#sessionState(params.sessionId);
 	}
 
 	async resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse> {
-		this.#rejectIfShuttingDown();
-		const canonical = this.#stageCanonicalScope(params.cwd);
-		const record = await this.#trackLifecycle(() =>
-			this.#resumeManagedSession(params.sessionId, params.cwd, params.mcpServers ?? []),
-		);
-		this.#rejectIfShuttingDown();
-		this.#commitCanonicalScope(canonical);
-		this.#invalidateAuthority();
-		const response: ResumeSessionResponse = {
-			configOptions: this.#buildConfigOptions(record.session),
-			modes: this.#buildModeState(record.session),
-		};
-		this.#scheduleBootstrapUpdates(record.session.sessionId);
-		return response;
+		this.#assertNoMcpServers(params);
+		this.#assertAbsoluteCwd(params.cwd);
+		await this.#attachExisting(params.sessionId, params.cwd);
+		this.#scheduleBootstrap(params.sessionId);
+		return await this.#sessionState(params.sessionId);
 	}
 
 	async unstable_forkSession(params: ForkSessionRequest): Promise<ForkSessionResponse> {
-		this.#rejectIfShuttingDown();
-		const canonical = this.#stageCanonicalScope(params.cwd);
-		const record = await this.#trackLifecycle(() => this.#forkManagedSession(params));
-		this.#rejectIfShuttingDown();
-		this.#commitCanonicalScope(canonical);
-		this.#invalidateAuthority();
-		const response: ForkSessionResponse = {
-			sessionId: record.session.sessionId,
-			configOptions: this.#buildConfigOptions(record.session),
-			modes: this.#buildModeState(record.session),
-		};
-		this.#scheduleBootstrapUpdates(record.session.sessionId);
-		return response;
+		this.#assertNoMcpServers(params);
+		this.#assertAbsoluteCwd(params.cwd);
+		const source = await this.#resolveSavedSession(params.sessionId, params.cwd);
+		const result = await (await this.#brokerAdapter()).global(
+			"session.fork",
+			{
+				cwd: params.cwd,
+				sourceSessionId: params.sessionId,
+				sourceSessionPath: source,
+				target: { path: params.cwd },
+			},
+			randomUUID(),
+		);
+		const id = sessionId(result);
+		this.#knownSessionCwds.set(id, params.cwd);
+		try {
+			await this.#attach(id, params.cwd, endpoint(result));
+			this.#scheduleBootstrap(id);
+			return { sessionId: id, ...(await this.#sessionState(id)) };
+		} catch (error) {
+			await this.#discardNewSession(id);
+			throw error;
+		}
+	}
+
+	async listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse> {
+		if (params.cwd) this.#assertAbsoluteCwd(params.cwd);
+		const result = object(await (await this.#brokerAdapter()).global("session.list"));
+		const listing = object(result?.result) ?? result;
+		const listed = Array.isArray(listing?.sessions) ? listing.sessions : [];
+		if (params.cwd) {
+			const discovered = new Set<string>();
+			for (const session of listed) {
+				const candidate = object(session) as BrokerSession | undefined;
+				if (
+					typeof candidate?.sessionId !== "string" ||
+					typeof candidate.locator?.repo !== "string" ||
+					path.resolve(candidate.locator.repo) !== path.resolve(params.cwd)
+				)
+					continue;
+				if (discovered.has(candidate.sessionId))
+					throw new AcpSdkAdapterError("conflict", `Broker returned duplicate session id: ${candidate.sessionId}`);
+				discovered.add(candidate.sessionId);
+				const knownCwd = this.#knownSessionCwds.get(candidate.sessionId);
+				if (knownCwd && path.resolve(knownCwd) !== path.resolve(params.cwd))
+					throw new AcpSdkAdapterError(
+						"conflict",
+						`ACP session ${candidate.sessionId} has conflicting cwd authority.`,
+					);
+				this.#knownSessionCwds.set(candidate.sessionId, params.cwd);
+			}
+		}
+		return paginateAcpSessions(listed, params.cwd ?? undefined, this.#cursor(params.cursor));
 	}
 
 	async closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse> {
 		const record = this.#sessions.get(params.sessionId);
-		if (!record) {
+		const cwd = record?.cwd ?? this.#knownSessionCwds.get(params.sessionId);
+		// ACP close has no cwd. Only connection-owned sessions may reach broker lifecycle control.
+		if (!cwd) return {};
+		this.#beginTeardown(params.sessionId);
+		try {
+			await this.#teardownSession(params.sessionId, "closed", true);
+			this.#knownSessionCwds.delete(params.sessionId);
 			return {};
+		} finally {
+			this.#finishTeardown(params.sessionId);
 		}
-		this.#rejectIfTerminal(record);
-		await this.#closeManagedSession(params.sessionId, record);
-		this.#invalidateAuthority();
-		return {};
 	}
 
-	/**
-	 * Hard delete an ACP session. `DeleteSessionRequest` carries only `sessionId`;
-	 * the server owns authorization through the immutable canonical cwd scope and
-	 * the complete strict scoped inventory snapshot.
-	 *
-	 * - No scope / unknown / already-deleted id → lookup-free `{}`.
-	 * - Duplicate/conflict id → visible error; neither transcript nor artifacts change.
-	 * - Active session → reserve `deleting`, drain/cancel prompt, flush, strict
-	 *   dispose/close, recheck identity/state, then verified artifact-first deletion.
-	 * - Concurrent delete callers join the terminal promise.
-	 */
 	async deleteSession(params: DeleteSessionRequest): Promise<DeleteSessionResponse> {
-		// Before scope: return {} without scanning/listing storage.
-		if (this.#canonicalCwdScope === undefined) {
-			return {};
-		}
-		if (this.#shuttingDown) {
-			throw new Error("ACP session delete is unavailable during shutdown");
-		}
 		const record = this.#sessions.get(params.sessionId);
-		if (record) {
-			return await this.#deleteActiveSession(params.sessionId, record);
+		const cwd = record?.cwd ?? this.#knownSessionCwds.get(params.sessionId);
+		// ACP's delete request has no cwd. Only delete sessions this connection has
+		// already scoped through the broker; unknown ids remain the protocol no-op.
+		if (!cwd) return {};
+		this.#beginTeardown(params.sessionId);
+		try {
+			await this.#teardownSession(params.sessionId, "deleted", true);
+			let saved: string;
+			try {
+				saved = await this.#resolveSavedSession(params.sessionId, cwd);
+			} catch (error) {
+				if (error instanceof AcpSdkAdapterError && error.code === "not_found") {
+					this.#knownSessionCwds.delete(params.sessionId);
+					return {};
+				}
+				throw error;
+			}
+			await (await this.#brokerAdapter()).global(
+				"session.delete",
+				{ sessionId: params.sessionId, sessionPath: saved, cwd, target: { path: cwd } },
+				this.#lifecycleIdempotencyKey(params.sessionId, "session.delete"),
+			);
+			this.#knownSessionCwds.delete(params.sessionId);
+			return {};
+		} finally {
+			this.#finishTeardown(params.sessionId);
 		}
-		// Inactive: read authority from the strict inventory snapshot.
-		return await this.#deleteInactiveSession(params.sessionId);
 	}
 
 	async setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse> {
-		const record = this.#getSessionRecord(params.sessionId);
-		this.#rejectIfTerminal(record);
-		this.#applyModeChange(record.session, params.modeId);
-		await this.#connection.sessionUpdate({
-			sessionId: record.session.sessionId,
-			update: this.#buildCurrentModeUpdate(record.session),
+		if (params.modeId !== ACP_DEFAULT_MODE_ID && params.modeId !== ACP_PLAN_MODE_ID)
+			throw new Error(`Unsupported ACP mode: ${params.modeId}`);
+		await this.#adapter(params.sessionId).control("mode.plan.set", { on: params.modeId === ACP_PLAN_MODE_ID });
+		await this.#publishSessionUpdate(params.sessionId, {
+			sessionId: params.sessionId,
+			update: { sessionUpdate: "current_mode_update", currentModeId: params.modeId },
 		});
-		await this.#pushConfigOptionUpdate(record);
 		return {};
 	}
 
 	async setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse> {
-		const record = this.#getSessionRecord(params.sessionId);
-		this.#rejectIfTerminal(record);
-		if (typeof params.value === "boolean") {
+		if (typeof params.value !== "string")
 			throw new Error(`Unsupported boolean ACP config option: ${params.configId}`);
-		}
-
 		switch (params.configId) {
 			case MODE_CONFIG_ID:
-				this.#applyModeChange(record.session, params.value);
+				await this.setSessionMode({ sessionId: params.sessionId, modeId: params.value });
 				break;
 			case MODEL_CONFIG_ID:
-				await this.#setModelById(record.session, params.value);
+				await this.#adapter(params.sessionId).setModel(params.value);
 				break;
 			case THINKING_CONFIG_ID:
-				this.#setThinkingLevelById(record.session, params.value);
+				await this.#adapter(params.sessionId).control("thinking.set", { level: params.value });
 				break;
-			default:
-				throw new Error(`Unknown ACP config option: ${params.configId}`);
+			default: {
+				const operation = ACP_CONFIG_CONTROL_OPERATIONS[params.configId];
+				if (!operation) throw new Error(`Unknown ACP config option: ${params.configId}`);
+				await this.#adapter(params.sessionId).control(operation, { mode: params.value });
+			}
 		}
+		const state = await this.#sessionState(params.sessionId);
+		await this.#publishSessionUpdate(params.sessionId, {
+			sessionId: params.sessionId,
+			update: { sessionUpdate: "config_option_update", configOptions: state.configOptions ?? [] },
+		});
+		return { configOptions: state.configOptions ?? [] };
+	}
 
-		// When mode is changed via the generic config-option API, mirror the
-		// `current_mode_update` notification that `setSessionMode` emits so
-		// ACP clients tracking session-mode state see a consistent transition.
-		if (params.configId === MODE_CONFIG_ID) {
-			await this.#connection.sessionUpdate({
-				sessionId: record.session.sessionId,
-				update: this.#buildCurrentModeUpdate(record.session),
+	async prompt(params: PromptRequest): Promise<PromptResponse> {
+		const record = this.#sessions.get(params.sessionId);
+		if (!record) throw new AcpSdkAdapterError("not_found", `Unsupported ACP session: ${params.sessionId}`);
+		if (record.activePrompt) throw new AcpSdkAdapterError("conflict", "ACP session already has an active prompt.");
+		const payload = acpPromptPayload(params.prompt);
+		let waiter!: PromptWaiter;
+		const response = new Promise<PromptResponse>((resolve, reject) => {
+			waiter = {
+				cancelRequested: false,
+				acknowledged: false,
+				activityObserved: false,
+				steeringAtAcknowledgement: record.busy,
+				boundary: record.inboundSequence,
+				correlation: {},
+				resolve,
+				reject,
+			};
+			record.activePrompt = waiter;
+		});
+		try {
+			const acknowledgement = await record.adapter.prompt({
+				text: payload.text,
+				...(payload.images.length ? { images: payload.images } : {}),
 			});
+			waiter.steeringAtAcknowledgement = record.busy;
+			// Capture the ingress boundary after the command acknowledgement. Frames
+			// queued before this point are stale with respect to this ACP prompt.
+			waiter.boundary = record.inboundSequence;
+			waiter.correlation = correlationFrom(acknowledgement);
+			waiter.acknowledged = true;
+			this.#settlePrompt(record, waiter);
+		} catch (error) {
+			if (record.activePrompt === waiter) record.activePrompt = undefined;
+			throw error;
 		}
+		return await response;
+	}
 
-		// For `thinking` the lifetime subscription pushes post-bootstrap; only
-		// push here when it's not yet installed so pre-bootstrap callers still
-		// see the change without a post-bootstrap duplicate.
-		const thinkingHandledBySubscription =
-			params.configId === THINKING_CONFIG_ID && record.lifetimeUnsubscribe !== undefined;
-		if (!thinkingHandledBySubscription) {
-			await this.#pushConfigOptionUpdate(record);
-		}
-		return { configOptions: this.#buildConfigOptions(record.session) };
+	async cancel(params: { sessionId: string }): Promise<void> {
+		const record = this.#sessions.get(params.sessionId);
+		if (!record) throw new AcpSdkAdapterError("not_found", `Unsupported ACP session: ${params.sessionId}`);
+		const waiter = record.activePrompt;
+		const acknowledgement = await record.adapter.cancel();
+		const result = object(object(acknowledgement)?.result) ?? object(acknowledgement);
+		if (result?.aborted !== true)
+			throw new AcpSdkAdapterError(
+				"abort_unacknowledged",
+				"SDK did not acknowledge cancellation of the active prompt.",
+			);
+		// Do not retroactively mark a waiter that already settled while the abort
+		// request was in flight. A cancelled response means the abort itself won.
+		if (waiter && record.activePrompt === waiter) waiter.cancelRequested = true;
 	}
 
-	async prompt(params: PromptRequest): Promise<PromptResponse> {
-		const record = this.#getSessionRecord(params.sessionId);
-		this.#rejectIfTerminal(record);
-		const activeTurn = record.promptTurn;
-		if (activeTurn && !activeTurn.settled && record.session.isStreaming) {
-			throw new Error("ACP prompt already in progress for this session");
-		}
-		return await this.#queuePrompt(record, async () => {
-			const previousTurn = record.promptTurn;
-			if (previousTurn) {
-				// Wait for any prompt that's still settling or whose cancel cleanup is
-				// still in flight. We deliberately swallow the prompt rejection (the
-				// owning caller already received it) but let cleanup rejections
-				// propagate — a timed-out cancel must fail this queued prompt instead
-				// of letting it run on a session that is about to be closed.
-				await previousTurn.promise.catch(() => undefined);
-				await previousTurn.cleanup;
+	async extMethod(method: string, params: JsonObject): Promise<JsonObject> {
+		try {
+			if (method === "_gjc/sdk/global") {
+				const result = await (await this.#brokerAdapter()).handle(method, params);
+				return object(result) ?? {};
+			}
+			if (method === "_gjc/sdk/control" || method === "_gjc/sdk/query") {
+				const id = typeof params.sessionId === "string" ? params.sessionId : undefined;
+				if (!id) throw new AcpSdkAdapterError("invalid_input", "sessionId is required.");
+				const result = await this.#adapter(id).handle(method, params);
+				return object(result) ?? {};
 			}
+			throw new AcpSdkAdapterError("method_not_found", `Unknown ACP ext method: ${method}`);
+		} catch (error) {
+			const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "internal";
+			const message = error instanceof Error ? error.message : String(error);
+			return { ok: false, error: { code, message } };
+		}
+	}
 
-			const converted = this.#convertPromptBlocks(params.prompt);
-			const pendingPrompt = Promise.withResolvers<PromptResponse>();
-			const metaUserMessageId = params._meta?.userMessageId;
-			record.promptTurn = {
-				userMessageId: typeof metaUserMessageId === "string" ? metaUserMessageId : crypto.randomUUID(),
-				cancelRequested: false,
-				settled: false,
-				cleanup: undefined,
-				usageBaseline: this.#cloneUsageStatistics(record.session.sessionManager.getUsageStatistics()),
-				unsubscribe: undefined,
-				resolve: pendingPrompt.resolve,
-				reject: pendingPrompt.reject,
-				promise: pendingPrompt.promise,
-			};
+	async extNotification(_method: string, _params: JsonObject): Promise<void> {}
+	get signal(): AbortSignal {
+		return this.#connection.signal;
+	}
+	get closed(): Promise<void> {
+		return this.#connection.closed;
+	}
 
-			this.#ensureLifetimeSubscription(record);
-			record.promptTurn.unsubscribe = record.session.subscribe(event => {
-				void this.#handlePromptEvent(record, event);
-			});
+	#sessionEpoch(id: string): number {
+		return this.#sessionEpochs.get(id) ?? 0;
+	}
 
-			this.#runPromptOrCommand(record, converted.text, converted.images).catch((error: unknown) => {
-				this.#finishPrompt(record, undefined, error);
-			});
+	#advanceSessionEpoch(id: string): void {
+		this.#sessionEpochs.set(id, this.#sessionEpoch(id) + 1);
+	}
 
-			return await pendingPrompt.promise;
-		});
+	#assertSessionEpoch(id: string, epoch: number): void {
+		if (this.#disposed || this.#tearingDown.has(id) || this.#sessionEpoch(id) !== epoch)
+			throw new AcpSdkAdapterError("connection_closed", `ACP session ${id} was closed while attaching.`);
 	}
 
-	async #queuePrompt(record: ManagedSessionRecord, run: () => Promise<PromptResponse>): Promise<PromptResponse> {
-		const nextQueue = Promise.withResolvers<void>();
-		const releaseQueue = nextQueue.resolve;
-		const previousQueue = record.promptQueue;
-		record.promptQueue = {
-			promise: nextQueue.promise,
-			release: releaseQueue,
-		};
-		await previousQueue.promise;
+	#beginTeardown(id: string): void {
+		this.#tearingDown.set(id, (this.#tearingDown.get(id) ?? 0) + 1);
+	}
+
+	#finishTeardown(id: string): void {
+		const remaining = (this.#tearingDown.get(id) ?? 1) - 1;
+		if (remaining > 0) this.#tearingDown.set(id, remaining);
+		else this.#tearingDown.delete(id);
+	}
+
+	#lifecycleIdempotencyKey(id: string, operation: "session.close" | "session.delete"): string {
+		return `acp:${operation}:${id}`;
+	}
+
+	#isAlreadyGone(error: unknown): boolean {
+		return (
+			typeof error === "object" &&
+			error !== null &&
+			"code" in error &&
+			((error.code === "not_found" || error.code === "resource_gone") as boolean)
+		);
+	}
+
+	async #attachExisting(id: string, cwd: string): Promise<void> {
+		const epoch = this.#sessionEpoch(id);
+		const attached = this.#sessions.get(id);
+		if (attached) {
+			if (path.resolve(attached.cwd) !== path.resolve(cwd))
+				throw new AcpSdkAdapterError("conflict", `ACP session ${id} has conflicting cwd authority.`);
+			return;
+		}
+		const knownCwd = this.#knownSessionCwds.get(id);
+		if (knownCwd && path.resolve(knownCwd) !== path.resolve(cwd))
+			throw new AcpSdkAdapterError("conflict", `ACP session ${id} has conflicting cwd authority.`);
+		const resolving = this.#resolvingExisting.get(id);
+		if (resolving?.epoch === epoch) {
+			await resolving.task;
+			this.#assertSessionEpoch(id, epoch);
+			const resolved = this.#sessions.get(id);
+			if (!resolved) throw new AcpSdkAdapterError("unavailable", `ACP session ${id} did not attach.`);
+			if (path.resolve(resolved.cwd) !== path.resolve(cwd))
+				throw new AcpSdkAdapterError("conflict", `ACP session ${id} has conflicting cwd authority.`);
+			return;
+		}
+
+		const task = this.#resolveExistingAttachment(id, cwd, epoch);
+		const pending = { epoch, task };
+		this.#resolvingExisting.set(id, pending);
 		try {
-			return await run();
+			await task;
+			this.#assertSessionEpoch(id, epoch);
 		} finally {
-			releaseQueue();
-			if (record.promptQueue.release === releaseQueue) {
-				record.promptQueue.release = undefined;
-			}
+			if (this.#resolvingExisting.get(id) === pending) this.#resolvingExisting.delete(id);
 		}
 	}
 
-	async #runPromptOrCommand(record: ManagedSessionRecord, text: string, images: AgentImageContent[]): Promise<void> {
-		// Namespaced skill commands cannot collide with ACP builtins; handle
-		// them before builtin dispatch. Bare `/name` aliases are intentionally
-		// not skill commands.
-		if (text.startsWith("/skill:") && (await this.#tryRunSkillCommand(record, text))) {
+	async #resolveExistingAttachment(id: string, cwd: string, epoch: number): Promise<void> {
+		this.#assertSessionEpoch(id, epoch);
+		const indexed = await this.#scopedBrokerSession(id, cwd);
+		this.#assertSessionEpoch(id, epoch);
+		if (indexed?.live) {
+			const result = await this.#brokerEndpoint(id, indexed.endpointGeneration);
+			this.#assertSessionEpoch(id, epoch);
+			await this.#attach(id, cwd, endpoint(result), epoch);
 			return;
 		}
 
-		const builtinResult = await executeAcpBuiltinSlashCommand(text, {
-			session: record.session,
-			sessionManager: record.session.sessionManager,
-			settings: record.session.settings,
-			cwd: record.session.sessionManager.getCwd(),
-			output: output => this.#emitCommandOutput(record, output),
-			refreshCommands: () => this.#emitAvailableCommandsUpdate(record),
-			reloadPlugins: () => this.#reloadPluginState(record),
-			notifyTitleChanged: async () => {
-				await this.#connection.sessionUpdate({
-					sessionId: record.session.sessionId,
-					update: {
-						sessionUpdate: "session_info_update",
-						title: record.session.sessionName,
-						updatedAt: new Date().toISOString(),
-					},
-				});
-			},
-			notifyConfigChanged: async () => {
-				await this.#pushConfigOptionUpdate(record);
-			},
-		});
-		if (builtinResult !== false) {
-			if ("prompt" in builtinResult) {
-				await record.session.prompt(builtinResult.prompt, { images });
-				return;
-			}
-			const promptTurn = record.promptTurn;
-			this.#finishPrompt(record, {
-				stopReason: "end_turn",
-				usage: this.#buildTurnUsage(
-					promptTurn?.usageBaseline ??
-						this.#cloneUsageStatistics(record.session.sessionManager.getUsageStatistics()),
-					record.session.sessionManager.getUsageStatistics(),
-				),
-				_meta: promptTurn ? { userMessageId: promptTurn.userMessageId } : undefined,
-			});
-			return;
-		}
-
-		if (await this.#tryRunSkillCommand(record, text, { directAliasMayCollide: false })) {
-			return;
-		}
-
-		await record.session.prompt(text, { images });
-	}
-
-	async #tryRunSkillCommand(
-		record: ManagedSessionRecord,
-		text: string,
-		options: { directAliasMayCollide?: boolean } = {},
-	): Promise<boolean> {
-		if (!record.session.skillsSettings?.enableSkillCommands) {
-			return false;
-		}
-		const skillsByCommandName = new Map(
-			record.session.skills
-				.filter(skill => skill.hide !== true)
-				.flatMap(skill => getSkillSlashCommandNames(skill).map(commandName => [commandName, skill] as const)),
+		const saved = await this.#resolveSavedSession(id, cwd);
+		this.#assertSessionEpoch(id, epoch);
+		const result = await (await this.#brokerAdapter()).global(
+			"session.resume",
+			{ cwd, sessionId: id, sessionPath: saved, target: { path: cwd } },
+			randomUUID(),
 		);
-		const invocations = parseSkillInvocations(text, skillsByCommandName);
-		if (invocations.length > 0) {
-			for (let index = 0; index < invocations.length; index += 1) {
-				const invocation = invocations[index];
-				if (!invocation) continue;
-				const activationResult = await resolveSubskillActivationForSkillInvocation({
-					cwd: record.session.sessionManager.getCwd(),
-					sessionId: record.session.sessionId,
-					skillName: invocation.skill.name,
-					args: invocation.args,
-				});
-				const built = await buildSkillPromptMessage(invocation.skill, activationResult.cleanedArgs, {
-					subskillActivation: activationResult.activation,
-					subskillActivationSet: activationResult.activeSubskillsToPersist,
-					cwd: record.session.sessionManager.getCwd(),
-					sessionId: record.session.sessionId,
-				});
-				if (index === invocations.length - 1) {
-					await record.session.promptCustomMessage({
-						customType: SKILL_PROMPT_MESSAGE_TYPE,
-						content: built.message,
-						display: true,
-						details: built.details,
-						attribution: "user",
-					});
-				} else {
-					await record.session.sendCustomMessage({
-						customType: SKILL_PROMPT_MESSAGE_TYPE,
-						content: built.message,
-						display: true,
-						details: built.details,
-						attribution: "user",
-					});
-				}
-			}
-			return true;
-		}
-		const slashText = text.trimStart();
-		if (!slashText.startsWith("/")) {
-			return false;
-		}
-		const spaceIndex = slashText.indexOf(" ");
-		const commandName = spaceIndex === -1 ? slashText.slice(1) : slashText.slice(1, spaceIndex);
-		const args = spaceIndex === -1 ? "" : slashText.slice(spaceIndex + 1).trim();
-		if (
-			!isNamespacedSkillSlashCommandName(commandName) &&
-			options.directAliasMayCollide !== true &&
-			(await this.#directSkillAliasCollides(record, commandName))
-		) {
-			return false;
-		}
-		const skill = record.session.skills.find(candidate => isSkillSlashCommandName(commandName, candidate));
-		if (!skill || skill.hide === true) {
-			return false;
-		}
-		const activationResult = await resolveSubskillActivationForSkillInvocation({
-			cwd: record.session.sessionManager.getCwd(),
-			sessionId: record.session.sessionId,
-			skillName: skill.name,
-			args,
-		});
-		const built = await buildSkillPromptMessage(skill, activationResult.cleanedArgs, {
-			subskillActivation: activationResult.activation,
-			subskillActivationSet: activationResult.activeSubskillsToPersist,
-			cwd: record.session.sessionManager.getCwd(),
-			sessionId: record.session.sessionId,
-		});
-		await record.session.promptCustomMessage({
-			customType: SKILL_PROMPT_MESSAGE_TYPE,
-			content: built.message,
-			display: true,
-			details: built.details,
-			attribution: "user",
-		});
-		return true;
+		this.#assertSessionEpoch(id, epoch);
+		await this.#attach(id, cwd, endpoint(result), epoch);
 	}
 
-	async #directSkillAliasCollides(record: ManagedSessionRecord, commandName: string): Promise<boolean> {
-		if (record.session.customCommands.some(command => command.command.name === commandName)) {
-			return true;
+	async #scopedBrokerSession(id: string, cwd: string): Promise<BrokerSession | undefined> {
+		const response = object(await (await this.#brokerAdapter()).global("session.list", { cwd }));
+		const result = object(response?.result) ?? response;
+		const matches: BrokerSession[] = [];
+		for (const item of Array.isArray(result?.sessions) ? result.sessions : []) {
+			const session = object(item) as BrokerSession | undefined;
+			if (session?.sessionId !== id) continue;
+			if (typeof session.locator?.repo !== "string" || path.resolve(session.locator.repo) !== path.resolve(cwd))
+				throw new AcpSdkAdapterError("conflict", `Broker returned conflicting session scope for ${id}.`);
+			matches.push(session);
 		}
-		const fileCommands = await loadSlashCommands({ cwd: record.session.sessionManager.getCwd() });
-		return fileCommands.some(command => command.name === commandName);
+		if (matches.length > 1) throw new AcpSdkAdapterError("conflict", `Broker returned duplicate session id: ${id}`);
+		return matches[0];
 	}
 
-	async cancel(params: { sessionId: string }): Promise<void> {
-		const record = this.#getSessionRecord(params.sessionId);
-		const promptTurn = record.promptTurn;
-		if (!promptTurn || promptTurn.settled) {
+	async #attach(id: string, cwd: string, discovered: Endpoint, epoch = this.#sessionEpoch(id)): Promise<void> {
+		this.#assertSessionEpoch(id, epoch);
+		const existing = this.#sessions.get(id);
+		if (existing) {
+			if (path.resolve(existing.cwd) !== path.resolve(cwd))
+				throw new AcpSdkAdapterError("conflict", `ACP session ${id} has conflicting cwd authority.`);
 			return;
 		}
-		const cleanup = this.#beginCancelCleanup(record, promptTurn);
-		try {
-			await cleanup;
-		} catch (error: unknown) {
-			// A terminal delete owns the record; let the delete handle the failure
-			// rather than racing it with an independent close.
-			if (record.terminalState !== "active") {
-				return;
-			}
-			logger.warn("ACP cancel cleanup timed out; closing session", { sessionId: record.session.sessionId, error });
-			await this.#closeManagedSession(record.session.sessionId, record);
-		}
-	}
-
-	/**
-	 * Transition a still-running turn into cancellation: mark intent, drop the live-event
-	 * subscription, start the bounded `abort()` race, and resolve the ACP prompt response
-	 * with `stopReason: "cancelled"` so the client sees acceptance immediately. The
-	 * returned promise is the cleanup barrier — it resolves when `abort()` completes and
-	 * rejects when the timeout fires. Idempotent: a second call returns the same barrier.
-	 */
-	#beginCancelCleanup(record: ManagedSessionRecord, promptTurn: PromptTurnState): Promise<void> {
-		if (promptTurn.cleanup) {
-			return promptTurn.cleanup;
-		}
-		promptTurn.cancelRequested = true;
-		promptTurn.unsubscribe?.();
-		void this.#emitCancelledPromptIdleUpdate(record);
-		const cleanup = this.#runCancelCleanup(record, promptTurn);
-		promptTurn.cleanup = cleanup;
-		this.#finishPrompt(record, {
-			stopReason: "cancelled",
-			usage: this.#buildTurnUsage(promptTurn.usageBaseline, record.session.sessionManager.getUsageStatistics()),
-			_meta: { userMessageId: promptTurn.userMessageId },
-		});
-		return cleanup;
-	}
-
-	async #runCancelCleanup(record: ManagedSessionRecord, promptTurn: PromptTurnState): Promise<void> {
-		let timer: NodeJS.Timeout | undefined;
-		const timeout = new Promise<never>((_, reject) => {
-			timer = setTimeout(() => reject(new Error("ACP cancel cleanup timed out")), this.#cancelCleanupTimeoutMs);
-		});
-		try {
-			await Promise.race([record.session.abort(), timeout]);
-		} finally {
-			if (timer) clearTimeout(timer);
-			// Order matters: clear `cleanup` before evicting the slot so the slot-eviction
-			// branch matches what `#finishPrompt` saw if it ran first.
-			promptTurn.cleanup = undefined;
-			if (promptTurn.settled && record.promptTurn === promptTurn) {
-				record.promptTurn = undefined;
-			}
-		}
-	}
-
-	async extMethod(method: string, params: { [key: string]: unknown }): Promise<{ [key: string]: unknown }> {
-		switch (method) {
-			case "_gjc/sessions/listAll": {
-				const limit = typeof params.limit === "number" ? Math.max(1, Math.min(5000, params.limit as number)) : 1000;
-				const sessions = await SessionManager.listAll();
-				const sorted = sessions.sort((l, r) => r.modified.getTime() - l.modified.getTime()).slice(0, limit);
-				return {
-					sessions: sorted.map(s => this.#toSessionInfo(s)),
-					total: sessions.length,
-				};
-			}
-			case "_gjc/projects/list": {
-				const sessions = await SessionManager.listAll();
-				const buckets = new Map<
-					string,
-					{ cwd: string; sessionCount: number; lastActivityAt: number; lastTitle: string }
-				>();
-				for (const s of sessions) {
-					if (!s.cwd) continue;
-					const ts = s.modified.getTime();
-					const existing = buckets.get(s.cwd);
-					if (existing) {
-						existing.sessionCount += 1;
-						if (ts > existing.lastActivityAt) {
-							existing.lastActivityAt = ts;
-							existing.lastTitle = s.title ?? "";
-						}
-					} else {
-						buckets.set(s.cwd, {
-							cwd: s.cwd,
-							sessionCount: 1,
-							lastActivityAt: ts,
-							lastTitle: s.title ?? "",
-						});
-					}
-				}
-				const projects = Array.from(buckets.values()).sort((a, b) => b.lastActivityAt - a.lastActivityAt);
-				return { projects, totalSessions: sessions.length };
-			}
-			case "_gjc/chats/byCwd": {
-				const cwd = typeof params.cwd === "string" ? (params.cwd as string) : undefined;
-				if (!cwd) throw new Error("cwd required");
-				const limit = typeof params.limit === "number" ? Math.max(1, Math.min(500, params.limit as number)) : 100;
-				const sessions = await SessionManager.list(cwd);
-				const sorted = sessions.sort((l, r) => r.modified.getTime() - l.modified.getTime()).slice(0, limit);
-				return { sessions: sorted.map(s => this.#toSessionInfo(s)) };
-			}
-			case "_gjc/usage": {
-				const [firstRecord] = this.#sessions.values();
-				const target = firstRecord?.session ?? this.#initialSession;
-				if (!target) {
-					return { reports: [] };
-				}
-				const reports = await target.fetchUsageReports();
-				return { reports: reports ?? [] };
-			}
-			case "_gjc/extensions": {
-				const cwd = typeof params.cwd === "string" ? (params.cwd as string) : undefined;
-				const sm = await Settings.init();
-				const disabledIds = (sm.get("disabledExtensions") as string[] | undefined) ?? [];
-				const extensions = await loadAllExtensions(cwd, disabledIds);
-				return { extensions: extensions as unknown as Array<{ [key: string]: unknown }> };
-			}
-			case "_gjc/extensions/toggle": {
-				const providerId = params.providerId;
-				if (typeof providerId !== "string") throw new Error("providerId required");
-				if (params.enabled === false) {
-					disableProvider(providerId);
-					return { enabled: false };
-				}
-				enableProvider(providerId);
-				return { enabled: true };
-			}
-			default:
-				throw new Error(`Unknown ACP ext method: ${method}`);
-		}
-	}
-
-	async extNotification(_method: string, _params: { [key: string]: unknown }): Promise<void> {}
-
-	get signal(): AbortSignal {
-		return this.#connection.signal;
-	}
-
-	get closed(): Promise<void> {
-		return this.#connection.closed;
-	}
-
-	#registerConnectionCleanup(): void {
-		if (this.#cleanupRegistered) {
+		const attaching = this.#attaching.get(id);
+		if (attaching?.epoch === epoch) {
+			await attaching.task;
+			this.#assertSessionEpoch(id, epoch);
+			const attached = this.#sessions.get(id);
+			if (!attached) throw new AcpSdkAdapterError("unavailable", `ACP session ${id} did not attach.`);
+			if (path.resolve(attached.cwd) !== path.resolve(cwd))
+				throw new AcpSdkAdapterError("conflict", `ACP session ${id} has conflicting cwd authority.`);
 			return;
 		}
-		this.#cleanupRegistered = true;
-		this.#connection.signal.addEventListener(
-			"abort",
-			() => {
-				this.#shuttingDown = true;
-				// Mark shutdown under mutex (no actual mutex needed — single-threaded),
-				// reject new scope/inventory/lifecycle work, then await terminal work.
-				this.#shutdownPromise = (async () => {
-					// Join lifecycle preparation that has not registered yet. Each tracked
-					// operation rechecks shutdown and disposes its prepared session before settling.
-					await Promise.allSettled(Array.from(this.#lifecycleOperations));
-					const terminalPromises = Array.from(this.#sessions.values())
-						.map(r => r.terminalPromise)
-						.filter((p): p is Promise<DeleteSessionResponse> => p !== undefined);
-					await Promise.allSettled(terminalPromises);
-					await this.#disposeAllSessions();
-					// Clear connection-local authority.
-					this.#authoritySnapshot = undefined;
-					this.#canonicalCwdScope = undefined;
-				})();
-			},
-			{ once: true },
-		);
-	}
-
-	/**
-	 * Connection-local shutdown promise. Resolves once all terminal work (dispose,
-	 * active deletes, abort cleanup) has settled. `acp-mode.ts` awaits this after
-	 * transport closure so `process.exit` never kills in-flight deletion/disposal.
-	 */
-	get shutdownPromise(): Promise<void> {
-		return this.#shutdownPromise ?? Promise.resolve();
-	}
 
-	async #trackLifecycle<T>(operation: () => Promise<T>): Promise<T> {
-		this.#rejectIfShuttingDown();
-		const start = Promise.withResolvers<void>();
-		const promise = start.promise.then(operation);
-		this.#lifecycleOperations.add(promise);
-		start.resolve();
+		const task = this.#attachEndpoint(id, cwd, discovered, epoch);
+		const pending = { epoch, task };
+		this.#attaching.set(id, pending);
 		try {
-			return await promise;
+			await task;
+			this.#assertSessionEpoch(id, epoch);
 		} finally {
-			this.#lifecycleOperations.delete(promise);
+			if (this.#attaching.get(id) === pending) this.#attaching.delete(id);
 		}
 	}
 
-	async #createNewSessionRecord(cwd: string, mcpServers: McpServer[]): Promise<ManagedSessionRecord> {
-		const session = await this.#createSession(path.resolve(cwd));
+	async #attachEndpoint(id: string, cwd: string, discovered: Endpoint, epoch: number): Promise<void> {
+		let adapter: AcpSdkAdapter | undefined;
 		try {
-			await session.sessionManager.ensureOnDisk();
+			adapter = await AcpSdkAdapter.connect({
+				url: discovered.url,
+				token: discovered.token,
+				connection: this.#reverseConnection(id),
+				providers: this.#providers(),
+			});
+			this.#assertSessionEpoch(id, epoch);
+			const record: SessionRecord = {
+				cwd,
+				adapter,
+				unsubscribe: () => {},
+				reconnectUnsubscribe: () => {},
+				frameTail: Promise.resolve(),
+				inboundSequence: 0,
+				busy: false,
+			};
+			record.unsubscribe = adapter.onFrame(frame => this.#enqueueSdkFrame(id, adapter!, frame));
+			record.reconnectUnsubscribe = adapter.onReconnectFailed(error =>
+				this.#recoverSessionAfterTransportFailure(id, adapter!, error),
+			);
+			this.#sessions.set(id, record);
+			this.#knownSessionCwds.set(id, cwd);
+			await applyAcpPermissionMode(adapter, this.#clientCapabilities);
+			this.#assertSessionEpoch(id, epoch);
 		} catch (error) {
-			await this.#disposeStandaloneSession(session);
+			if (adapter && this.#sessions.get(id)?.adapter === adapter) {
+				try {
+					await this.#teardownSession(id, "attachment failed", false);
+				} finally {
+					this.#knownSessionCwds.delete(id);
+				}
+			} else if (adapter) {
+				try {
+					await adapter.close();
+				} catch {}
+			}
 			throw error;
 		}
-		return await this.#registerPreparedSession(session, mcpServers);
 	}
 
-	async #loadManagedSession(sessionId: string, cwd: string, mcpServers: McpServer[]): Promise<ManagedSessionRecord> {
-		const existing = this.#sessions.get(sessionId);
-		if (existing) {
-			this.#rejectIfTerminal(existing);
-			this.#assertMatchingCwd(existing.session, cwd);
-			await this.#configureMcpServers(existing, mcpServers);
-			return existing;
-		}
-
-		const candidate = this.#resolveStrictLifecycleCandidate(sessionId, cwd);
-		return await this.#openStoredSession(candidate, cwd, mcpServers, sessionId);
+	#recoverSessionAfterTransportFailure(id: string, adapter: AcpSdkAdapter, error: Error): void {
+		const record = this.#sessions.get(id);
+		if (!record || record.adapter !== adapter) return;
+		const detail = error.message || "SDK transport reconnect failed.";
+		const terminal = new AcpSdkAdapterError("connection_closed", `ACP session transport was lost: ${detail}`);
+		void this.#recoverSessionAfterTransportFailureAsync(id, adapter, record.cwd, terminal);
 	}
 
-	async #resumeManagedSession(sessionId: string, cwd: string, mcpServers: McpServer[]): Promise<ManagedSessionRecord> {
-		const existing = this.#sessions.get(sessionId);
-		if (existing) {
-			this.#rejectIfTerminal(existing);
-			this.#assertMatchingCwd(existing.session, cwd);
-			await this.#configureMcpServers(existing, mcpServers);
-			return existing;
+	async #recoverSessionAfterTransportFailureAsync(
+		id: string,
+		adapter: AcpSdkAdapter,
+		cwd: string,
+		error: AcpSdkAdapterError,
+	): Promise<void> {
+		await this.#failSession(id, adapter, error);
+		if (this.#disposed || this.#knownSessionCwds.get(id) !== cwd) return;
+		try {
+			await this.#attachExisting(id, cwd);
+		} catch {
+			// The affected prompt was rejected and the stale adapter was removed. A later load/resume retries discovery.
 		}
+	}
 
-		const candidate = this.#resolveStrictLifecycleCandidate(sessionId, cwd);
-		return await this.#openStoredSession(candidate, cwd, mcpServers, sessionId);
+	async #discardNewSession(id: string): Promise<void> {
+		await this.#teardownSession(id, "discarded", true);
+		this.#knownSessionCwds.delete(id);
 	}
 
 	/**
-	 * Resolve a single exact-one scoped candidate via a fresh strict inventory.
-	 * Rejects duplicates and inventory failures — never falls back to a forgiving
-	 * first-match lookup. Used by load/resume so authoritative lifecycle paths bind
-	 * exact identity before opening a stored session.
+	 * All local session disposal follows one path: remove ownership and reject a
+	 * waiting prompt before any awaited socket or broker work. A failed close is
+	 * terminally uncertain, not a reason to leave a usable-looking ACP record.
 	 */
-	#resolveStrictLifecycleCandidate(sessionId: string, scope: string): StrictInventoryCandidate {
-		const snapshot = this.#buildFreshAuthoritySnapshot(scope);
-		const entry = snapshot.entries.get(sessionId);
-		if (!entry) {
-			throw new Error(`ACP session not found: ${sessionId}`);
-		}
-		if (entry.kind !== "candidate") {
-			throw new Error(`ACP session ${sessionId} load failed: ${entry.reason}`);
-		}
-		return entry.candidate;
-	}
-
-	async #forkManagedSession(params: ForkSessionRequest): Promise<ManagedSessionRecord> {
-		const sourcePath = await this.#resolveForkSourceSessionPath(params.sessionId);
-		const session = await this.#createSession(path.resolve(params.cwd));
+	async #teardownSession(id: string, reason: string, closeRemote: boolean): Promise<void> {
+		const record = this.#sessions.get(id);
+		const ownershipBound = record !== undefined || this.#knownSessionCwds.has(id);
+		this.#beginTeardown(id);
 		try {
-			const success = await session.switchSession(sourcePath);
-			if (!success) {
-				throw new Error(`ACP session fork was cancelled: ${params.sessionId}`);
-			}
-			const forked = await session.fork();
-			if (!forked) {
-				throw new Error(`ACP session fork failed: ${params.sessionId}`);
+			this.#advanceSessionEpoch(id);
+			if (record) {
+				this.#sessions.delete(id);
+				record.unsubscribe();
+				record.reconnectUnsubscribe();
+				const waiter = record.activePrompt;
+				record.activePrompt = undefined;
+				waiter?.reject(new AcpSdkAdapterError("connection_closed", `ACP session was ${reason}.`));
 			}
-		} catch (error) {
-			await this.#disposeStandaloneSession(session);
-			throw error;
-		}
-		return await this.#registerPreparedSession(session, params.mcpServers ?? []);
-	}
 
-	async #openStoredSession(
-		issued: StrictInventoryCandidate,
-		cwd: string,
-		mcpServers: McpServer[],
-		sessionId: string,
-	): Promise<ManagedSessionRecord> {
-		const session = await this.#createSession(path.resolve(cwd));
-		try {
-			const current = this.#resolveStrictLifecycleCandidate(sessionId, cwd);
-			if (
-				current.path !== issued.path ||
-				current.cwd !== issued.cwd ||
-				current.identity.dev !== issued.identity.dev ||
-				current.identity.ino !== issued.identity.ino
-			) {
-				throw new Error(`ACP session ${sessionId} changed while opening`);
+			const failures: unknown[] = [];
+			try {
+				await record?.adapter.close();
+			} catch (error) {
+				failures.push(error);
+			}
+			if (closeRemote) {
+				try {
+					await (await this.#brokerAdapter()).global(
+						"session.close",
+						{ sessionId: id },
+						this.#lifecycleIdempotencyKey(id, "session.close"),
+					);
+				} catch (error) {
+					if (!(ownershipBound && this.#isAlreadyGone(error))) failures.push(error);
+				}
 			}
-			const success = await session.switchSession(current.path);
-			if (!success) {
-				throw new Error(`ACP session load was cancelled: ${sessionId}`);
+			if (failures.length > 0) {
+				const detail = failures
+					.map(failure => (failure instanceof Error ? failure.message : String(failure)))
+					.join("; ");
+				throw aggregateAcpFailure("terminal_uncertain", `ACP session cleanup is uncertain: ${detail}`, failures);
 			}
-		} catch (error) {
-			await this.#disposeStandaloneSession(session);
-			throw error;
+		} finally {
+			this.#finishTeardown(id);
 		}
-		return await this.#registerPreparedSession(session, mcpServers);
 	}
 
-	async #registerPreparedSession(session: AgentSession, mcpServers: McpServer[]): Promise<ManagedSessionRecord> {
-		const record = this.#createManagedSessionRecord(session);
-		session.setClientBridge(createAcpClientBridge(this.#connection, session.sessionId, this.#clientCapabilities));
-		// The lifetime subscription normally follows the bootstrap race guard, but
-		// prompt() installs it eagerly once the client has demonstrated session ownership.
+	async #failSession(id: string, adapter: AcpSdkAdapter, error: AcpSdkAdapterError): Promise<void> {
+		const record = this.#sessions.get(id);
+		if (!record || record.adapter !== adapter) return;
+		this.#advanceSessionEpoch(id);
+		this.#sessions.delete(id);
+		record.unsubscribe();
+		record.reconnectUnsubscribe();
+		const waiter = record.activePrompt;
+		record.activePrompt = undefined;
+		waiter?.reject(error);
 		try {
-			await this.#configureExtensions(record);
-			await this.#configureMcpServers(record, mcpServers);
-			if (this.#shuttingDown) {
-				await this.#disposeSessionRecord(record);
-				throw new Error("ACP session lifecycle is unavailable during shutdown");
-			}
-			this.#sessions.set(session.sessionId, record);
-			return record;
-		} catch (error) {
-			await this.#disposeSessionRecord(record);
-			throw error;
-		}
+			await adapter.close();
+		} catch {}
 	}
 
-	#createManagedSessionRecord(session: AgentSession): ManagedSessionRecord {
-		return {
-			session,
-			mcpManager: undefined,
-			promptTurn: undefined,
-			promptQueue: { promise: Promise.resolve(), release: undefined },
-			liveMessageId: undefined,
-			liveMessageProgress: undefined,
-			toolArgsById: new Map(),
-			extensionsConfigured: false,
-			lifetimeUnsubscribe: undefined,
-			terminalState: "active",
-			terminalFailure: undefined,
-			terminalPromise: undefined,
-		};
+	async #brokerAdapter(): Promise<AcpSdkAdapter> {
+		return (await this.#brokerConnection()).adapter;
 	}
 
-	#ensureLifetimeSubscription(record: ManagedSessionRecord): void {
-		if (record.lifetimeUnsubscribe) {
-			return;
-		}
-		record.lifetimeUnsubscribe = record.session.subscribe(event => {
-			void this.#handleLifetimeEvent(record, event);
-		});
+	/** Machine-local endpoint lookup; never routed through ACP extension methods. */
+	async #brokerEndpoint(sessionId: string, endpointGeneration: number | undefined): Promise<unknown> {
+		const input = { sessionId, ...(endpointGeneration === undefined ? {} : { endpointGeneration }) };
+		return await (await this.#brokerConnection()).client.global("session.get_endpoint", input);
 	}
 
-	async #handleLifetimeEvent(record: ManagedSessionRecord, event: AgentSessionEvent): Promise<void> {
-		if (event.type === "auto_compaction_start" || event.type === "auto_compaction_end") {
-			// Prompt-bound compaction is normally forwarded by #handlePromptEvent. The lifetime
-			// subscription covers idle maintenance and the end event after prompt cancellation.
-			const promptTurn = record.promptTurn;
-			if (
-				isPromptTurnInFlight(promptTurn) &&
-				(!promptTurn.cancelRequested || event.type === "auto_compaction_start")
-			) {
-				return;
-			}
-			for (const notification of mapAgentWireEventPayloadToAcpSessionUpdates(
-				toAgentWireEventPayload(event),
-				record.session.sessionId,
-				{
-					cwd: record.session.sessionManager.getCwd(),
-					compactionEndPhase: "idle",
-				},
-			)) {
-				await this.#connection.sessionUpdate(notification);
-			}
-			return;
-		}
-		if (event.type !== "thinking_level_changed") {
-			return;
+	async #brokerConnection(): Promise<BrokerConnection> {
+		if (!this.#broker) {
+			let pending!: Promise<BrokerConnection>;
+			pending = (async () => {
+				await ensureBroker({ agentDir: this.#agentDir });
+				const discovery = await readSdkBrokerDiscovery(this.#agentDir);
+				if (!discovery) throw new AcpSdkAdapterError("unavailable", "SDK broker discovery is unavailable.");
+				const client = await SdkClient.connect(discovery.url, discovery.token);
+				const adapter = new AcpSdkAdapter({ url: discovery.url, token: discovery.token, client });
+				adapter.onReconnectFailed(() => {
+					if (this.#broker === pending) this.#broker = undefined;
+					void adapter.close().catch(() => undefined);
+				});
+				await adapter.start();
+				return { adapter, client };
+			})();
+			this.#broker = pending;
 		}
+		const pending = this.#broker;
 		try {
-			await this.#pushConfigOptionUpdate(record);
+			return await pending;
 		} catch (error) {
-			logger.warn("Failed to push thinking-level config_option_update", {
-				sessionId: record.session.sessionId,
-				error,
-			});
+			if (this.#broker === pending) this.#broker = undefined;
+			throw error;
 		}
 	}
 
-	#getSessionRecord(sessionId: string): ManagedSessionRecord {
-		const record = this.#sessions.get(sessionId);
-		if (!record) {
-			throw new Error(`Unsupported ACP session: ${sessionId}`);
-		}
-		return record;
+	#adapter(id: string): AcpSdkAdapter {
+		const record = this.#sessions.get(id);
+		if (!record) throw new AcpSdkAdapterError("not_found", `Unsupported ACP session: ${id}`);
+		return record.adapter;
 	}
 
-	#assertMatchingCwd(session: AgentSession, cwd: string): void {
-		const expected = path.resolve(cwd);
-		const actual = path.resolve(session.sessionManager.getCwd());
-		if (actual !== expected) {
-			throw new Error(`ACP session ${session.sessionId} is already loaded for ${actual}, not ${expected}`);
-		}
+	async #resolveSavedSession(id: string, cwd: string): Promise<string> {
+		const response = object(
+			await (await this.#brokerAdapter()).global("session.list", { resolveSessionId: id, cwd }),
+		);
+		const result = object(response?.result) ?? response;
+		const saved = object(result?.savedSession);
+		if (saved?.id !== id || typeof saved.path !== "string")
+			throw new AcpSdkAdapterError("not_found", `Saved ACP session does not exist: ${id}`);
+		return saved.path;
 	}
 
-	async #resolveForkSourceSessionPath(sessionId: string): Promise<string> {
-		const loaded = this.#sessions.get(sessionId);
-		if (loaded) {
-			if (loaded.terminalState !== "active") {
-				throw new Error(`ACP session fork is unavailable while it is in terminal state: ${sessionId}`);
-			}
-			if (isPromptTurnInFlight(loaded.promptTurn)) {
-				throw new Error(`ACP session fork is unavailable while a prompt is in progress: ${sessionId}`);
-			}
-			await loaded.session.sessionManager.flush();
-			const sessionPath = loaded.session.sessionManager.getSessionFile();
-			if (!sessionPath) {
-				throw new Error(`ACP session cannot be forked before it is persisted: ${sessionId}`);
-			}
-			return sessionPath;
-		}
-
-		// Inactive fork source: exact-one scoped lookup only. Never use global
-		// listAll/first-match — that was the P1 data-loss path.
-		const scope = this.#canonicalCwdScope;
-		if (!scope) {
-			throw new Error(`ACP session not found (no scope established): ${sessionId}`);
-		}
-		const snapshot = this.#buildFreshAuthoritySnapshot(scope);
-		const entry = snapshot.entries.get(sessionId);
-		if (!entry) {
-			throw new Error(`ACP session not found: ${sessionId}`);
-		}
-		if (entry.kind !== "candidate") {
-			throw new Error(`ACP session fork failed: ${entry.reason}`);
-		}
-		return entry.candidate.path;
+	#providers(): AcpProviderRegistration[] {
+		return acpProviderRegistrations(this.#clientCapabilities);
 	}
 
-	async #handlePromptEvent(record: ManagedSessionRecord, event: AgentSessionEvent): Promise<void> {
-		const promptTurn = record.promptTurn;
-		if (!promptTurn || promptTurn.settled || promptTurn.cancelRequested) {
-			return;
-		}
-
-		if (event.type === "tool_execution_start" || event.type === "tool_execution_update") {
-			record.toolArgsById.set(event.toolCallId, event.args);
-		}
-
-		this.#prepareLiveAssistantMessage(record, event);
-		for (const notification of mapAgentWireEventPayloadToAcpSessionUpdates(
-			toAgentWireEventPayload(event),
-			record.session.sessionId,
-			{
-				getMessageId: message => this.#getLiveMessageId(record, message),
-				getMessageProgress: message => this.#getLiveMessageProgress(record, message),
-				getToolArgs: toolCallId => record.toolArgsById.get(toolCallId),
-				cwd: record.session.sessionManager.getCwd(),
-				compactionEndPhase: "responding",
+	#reverseConnection(sessionId: string): AcpReverseConnection {
+		const methods: Record<string, string> = {
+			"fs.readTextFile": "readTextFile",
+			"fs.writeTextFile": "writeTextFile",
+			"terminal.create": "createTerminal",
+			"permission.request": "requestPermission",
+			"ui.elicit": "unstable_createElicitation",
+		};
+		return {
+			request: async (method: string, params: JsonObject): Promise<unknown> => {
+				const name = methods[method] ?? method;
+				const target = (this.#connection as unknown as Record<string, unknown>)[name];
+				if (typeof target !== "function")
+					throw new AcpSdkAdapterError("acp_reverse_unavailable", `ACP reverse method is unavailable: ${method}`);
+				const request = method === "permission.request" ? { ...params, sessionId } : params;
+				return await (target as (input: JsonObject) => Promise<unknown>)(request);
 			},
-		)) {
-			await this.#connection.sessionUpdate(notification);
-		}
-		if (event.type === "tool_execution_end") {
-			record.toolArgsById.delete(event.toolCallId);
-		}
-		this.#clearLiveAssistantMessageAfterEvent(record, event);
-
-		if (event.type === "agent_end") {
-			await this.#emitEndOfTurnUpdates(record);
-			await this.#waitForAcpPromptIdle(record);
-			this.#finishPrompt(record, {
-				stopReason: this.#resolveStopReason(event, promptTurn.cancelRequested),
-				usage: this.#buildTurnUsage(promptTurn.usageBaseline, record.session.sessionManager.getUsageStatistics()),
-				_meta: { userMessageId: promptTurn.userMessageId },
-			});
-		}
+		};
 	}
 
-	async #waitForAcpPromptIdle(record: ManagedSessionRecord): Promise<void> {
-		for (let pass = 0; pass < ACP_ASYNC_DELIVERY_DRAIN_MAX_PASSES; pass++) {
-			await record.session.waitForIdle();
-			const delivered = await record.session.drainAsyncJobDeliveriesForAcp({
-				timeoutMs: ACP_ASYNC_DELIVERY_DRAIN_TIMEOUT_MS,
-			});
-			if (!delivered) {
-				return;
-			}
-		}
-
-		await record.session.waitForIdle();
+	#observeSessionActivity(record: SessionRecord, frame: JsonObject): void {
+		const event = receivedSdkEvent(frame)?.event;
+		if (event?.type === "agent_start") record.busy = true;
+		else if (event?.type === "agent_end") record.busy = false;
 	}
 
-	#prepareLiveAssistantMessage(record: ManagedSessionRecord, event: AgentSessionEvent): void {
-		if (
-			(event.type === "message_start" || event.type === "message_update" || event.type === "message_end") &&
-			event.message.role === "assistant" &&
-			(event.type === "message_start" || !record.liveMessageId || !record.liveMessageProgress)
-		) {
-			record.liveMessageId = crypto.randomUUID();
-			record.liveMessageProgress = { textEmitted: false, thoughtEmitted: false };
-		}
+	#frameProcessingFailure(error: unknown): AcpSdkAdapterError {
+		if (error instanceof AcpSdkAdapterError && error.code === "frame_processing_failed") return error;
+		const detail = error instanceof Error ? error.message : String(error);
+		return new AcpSdkAdapterError("frame_processing_failed", `ACP session frame processing failed: ${detail}`);
 	}
 
-	#clearLiveAssistantMessageAfterEvent(record: ManagedSessionRecord, event: AgentSessionEvent): void {
-		if ((event.type === "message_end" && event.message.role === "assistant") || event.type === "agent_end") {
-			record.liveMessageId = undefined;
-			record.liveMessageProgress = undefined;
-		}
+	#enqueueSdkFrame(id: string, adapter: AcpSdkAdapter, frame: JsonObject): void {
+		const record = this.#sessions.get(id);
+		if (!record || record.adapter !== adapter) return;
+		// Sequence and busy state are captured at ingress, before queued work begins.
+		// A frame received before acknowledgement stays before that prompt's boundary.
+		this.#observeSessionActivity(record, frame);
+		const sequence = ++record.inboundSequence;
+		const task = record.frameTail.then(async () => await this.#handleSdkFrame(id, adapter, frame, sequence));
+		record.frameTail = task.catch(
+			async error => await this.#failSession(id, adapter, this.#frameProcessingFailure(error)),
+		);
 	}
 
-	#getLiveMessageId(record: ManagedSessionRecord, message: unknown): string | undefined {
-		if (typeof message !== "object" || message === null) {
-			return undefined;
+	async #handleSdkFrame(id: string, adapter: AcpSdkAdapter, frame: JsonObject, sequence: number): Promise<void> {
+		const record = this.#sessions.get(id);
+		if (!record || record.adapter !== adapter) return;
+		const received = receivedSdkEvent(frame);
+		if (!received) return;
+		const { event, wirePayload } = received;
+		const correlation = correlationFrom(frame, event);
+		const activePrompt = record.activePrompt;
+		// Prompt ownership is updated before publishing client notifications, but a
+		// terminal waiter is resolved only after publication succeeds so a failed
+		// sessionUpdate rejects the prompt instead of reporting false completion.
+		if (
+			activePrompt?.acknowledged &&
+			sequence > activePrompt.boundary &&
+			!correlationsConflict(activePrompt.correlation, correlation)
+		) {
+			if (isPromptActivity(String(event.type))) {
+				activePrompt.activityObserved = true;
+			} else if (event.type === "agent_end") {
+				if (
+					correlationsMatch(activePrompt.correlation, correlation) ||
+					activePrompt.activityObserved ||
+					activePrompt.steeringAtAcknowledgement
+				)
+					activePrompt.pendingTerminal = correlation;
+			}
 		}
-		record.liveMessageId ??= crypto.randomUUID();
-		return record.liveMessageId;
-	}
-
-	#getLiveMessageProgress(
-		record: ManagedSessionRecord,
-		message: unknown,
-	): { textEmitted: boolean; thoughtEmitted: boolean } | undefined {
-		if (typeof message !== "object" || message === null) {
-			return undefined;
+		if (wirePayload) {
+			for (const notification of mapAgentWireEventPayloadToAcpSessionUpdates(wirePayload as never, id, {
+				cwd: record.cwd,
+			}))
+				await this.#publishSessionUpdate(id, notification, adapter);
 		}
-		record.liveMessageProgress ??= { textEmitted: false, thoughtEmitted: false };
-		return record.liveMessageProgress;
+		if (event.type === "agent_end") await this.#emitEndOfTurnUpdates(id, adapter);
+		if (activePrompt) this.#settlePrompt(record, activePrompt);
 	}
 
-	#finishPrompt(record: ManagedSessionRecord, response?: PromptResponse, error?: unknown): void {
-		const promptTurn = record.promptTurn;
-		if (!promptTurn || promptTurn.settled) {
-			return;
-		}
-		promptTurn.settled = true;
-		promptTurn.unsubscribe?.();
-		// Keep the slot occupied until cancel cleanup finishes — `#runCancelCleanup`
-		// evicts the slot in its finally block once both flags say it's safe.
-		if (!promptTurn.cleanup && record.promptTurn === promptTurn) {
-			record.promptTurn = undefined;
-		}
-		if (error !== undefined) {
-			promptTurn.reject(error);
+	#settlePrompt(record: SessionRecord, waiter: PromptWaiter): void {
+		if (record.activePrompt !== waiter || !waiter.acknowledged || !waiter.pendingTerminal) return;
+		if (correlationsConflict(waiter.correlation, waiter.pendingTerminal)) return;
+		if (
+			!correlationsMatch(waiter.correlation, waiter.pendingTerminal) &&
+			!waiter.activityObserved &&
+			!waiter.steeringAtAcknowledgement
+		)
 			return;
-		}
-		promptTurn.resolve(response ?? { stopReason: "end_turn" });
-	}
-
-	#resolveStopReason(
-		event: Extract<AgentSessionEvent, { type: "agent_end" }>,
-		cancelRequested: boolean,
-	): PromptResponse["stopReason"] {
-		if (cancelRequested) {
-			return "cancelled";
-		}
-		const lastAssistant = [...event.messages]
-			.reverse()
-			.find((message): message is AssistantMessage => message.role === "assistant");
-		const reason = lastAssistant?.stopReason;
-		switch (reason) {
-			case "aborted":
-				return "cancelled";
-			case "length":
-				return "max_tokens";
-			case "error": {
-				if (lastAssistant?.errorKind === "provider_safety_stop") {
-					return "refusal";
-				}
-				if (isLegacyProviderSafetyStopMessage(lastAssistant?.errorMessage ?? "")) {
-					return "refusal";
-				}
-				return "end_turn";
-			}
-			default:
-				return "end_turn";
-		}
+		record.activePrompt = undefined;
+		waiter.resolve({ stopReason: waiter.cancelRequested ? "cancelled" : "end_turn" });
 	}
 
-	async #emitCommandOutput(record: ManagedSessionRecord, text: string): Promise<void> {
-		if (!text) {
-			return;
+	async #emitEndOfTurnUpdates(id: string, adapter: AcpSdkAdapter): Promise<void> {
+		let usage: JsonObject | undefined;
+		try {
+			const response = object(await adapter.query("context.get"));
+			const result = object(response?.result) ?? response;
+			usage = object(result?.usage);
+		} catch {
+			// Context usage is advisory ACP metadata; prompt completion remains authoritative.
+		}
+		if (typeof usage?.tokens === "number" && typeof usage.contextWindow === "number") {
+			await this.#publishSessionUpdate(
+				id,
+				{
+					sessionId: id,
+					update: {
+						sessionUpdate: "usage_update",
+						size: usage.contextWindow,
+						used: usage.tokens,
+					},
+				},
+				adapter,
+			);
 		}
-		await this.#connection.sessionUpdate({
-			sessionId: record.session.sessionId,
-			update: {
-				sessionUpdate: "agent_message_chunk",
-				content: { type: "text", text },
-				messageId: crypto.randomUUID(),
+		await this.#publishSessionUpdate(
+			id,
+			{
+				sessionId: id,
+				update: {
+					sessionUpdate: "session_info_update",
+					updatedAt: new Date().toISOString(),
+					_meta: { gjcPhase: "idle", running: false, gjcRunning: false },
+				},
 			},
-		});
-	}
-
-	#assertAbsoluteCwd(cwd: string): void {
-		if (!path.isAbsolute(cwd)) {
-			throw new Error(`ACP cwd must be absolute: ${cwd}`);
-		}
-	}
-
-	/**
-	 * Validate the cwd and reject cross-cwd calls against an already-committed scope,
-	 * WITHOUT committing. Returns the canonical (resolved) cwd. Pair with
-	 * {@link #commitCanonicalScope} after the lifecycle operation succeeds so a failed
-	 * first new/load/resume/fork/list never pins the connection to a cwd it never served.
-	 */
-	#stageCanonicalScope(cwd: string): string {
-		this.#assertAbsoluteCwd(cwd);
-		const canonical = path.resolve(cwd);
-		if (this.#canonicalCwdScope !== undefined && this.#canonicalCwdScope !== canonical) {
-			throw new Error(`ACP connection is scoped to ${this.#canonicalCwdScope}, not ${canonical}`);
-		}
-		return canonical;
+			adapter,
+		);
 	}
 
-	/** Commit the canonical cwd scope on the first successful explicit-cwd call. */
-	#commitCanonicalScope(canonical: string): void {
-		if (this.#canonicalCwdScope === undefined) {
-			this.#canonicalCwdScope = canonical;
+	async #publishSessionUpdate(
+		id: string,
+		notification: SessionNotification,
+		expectedAdapter?: AcpSdkAdapter,
+	): Promise<void> {
+		const record = this.#sessions.get(id);
+		if (!record || (expectedAdapter && record.adapter !== expectedAdapter)) return;
+		try {
+			await this.#connection.sessionUpdate(notification);
+		} catch (error) {
+			const failure = this.#frameProcessingFailure(error);
+			await this.#failSession(id, record.adapter, failure);
+			throw failure;
+		}
+	}
+
+	async #sessionState(id: string): Promise<Pick<NewSessionResponse, "configOptions" | "modes">> {
+		const record = this.#sessions.get(id);
+		if (!record) throw new AcpSdkAdapterError("not_found", `Unsupported ACP session: ${id}`);
+		const [config, models] = await Promise.all([
+			record.adapter.query("config.list/get"),
+			record.adapter.query("models.list/current"),
+		]);
+		return acpSessionStateFromConfig(config, models);
+	}
+
+	async #replaySession(id: string): Promise<void> {
+		const adapter = this.#adapter(id);
+		let cursor: string | undefined;
+		let imageLimitationReported = false;
+		for (let pageCount = 0; pageCount < MAX_ACP_REPLAY_PAGES; pageCount++) {
+			const response = object(await adapter.query("transcript.list", {}, cursor));
+			const result = object(response?.result) ?? response;
+			const page = object(result?.page);
+			for (const item of Array.isArray(page?.items) ? page.items : []) {
+				const message = object(item);
+				if (!message || (message.role !== "user" && message.role !== "assistant")) continue;
+				const content = transcriptReplayContent(message);
+				if (!imageLimitationReported) {
+					imageLimitationReported = true;
+					await this.#publishSessionUpdate(
+						id,
+						{
+							sessionId: id,
+							update: {
+								sessionUpdate: "session_info_update",
+								_meta: { gjcTranscriptImageReplay: content.images },
+							},
+						},
+						adapter,
+					);
+				}
+				const messageId = typeof message.id === "string" ? message.id : undefined;
+				for (const block of content.blocks) {
+					await this.#publishSessionUpdate(
+						id,
+						{
+							sessionId: id,
+							update: {
+								sessionUpdate: message.role === "user" ? "user_message_chunk" : "agent_message_chunk",
+								content: block,
+								...(messageId ? { messageId } : {}),
+							},
+						},
+						adapter,
+					);
+				}
+			}
+			cursor = typeof page?.continuationCursor === "string" ? page.continuationCursor : undefined;
+			if (!cursor) return;
 		}
+		throw new AcpSdkAdapterError("resource_exhausted", "ACP transcript replay exceeded the page limit.");
 	}
 
-	/** Bump the generation and discard the authority snapshot on lifecycle changes. */
-	#invalidateAuthority(): void {
-		this.#authorityGeneration += 1;
-		this.#authoritySnapshot = undefined;
+	#scheduleBootstrap(id: string): void {
+		setTimeout(() => {
+			const record = this.#sessions.get(id);
+			if (!record || this.#connection.signal.aborted) return;
+			void this.#publishSessionUpdate(
+				id,
+				{
+					sessionId: id,
+					update: {
+						sessionUpdate: "session_info_update",
+						_meta: { gjcPhase: "idle", running: false, gjcRunning: false },
+					},
+				},
+				record.adapter,
+			).catch(() => undefined);
+		}, ACP_BOOTSTRAP_RACE_GUARD_MS);
 	}
 
-	#rejectIfTerminal(record: ManagedSessionRecord): void {
-		if (record.terminalState !== "active") {
-			throw new Error(`ACP session ${record.session.sessionId} is in terminal state: ${record.terminalState}`);
-		}
+	#cursor(cursor: string | null | undefined): number {
+		if (!cursor) return 0;
+		const value = Number.parseInt(cursor, 10);
+		if (!Number.isSafeInteger(value) || value < 0) throw new Error(`Invalid ACP session cursor: ${cursor}`);
+		return value;
 	}
 
-	#rejectIfShuttingDown(): void {
-		if (this.#shuttingDown) {
-			throw new Error("ACP session lifecycle is unavailable during shutdown");
-		}
+	#assertAbsoluteCwd(cwd: string): void {
+		if (!path.isAbsolute(cwd)) throw new Error(`ACP cwd must be an absolute path: ${cwd}`);
 	}
 
-	/**
-	 * Build (or reuse) the complete authorization snapshot from a strict raw scoped
-	 * inventory. The cached pagination snapshot is reused for display/list paging.
-	 * Any inventory failure throws a sanitized error — it grants zero authority.
-	 * The snapshot binds every discovered id to its exact-identity candidate or a
-	 * conflict tombstone BEFORE pagination, so duplicates beyond page 1 are known
-	 * before the first page response.
-	 */
-	#buildAuthoritySnapshot(scope: string): AcpAuthoritySnapshot {
-		if (this.#authoritySnapshot?.scope === scope) {
-			return this.#authoritySnapshot;
-		}
-		return this.#rebuildAuthoritySnapshot(scope, true);
+	#assertNoMcpServers(params: { mcpServers?: unknown[] }): void {
+		if (params.mcpServers && params.mcpServers.length > 0)
+			throw new AcpSdkAdapterError("unsupported", "MCP servers are unsupported under SDK-backed ACP.");
 	}
 
-	/**
-	 * Build a FRESH authorization snapshot, ignoring the cached pagination snapshot.
-	 * Destructive authority (delete, inactive fork) must read storage at mutation
-	 * time so an external create/remove/replace/duplicate between list and delete
-	 * cannot yield a stale no-op or wrong mutation. The result is NOT cached: it
-	 * must not poison the generation-aware pagination cursor contract.
-	 */
-	#buildFreshAuthoritySnapshot(scope: string): AcpAuthoritySnapshot {
-		return this.#rebuildAuthoritySnapshot(scope, false);
+	#beginDispose(): void {
+		if (this.#disposePromise) return;
+		this.#disposePromise = this.#dispose();
+		// AbortSignal listeners cannot return a promise to their caller. Retain the
+		// aggregate cleanup result while attaching a rejection handler so disposal
+		// never creates a detached unhandled rejection.
+		void this.#disposePromise.catch(() => undefined);
 	}
 
-	#rebuildAuthoritySnapshot(scope: string, cache: boolean): AcpAuthoritySnapshot {
-		const inventory = SessionManager.inventorySessionsStrict(scope);
-		if (inventory.kind === "failure") {
-			const messages = inventory.failures.map(f => `${f.kind}: ${f.message}`);
-			throw new Error(`ACP scoped session inventory is incomplete: ${messages.join("; ")}`);
-		}
-		const entries = new Map<string, AcpAuthorityEntry>();
-		const orderedIds: string[] = [];
-		for (const candidate of inventory.candidates) {
-			const existing = entries.get(candidate.id);
-			if (existing) {
-				entries.set(candidate.id, { kind: "conflict", reason: "Duplicate session id in scoped inventory" });
-			} else {
-				entries.set(candidate.id, { kind: "candidate", candidate });
-				orderedIds.push(candidate.id);
+	async #dispose(): Promise<void> {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		const failures: unknown[] = [];
+		for (const id of [...this.#sessions.keys()]) {
+			try {
+				await this.#teardownSession(id, "connection closed", false);
+			} catch (error) {
+				failures.push(error);
 			}
 		}
-		const snapshot: AcpAuthoritySnapshot = {
-			scope,
-			entries,
-			orderedIds,
-			generation: this.#authorityGeneration,
-		};
-		if (cache) {
-			this.#authoritySnapshot = snapshot;
-		}
-		return snapshot;
-	}
-
-	/**
-	 * Delete an active (loaded) session via the per-record terminal state machine.
-	 * Reserves `deleting` before the first await; concurrent deletes join the
-	 * terminal promise. On failure the state transitions to `pre_dispatch_retryable`
-	 * (close_failed_retryable), `cleanup_pending` (verified-delete partial), or
-	 * `terminal_failure` (close_unknown / quiescence / unexpected) — all non-`active`
-	 * states reject prompt/config/close/load/resume/fork. Only `pre_dispatch_retryable`
-	 * and `cleanup_pending` permit a retry delete; `terminal_failure` never reopens.
-	 */
-	async #deleteActiveSession(sessionId: string, record: ManagedSessionRecord): Promise<DeleteSessionResponse> {
-		// Concurrent delete joins the in-progress terminal promise.
-		if (record.terminalPromise) {
-			return await record.terminalPromise;
-		}
-		// terminal_failure: never reopen — share the settled error.
-		if (record.terminalState === "terminal_failure") {
-			throw record.terminalFailure ?? new Error(`ACP session ${sessionId} has a settled terminal failure`);
+		this.#attaching.clear();
+		this.#resolvingExisting.clear();
+		this.#knownSessionCwds.clear();
+		this.#tearingDown.clear();
+		if (this.#broker) {
+			const broker = this.#broker;
+			this.#broker = undefined;
+			try {
+				await (await broker).adapter.close();
+			} catch (error) {
+				failures.push(error);
+			}
 		}
-		// Only active / pre_dispatch_retryable / cleanup_pending may start a delete.
-		if (record.terminalState === "deleting") {
-			throw new Error(`ACP session ${sessionId} is being deleted`);
+		if (failures.length > 0) {
+			const detail = failures
+				.map(failure => (failure instanceof Error ? failure.message : String(failure)))
+				.join("; ");
+			throw aggregateAcpFailure("terminal_uncertain", `ACP connection cleanup is uncertain: ${detail}`, failures);
 		}
-		record.terminalState = "deleting";
-		const scope = this.#canonicalCwdScope!;
-		const terminalPromise = (async (): Promise<DeleteSessionResponse> => {
-			try {
-				// Quiesce — failure is terminal (never swallow).
-				try {
-					await this.#quiesceForDelete(sessionId, record);
-				} catch (quiesceError) {
-					record.terminalState = "terminal_failure";
-					record.terminalFailure = quiesceError instanceof Error ? quiesceError : new Error(String(quiesceError));
-					throw quiesceError;
-				}
-				const manager = record.session.sessionManager;
-				// Strict close — outcome determines retryability.
-				const closeOutcome = await record.session.closeWriterStrict();
-				if (closeOutcome.kind !== "closed") {
-					if (closeOutcome.kind === "close_failed_retryable") {
-						record.terminalState = "pre_dispatch_retryable";
-					} else {
-						record.terminalState = "terminal_failure";
-						record.terminalFailure = closeOutcome.error;
-					}
-					const reason =
-						closeOutcome.kind === "close_unknown"
-							? "writer close outcome is unknown"
-							: "writer close failed before dispatch";
-					throw new Error(`ACP session ${sessionId} cannot be deleted: ${reason}`);
-				}
-				// Recheck: the record must still own this exact session.
-				if (this.#sessions.get(sessionId) !== record || record.terminalState !== "deleting") {
-					record.terminalState = "terminal_failure";
-					record.terminalFailure = new Error(`ACP session ${sessionId} state changed during deletion`);
-					throw new Error(`ACP session ${sessionId} state changed during deletion`);
-				}
-				const sessionFile = manager.getSessionFile();
-				const sessionDir = manager.getSessionDir();
-				if (!sessionFile) {
-					record.terminalState = "terminal_failure";
-					record.terminalFailure = new Error(`ACP session ${sessionId} is not persisted and cannot be deleted`);
-					throw new Error(`ACP session ${sessionId} is not persisted and cannot be deleted`);
-				}
-				const snapshot = this.#buildFreshAuthoritySnapshot(scope);
-				const entry = snapshot.entries.get(sessionId);
-				if (entry?.kind !== "candidate") {
-					record.terminalState = "terminal_failure";
-					record.terminalFailure = new Error(`ACP session ${sessionId} is not an exact-one scoped candidate`);
-					throw new Error(`ACP session ${sessionId} is not an exact-one scoped candidate`);
-				}
-				if (entry.candidate.path !== sessionFile) {
-					record.terminalState = "terminal_failure";
-					record.terminalFailure = new Error(`ACP session ${sessionId} transcript path changed during deletion`);
-					throw new Error(`ACP session ${sessionId} transcript path changed during deletion`);
-				}
-				this.#assertPendingTranscriptIdentity(sessionId, entry.candidate.identity);
-				const sessionsRoot = path.dirname(sessionDir);
-				const target: VerifiedSessionDeleteTarget = {
-					sessionsRoot,
-					transcriptPath: sessionFile,
-					sessionId,
-					cwd: manager.getCwd(),
-					transcriptIdentity: {
-						dev: entry.candidate.identity.dev,
-						ino: entry.candidate.identity.ino,
-					},
-					...this.#pendingArtifactsIdentity(sessionId),
-				};
-				const outcome = await manager.deleteSessionVerified(target);
-				if (outcome.kind !== "deleted") {
-					record.terminalState = "cleanup_pending";
-					this.#recordPendingDeleteEvidence(sessionId, outcome);
-					throw new Error(
-						`ACP session ${sessionId} delete is incomplete: ${outcome.phase} cleanup pending (${outcome.error.message})`,
-					);
-				}
-				// Fully deleted: clear retry evidence, remove from active map, dispose.
-				record.terminalState = "deleted";
-				this.#pendingDeleteEvidence.delete(sessionId);
-				this.#sessions.delete(sessionId);
-				this.#invalidateAuthority();
-				await this.#disposeSessionRecord(record);
-				return {};
-			} catch (error) {
-				// terminalState was set at the failure point above. For any
-				// unexpected error that left the state as `deleting`, treat it
-				// as terminal_failure so the record never silently reopens.
-				if (record.terminalState === "deleting") {
-					record.terminalState = "terminal_failure";
-					record.terminalFailure = error instanceof Error ? error : new Error(String(error));
-				}
-				record.terminalPromise = undefined;
-				this.#invalidateAuthority();
-				throw error;
-			}
-		})();
-		record.terminalPromise = terminalPromise;
-		return await terminalPromise;
-	}
-
-	/**
-	 * Delete an inactive (not currently loaded) session. The ID must have been
-	 * issued by the last complete scoped authority snapshot; an absent/unissued ID
-	 * returns lookup-free `{}` with NO inventory scan. Only after issuance may a
-	 * fresh strict inventory revalidate the same exact candidate before mutation.
-	 * A repeat-unknown (issued but gone from the fresh inventory) is also lookup-free `{}`.
-	 */
-	async #deleteInactiveSession(sessionId: string): Promise<DeleteSessionResponse> {
-		const scope = this.#canonicalCwdScope!;
-		// Gate: only IDs issued by the last complete scoped authority snapshot
-		// may trigger a fresh inventory scan. Absent/unissued → lookup-free {}.
-		const issued = this.#authoritySnapshot?.entries.get(sessionId);
-		if (!issued) {
-			return {};
-		}
-		if (issued.kind === "conflict") {
-			throw new Error(`ACP session delete failed: ${issued.reason}`);
-		}
-		// Fresh strict inventory to revalidate the same exact candidate.
-		const snapshot = this.#buildFreshAuthoritySnapshot(scope);
-		const entry = snapshot.entries.get(sessionId);
-		if (!entry) {
-			// Repeat unknown: issued but no longer present in the fresh inventory.
-			return {};
-		}
-		if (entry.kind === "conflict") {
-			throw new Error(`ACP session delete failed: ${entry.reason}`);
-		}
-		const candidate = entry.candidate;
-		if (
-			candidate.path !== issued.candidate.path ||
-			candidate.cwd !== issued.candidate.cwd ||
-			candidate.identity.dev !== issued.candidate.identity.dev ||
-			candidate.identity.ino !== issued.candidate.identity.ino
-		) {
-			throw new Error(`ACP session ${sessionId} changed since authority was issued`);
-		}
-		this.#assertPendingTranscriptIdentity(sessionId, candidate.identity);
-		const sessionsRoot = path.dirname(candidate.path);
-		const target: VerifiedSessionDeleteTarget = {
-			sessionsRoot,
-			transcriptPath: candidate.path,
-			sessionId,
-			cwd: candidate.cwd,
-			transcriptIdentity: { dev: candidate.identity.dev, ino: candidate.identity.ino },
-			...this.#pendingArtifactsIdentity(sessionId),
-		};
-		const storage = new FileSessionStorage();
-		const outcome = await storage.deleteSessionVerified(target);
-		if (outcome.kind !== "deleted") {
-			this.#recordPendingDeleteEvidence(sessionId, outcome);
-			throw new Error(
-				`ACP session ${sessionId} delete is incomplete: ${outcome.phase} cleanup pending (${outcome.error.message})`,
-			);
-		}
-		this.#pendingDeleteEvidence.delete(sessionId);
-		this.#invalidateAuthority();
-		return {};
-	}
-
-	#convertPromptBlocks(blocks: PromptRequest["prompt"]): { text: string; images: AgentImageContent[] } {
-		const textParts: string[] = [];
-		const images: AgentImageContent[] = [];
-		for (const block of blocks) {
-			switch (block.type) {
-				case "text":
-					textParts.push(block.text);
-					break;
-				case "image":
-					images.push({ type: "image", data: block.data, mimeType: block.mimeType });
-					break;
-				case "resource":
-					if ("text" in block.resource) {
-						textParts.push(block.resource.text);
-					} else if (typeof block.resource.mimeType === "string" && block.resource.mimeType.startsWith("image/")) {
-						// `embeddedContext: true` covers both text and blob resources, but
-						// blobs aren't directly consumable by the LLM. Route image blobs
-						// to the images array so the user's intent survives; everything
-						// else falls back to the URI placeholder below.
-						images.push({ type: "image", data: block.resource.blob, mimeType: block.resource.mimeType });
-					} else {
-						textParts.push(`[embedded resource: ${block.resource.uri}]`);
-					}
-					break;
-				case "resource_link":
-					textParts.push(block.title ?? block.name ?? block.uri);
-					break;
-				case "audio":
-					textParts.push("[audio omitted]");
-					break;
-			}
-		}
-		return {
-			text: textParts.join("\n\n").trim(),
-			images,
-		};
-	}
-
-	async #pushConfigOptionUpdate(record: ManagedSessionRecord): Promise<void> {
-		await this.#connection.sessionUpdate({
-			sessionId: record.session.sessionId,
-			update: {
-				sessionUpdate: "config_option_update",
-				configOptions: this.#buildConfigOptions(record.session),
-			},
-		});
-	}
-
-	#buildConfigOptions(session: AgentSession): SessionConfigOption[] {
-		const currentModeId = this.#getCurrentModeId(session);
-		const modeOptions = this.#getAvailableModes(session).map(mode => ({
-			value: mode.id,
-			name: mode.name,
-			description: mode.description,
-		}));
-		const configOptions: SessionConfigOption[] = [
-			{
-				id: MODE_CONFIG_ID,
-				name: "Mode",
-				category: "mode",
-				type: "select",
-				currentValue: currentModeId,
-				options: modeOptions,
-			},
-		];
-
-		const models = session.getAvailableModels();
-		const currentModel = session.model;
-		if (models.length > 0) {
-			configOptions.push({
-				id: MODEL_CONFIG_ID,
-				name: "Model",
-				category: "model",
-				type: "select",
-				currentValue: currentModel ? this.#toModelId(currentModel) : this.#toModelId(models[0]),
-				options: models.map(model => ({
-					value: this.#toModelId(model),
-					name: model.name,
-					description: `${model.provider}/${model.id}`,
-				})),
-			});
-		}
-
-		configOptions.push({
-			id: THINKING_CONFIG_ID,
-			name: "Thinking",
-			category: "thought_level",
-			type: "select",
-			currentValue: this.#toThinkingConfigValue(session.thinkingLevel),
-			options: this.#buildThinkingOptions(session),
-		});
-		return configOptions;
-	}
-
-	#buildThinkingOptions(session: AgentSession): Array<{ value: string; name: string; description?: string }> {
-		return [
-			{ value: THINKING_OFF, name: "Off" },
-			...session.getAvailableThinkingLevels().map(level => ({
-				value: level,
-				name: level,
-			})),
-		];
-	}
-
-	#toThinkingConfigValue(value: string | undefined): string {
-		return value && value !== "inherit" ? value : THINKING_OFF;
-	}
-
-	async #setModelById(session: AgentSession, modelId: string): Promise<void> {
-		const model = session.getAvailableModels().find(candidate => this.#toModelId(candidate) === modelId);
-		if (!model) {
-			throw new Error(`Unknown ACP model: ${modelId}`);
-		}
-		await session.setModel(model);
-	}
-
-	#setThinkingLevelById(session: AgentSession, value: string): void {
-		const thinkingLevel = parseThinkingLevel(value);
-		if (!thinkingLevel) {
-			throw new Error(`Unknown ACP thinking level: ${value}`);
-		}
-		session.setThinkingLevel(thinkingLevel);
-	}
-
-	#toModelId(model: Model): string {
-		return `${model.provider}/${model.id}`;
-	}
-
-	#getAvailableModes(session: AgentSession): Array<{ id: string; name: string; description: string }> {
-		const modes = [{ id: ACP_DEFAULT_MODE_ID, name: "Default", description: "Standard ACP headless mode" }];
-		if (session.settings.get("plan.enabled")) {
-			modes.push({
-				id: ACP_PLAN_MODE_ID,
-				name: "Plan",
-				description: "Read-only planning mode that drafts a plan to a markdown file before any code changes",
-			});
-		}
-		void session;
-		return modes;
-	}
-
-	#getCurrentModeId(session: AgentSession): string {
-		return session.getPlanModeState()?.enabled ? ACP_PLAN_MODE_ID : ACP_DEFAULT_MODE_ID;
-	}
-
-	#applyModeChange(session: AgentSession, modeId: string): void {
-		const availableModes = this.#getAvailableModes(session);
-		if (!availableModes.some(mode => mode.id === modeId)) {
-			throw new Error(`Unsupported ACP mode: ${modeId}`);
-		}
-		if (modeId === ACP_PLAN_MODE_ID) {
-			const previous = session.getPlanModeState();
-			session.setPlanModeState({
-				enabled: true,
-				planFilePath: previous?.planFilePath ?? DEFAULT_PLAN_FILE_URL,
-				workflow: previous?.workflow ?? "parallel",
-				reentry: previous !== undefined,
-			});
-		} else {
-			session.setPlanModeState(undefined);
-		}
-	}
-
-	#buildModeState(session: AgentSession): SessionModeState {
-		return {
-			availableModes: this.#getAvailableModes(session),
-			currentModeId: this.#getCurrentModeId(session),
-		};
-	}
-
-	#buildCurrentModeUpdate(session: AgentSession): SessionUpdate {
-		return {
-			sessionUpdate: "current_mode_update",
-			currentModeId: this.#getCurrentModeId(session),
-		};
-	}
-
-	async #buildAvailableCommands(session: AgentSession): Promise<AvailableCommand[]> {
-		const commands: AvailableCommand[] = [];
-		const seenNames = new Set<string>();
-		const appendCommand = (command: AvailableCommand): void => {
-			if (seenNames.has(command.name)) {
-				return;
-			}
-			seenNames.add(command.name);
-			commands.push(command);
-		};
-
-		// Advertise builtins first, then custom/user commands, then file-based
-		// slash commands, then namespaced `/skill:<name>` skills.
-		for (const command of ACP_BUILTIN_SLASH_COMMANDS) {
-			appendCommand(command);
-		}
-
-		for (const command of session.customCommands) {
-			appendCommand({
-				name: command.command.name,
-				description: command.command.description,
-				input: { hint: "arguments" },
-			});
-		}
-
-		for (const command of await loadSlashCommands({ cwd: session.sessionManager.getCwd() })) {
-			appendCommand({
-				name: command.name,
-				description: command.description,
-			});
-		}
-
-		if (session.skillsSettings?.enableSkillCommands) {
-			for (const skill of session.skills) {
-				if (skill.hide === true) continue;
-				for (const name of getSkillSlashCommandNames(skill)) {
-					appendCommand({
-						name,
-						description: skill.description || `Run ${skill.name} skill`,
-						input: { hint: "arguments" },
-					});
-				}
-			}
-		}
-
-		return commands;
-	}
-
-	#toSessionInfo(session: StoredSessionInfo): SessionInfo {
-		return {
-			sessionId: session.id,
-			cwd: session.cwd,
-			title: session.title,
-			updatedAt: session.modified.toISOString(),
-			_meta: {
-				messageCount: session.messageCount,
-				size: session.size,
-			},
-		};
-	}
-
-	#scheduleBootstrapUpdates(sessionId: string): void {
-		// Defer first notifications until the response has reached the client.
-		// Zed's agent-client-protocol reader dispatches responses and
-		// notifications to different async tasks; sending the first
-		// `available_commands_update` from `setTimeout(0)` reliably loses the
-		// race against the response handler and Zed logs `Received session
-		// notification for unknown session` then drops the update — leaving
-		// the slash-command palette empty (#1015 follow-up; see
-		// zed-industries/zed#55965 for the same race biting other ACP agents).
-		// `ACP_BOOTSTRAP_RACE_GUARD_MS` is invisible to the operator and large
-		// enough that the response future has scheduled before our timer fires
-		// on stdio-only transports.
-		//
-		// The session-lifetime subscription normally shares this guard so extension
-		// work cannot notify an unknown session id. prompt() may install it earlier:
-		// receipt of a prompt proves the client already owns the returned session id,
-		// and closes the cancellation window before this timer fires.
-		setTimeout(() => {
-			if (this.#connection.signal.aborted) {
-				return;
-			}
-			const record = this.#sessions.get(sessionId);
-			if (!record) {
-				return;
-			}
-			this.#ensureLifetimeSubscription(record);
-			void this.#emitBootstrapUpdates(sessionId, record);
-		}, ACP_BOOTSTRAP_RACE_GUARD_MS);
-	}
-
-	async #emitBootstrapUpdates(sessionId: string, record: ManagedSessionRecord): Promise<void> {
-		if (this.#sessions.get(sessionId) !== record) {
-			return;
-		}
-		await this.#connection.sessionUpdate({
-			sessionId,
-			update: {
-				sessionUpdate: "available_commands_update",
-				availableCommands: await this.#buildAvailableCommands(record.session),
-			},
-		});
-		await this.#connection.sessionUpdate({
-			sessionId,
-			update: {
-				sessionUpdate: "session_info_update",
-				title: record.session.sessionName,
-				updatedAt: record.session.sessionManager.getHeader()?.timestamp,
-			},
-		});
-	}
-
-	async #emitAvailableCommandsUpdate(record: ManagedSessionRecord): Promise<void> {
-		await this.#connection.sessionUpdate({
-			sessionId: record.session.sessionId,
-			update: {
-				sessionUpdate: "available_commands_update",
-				availableCommands: await this.#buildAvailableCommands(record.session),
-			},
-		});
-	}
-
-	/** Ensure cancellation clears a previously emitted busy/compacting phase even if abort never produces an end event. */
-	async #emitCancelledPromptIdleUpdate(record: ManagedSessionRecord): Promise<void> {
-		if (this.#connection.signal.aborted) {
-			return;
-		}
-		try {
-			await this.#connection.sessionUpdate({
-				sessionId: record.session.sessionId,
-				update: {
-					sessionUpdate: "session_info_update",
-					title: record.session.sessionName,
-					updatedAt: new Date().toISOString(),
-					_meta: {
-						gjcPhase: "idle",
-						running: false,
-						gjcRunning: false,
-					},
-				},
-			});
-		} catch (error) {
-			logger.warn("Failed to emit cancelled ACP prompt idle update", { error });
-		}
-	}
-
-	/**
-	 * Reload plugin/registry state for an ACP session. Mirrors the interactive
-	 * `/reload-plugins` and `/move` flows: invalidates the plugin-roots cache,
-	 * resets the capability cache, refreshes the session's slash-command state,
-	 * then re-advertises commands so the client sees newly installed/disabled
-	 * plugins.
-	 */
-	async #reloadPluginState(record: ManagedSessionRecord): Promise<void> {
-		const cwd = record.session.sessionManager.getCwd();
-		const projectPath = await resolveActiveProjectRegistryPath(cwd);
-		clearPluginRootsAndCaches(projectPath ? [projectPath] : undefined);
-		resetCapabilities();
-		const fileCommands = await loadSlashCommands({ cwd });
-		record.session.setSlashCommands(fileCommands);
-		await record.session.refreshSshTool({ activateIfAvailable: true });
-		await this.#emitAvailableCommandsUpdate(record);
-	}
-
-	async #emitEndOfTurnUpdates(record: ManagedSessionRecord): Promise<void> {
-		const sessionId = record.session.sessionId;
-
-		const contextUsage = record.session.getContextUsage();
-		if (contextUsage?.tokens != null) {
-			const usageStats = record.session.sessionManager.getUsageStatistics();
-			await this.#connection.sessionUpdate({
-				sessionId,
-				update: {
-					sessionUpdate: "usage_update",
-					size: contextUsage.contextWindow,
-					used: contextUsage.tokens,
-					cost: usageStats.cost > 0 ? { amount: usageStats.cost, currency: "USD" } : undefined,
-				},
-			});
-		}
-
-		await this.#connection.sessionUpdate({
-			sessionId,
-			update: {
-				sessionUpdate: "session_info_update",
-				title: record.session.sessionName,
-				updatedAt: new Date().toISOString(),
-				_meta: {
-					gjcPhase: "idle",
-					running: false,
-					gjcRunning: false,
-				},
-			},
-		});
-	}
-
-	#cloneUsageStatistics(usage: UsageStatistics): UsageStatistics {
-		return {
-			input: usage.input,
-			output: usage.output,
-			cacheRead: usage.cacheRead,
-			cacheWrite: usage.cacheWrite,
-			premiumRequests: usage.premiumRequests,
-			cost: usage.cost,
-		};
-	}
-
-	#buildTurnUsage(previous: UsageStatistics, current: UsageStatistics): Usage | undefined {
-		const inputTokens = Math.max(0, current.input - previous.input);
-		const outputTokens = Math.max(0, current.output - previous.output);
-		const cachedReadTokens = Math.max(0, current.cacheRead - previous.cacheRead);
-		const cachedWriteTokens = Math.max(0, current.cacheWrite - previous.cacheWrite);
-		const totalTokens = inputTokens + outputTokens + cachedReadTokens + cachedWriteTokens;
-
-		if (totalTokens === 0) {
-			return undefined;
-		}
-
-		const usage: Usage = {
-			inputTokens,
-			outputTokens,
-			totalTokens,
-		};
-		if (cachedReadTokens > 0) {
-			usage.cachedReadTokens = cachedReadTokens;
-		}
-		if (cachedWriteTokens > 0) {
-			usage.cachedWriteTokens = cachedWriteTokens;
-		}
-		return usage;
-	}
-
-	async #listStoredSessions(cwd?: string): Promise<StoredSessionInfo[]> {
-		const sessions = cwd ? await SessionManager.list(cwd) : await SessionManager.listAll();
-		return sessions.sort((left, right) => right.modified.getTime() - left.modified.getTime());
-	}
-
-	#parseCursor(cursor: string | undefined): number {
-		if (!cursor) {
-			return 0;
-		}
-		const parsed = Number.parseInt(cursor, 10);
-		if (!Number.isFinite(parsed) || parsed < 0) {
-			throw new Error(`Invalid ACP session cursor: ${cursor}`);
-		}
-		return parsed;
-	}
-
-	/**
-	 * Parse a scoped cursor of the form `${generation}:${offset}` and reject it when
-	 * its embedded generation no longer matches the current authority generation.
-	 * Unlike the cwd-less display cursor, the scoped cursor binds the page offset to
-	 * the exact authority snapshot that produced it, so a lifecycle invalidation
-	 * between pages is observable instead of silently rebuilt.
-	 */
-	#parseScopedCursor(cursor: string | undefined, currentGeneration: number): number {
-		if (!cursor) {
-			return 0;
-		}
-		const separator = cursor.indexOf(":");
-		if (separator <= 0) {
-			throw new Error(`Invalid ACP session cursor: ${cursor}`);
-		}
-		const generation = Number.parseInt(cursor.slice(0, separator), 10);
-		const offset = Number.parseInt(cursor.slice(separator + 1), 10);
-		if (!Number.isFinite(generation) || generation < 0 || !Number.isFinite(offset) || offset < 0) {
-			throw new Error(`Invalid ACP session cursor: ${cursor}`);
-		}
-		if (generation !== currentGeneration) {
-			throw new Error("ACP session list cursor is stale; the scoped session inventory changed");
-		}
-		return offset;
-	}
-
-	async #replaySessionHistory(record: ManagedSessionRecord): Promise<void> {
-		const cwd = record.session.sessionManager.getCwd();
-		const replayedToolCallIds = new Set<string>();
-		const replayedToolCallArgs = new Map<string, unknown>();
-		for (const message of record.session.sessionManager.buildSessionContext().messages as ReplayableMessage[]) {
-			for (const notification of this.#messageToReplayNotifications(
-				record.session.sessionId,
-				message,
-				cwd,
-				replayedToolCallIds,
-				replayedToolCallArgs,
-			)) {
-				await this.#connection.sessionUpdate(notification);
-			}
-		}
-	}
-
-	#messageToReplayNotifications(
-		sessionId: string,
-		message: ReplayableMessage,
-		cwd: string,
-		replayedToolCallIds: Set<string>,
-		replayedToolCallArgs: Map<string, unknown>,
-	): SessionNotification[] {
-		if (message.role === "assistant") {
-			return this.#replayAssistantMessage(sessionId, message, cwd, replayedToolCallIds, replayedToolCallArgs);
-		}
-		if (
-			message.role === "user" ||
-			message.role === "developer" ||
-			message.role === "custom" ||
-			message.role === "hookMessage"
-		) {
-			return this.#wrapReplayContent(
-				sessionId,
-				this.#extractReplayContent(message.content, undefined),
-				"user_message_chunk",
-				crypto.randomUUID(),
-			);
-		}
-		if (
-			message.role === "toolResult" &&
-			typeof message.toolCallId === "string" &&
-			typeof message.toolName === "string"
-		) {
-			return this.#replayToolResult(
-				sessionId,
-				cwd,
-				{
-					...message,
-					toolCallId: message.toolCallId,
-					toolName: message.toolName,
-				},
-				{
-					includeStart: !replayedToolCallIds.has(message.toolCallId),
-					toolArgs: replayedToolCallArgs.get(message.toolCallId),
-				},
-			);
-		}
-		if (
-			message.role === "bashExecution" ||
-			message.role === "pythonExecution" ||
-			message.role === "compactionSummary"
-		) {
-			return this.#wrapReplayContent(
-				sessionId,
-				this.#extractReplayContent(message.content, undefined),
-				"user_message_chunk",
-				crypto.randomUUID(),
-			);
-		}
-		return [];
-	}
-
-	#replayAssistantMessage(
-		sessionId: string,
-		message: ReplayableMessage,
-		cwd: string,
-		replayedToolCallIds: Set<string>,
-		replayedToolCallArgs: Map<string, unknown>,
-	): SessionNotification[] {
-		const notifications: SessionNotification[] = [];
-		const messageId = crypto.randomUUID();
-		if (Array.isArray(message.content)) {
-			for (const item of message.content) {
-				if (typeof item !== "object" || item === null || !("type" in item)) {
-					continue;
-				}
-				if (item.type === "text" && "text" in item && typeof item.text === "string" && item.text.length > 0) {
-					notifications.push({
-						sessionId,
-						update: {
-							sessionUpdate: "agent_message_chunk",
-							content: { type: "text", text: item.text },
-							messageId,
-						},
-					});
-					continue;
-				}
-				if (
-					item.type === "thinking" &&
-					"thinking" in item &&
-					typeof item.thinking === "string" &&
-					item.thinking.length > 0
-				) {
-					notifications.push({
-						sessionId,
-						update: {
-							sessionUpdate: "agent_thought_chunk",
-							content: { type: "text", text: item.thinking },
-							messageId,
-						},
-					});
-					continue;
-				}
-				const toolItem = item as ReplayableToolItem;
-				if (
-					(toolItem.type === "toolCall" || toolItem.type === "tool_use") &&
-					typeof toolItem.id === "string" &&
-					typeof toolItem.name === "string"
-				) {
-					const args = this.#buildReplayAssistantToolArgs(toolItem);
-					const update = buildToolCallStartUpdate({
-						toolCallId: toolItem.id,
-						toolName: toolItem.name,
-						args,
-						status: "completed",
-						cwd,
-					});
-					notifications.push({ sessionId, update });
-					replayedToolCallIds.add(toolItem.id);
-					replayedToolCallArgs.set(toolItem.id, args);
-				}
-			}
-		}
-		if (notifications.length === 0 && message.errorMessage && !isSilentAbort(message.errorMessage)) {
-			notifications.push({
-				sessionId,
-				update: {
-					sessionUpdate: "agent_message_chunk",
-					content: { type: "text", text: message.errorMessage },
-					messageId,
-				},
-			});
-		}
-		return notifications;
-	}
-
-	#buildReplayAssistantToolArgs(item: ReplayableToolItem): unknown {
-		if ("arguments" in item) {
-			return normalizeReplayToolArguments(item.arguments).args;
-		}
-		if (item.type === "tool_use" && "input" in item) {
-			return item.input;
-		}
-		return {};
-	}
-
-	#replayToolResult(
-		sessionId: string,
-		cwd: string,
-		message: Required<Pick<ReplayableMessage, "toolCallId" | "toolName">> & ReplayableMessage,
-		options: { includeStart?: boolean; toolArgs?: unknown } = {},
-	): SessionNotification[] {
-		const args = this.#buildReplayToolArgs(message.details);
-		const startEvent: AgentSessionEvent = {
-			type: "tool_execution_start",
-			toolCallId: message.toolCallId,
-			toolName: message.toolName,
-			args,
-		};
-		const endEvent: AgentSessionEvent = {
-			type: "tool_execution_end",
-			toolCallId: message.toolCallId,
-			toolName: message.toolName,
-			isError: message.isError === true,
-			result: {
-				content: message.content,
-				details: message.details,
-				errorMessage: message.errorMessage,
-			},
-		};
-		const notifications = mapAgentWireEventPayloadToAcpSessionUpdates(toAgentWireEventPayload(endEvent), sessionId, {
-			cwd,
-			getToolArgs: toolCallId => (toolCallId === message.toolCallId ? options.toolArgs : undefined),
-		});
-		if (options.includeStart === false) {
-			return notifications;
-		}
-		return [
-			...mapAgentWireEventPayloadToAcpSessionUpdates(toAgentWireEventPayload(startEvent), sessionId, { cwd }),
-			...notifications,
-		];
-	}
-
-	#buildReplayToolArgs(details: unknown): { path?: string } {
-		if (typeof details !== "object" || details === null || !("path" in details)) {
-			return {};
-		}
-		const value = (details as { path?: unknown }).path;
-		return typeof value === "string" && value.length > 0 ? { path: value } : {};
-	}
-
-	#wrapReplayContent(
-		sessionId: string,
-		content: PromptRequest["prompt"],
-		kind: "agent_message_chunk" | "user_message_chunk",
-		messageId: string,
-	): SessionNotification[] {
-		return content.map(block => ({
-			sessionId,
-			update: {
-				sessionUpdate: kind,
-				content: block,
-				messageId,
-			},
-		}));
-	}
-
-	#extractReplayContent(content: unknown, errorMessage: string | undefined): PromptRequest["prompt"] {
-		const replay: PromptRequest["prompt"] = [];
-		if (Array.isArray(content)) {
-			for (const item of content) {
-				if (typeof item !== "object" || item === null || !("type" in item)) {
-					continue;
-				}
-				if (item.type === "text" && "text" in item && typeof item.text === "string" && item.text.length > 0) {
-					replay.push({ type: "text", text: item.text });
-					continue;
-				}
-				if (
-					item.type === "image" &&
-					"data" in item &&
-					"mimeType" in item &&
-					typeof item.data === "string" &&
-					typeof item.mimeType === "string"
-				) {
-					replay.push({ type: "image", data: item.data, mimeType: item.mimeType });
-				}
-			}
-		}
-		if (replay.length === 0 && errorMessage) {
-			replay.push({ type: "text", text: errorMessage });
-		}
-		return replay;
-	}
-
-	async #configureExtensions(record: ManagedSessionRecord): Promise<void> {
-		if (record.extensionsConfigured) {
-			return;
-		}
-
-		const extensionRunner = record.session.extensionRunner;
-		if (!extensionRunner) {
-			record.extensionsConfigured = true;
-			return;
-		}
-
-		extensionRunner.initialize(
-			{
-				sendMessage: (message, options) => {
-					record.session.sendCustomMessage(message, options).catch((error: unknown) => {
-						logger.warn("ACP extension sendMessage failed", { error });
-					});
-				},
-				sendUserMessage: (content, options) => {
-					record.session.sendUserMessage(content, options).catch((error: unknown) => {
-						logger.warn("ACP extension sendUserMessage failed", { error });
-					});
-				},
-				appendEntry: (customType, data) => {
-					record.session.sessionManager.appendCustomEntry(customType, data);
-				},
-				setLabel: (targetId, label) => {
-					record.session.sessionManager.appendLabelChange(targetId, label);
-				},
-				getActiveTools: () => record.session.getActiveToolNames(),
-				getAllTools: () => record.session.getAllToolNames(),
-				setActiveTools: toolNames => record.session.setActiveToolsByName(toolNames),
-				getCommands: () => getSessionSlashCommands(record.session),
-				setModel: async model => {
-					const apiKey = await record.session.modelRegistry.getApiKey(model);
-					if (!apiKey) {
-						return false;
-					}
-					await record.session.setModel(model);
-					return true;
-				},
-				getThinkingLevel: () => record.session.thinkingLevel,
-				setThinkingLevel: level => record.session.setThinkingLevel(level),
-				getSessionName: () => record.session.sessionManager.getSessionName(),
-				setSessionName: async name => {
-					await record.session.sessionManager.setSessionName(name, "user");
-				},
-			},
-			{
-				getModel: () => record.session.model,
-				isIdle: () => !record.session.isStreaming,
-				abort: () => {
-					void record.session.abort();
-				},
-				hasPendingMessages: () => record.session.queuedMessageCount > 0,
-				shutdown: () => {},
-				getContextUsage: () => record.session.getContextUsage(),
-				getSystemPrompt: () => record.session.systemPrompt,
-				compact: instructionsOrOptions => runExtensionCompact(record.session, instructionsOrOptions),
-			},
-			{
-				getContextUsage: () => record.session.getContextUsage(),
-				waitForIdle: () => record.session.agent.waitForIdle(),
-				newSession: async options => {
-					const success = await record.session.newSession({ parentSession: options?.parentSession });
-					if (success && options?.setup) {
-						await options.setup(record.session.sessionManager);
-					}
-					return { cancelled: !success };
-				},
-				branch: async entryId => {
-					const result = await record.session.branch(entryId);
-					return { cancelled: result.cancelled };
-				},
-				navigateTree: async (targetId, options) => {
-					const result = await record.session.navigateTree(targetId, { summarize: options?.summarize });
-					return { cancelled: result.cancelled };
-				},
-				switchSession: async sessionPath => {
-					const success = await record.session.switchSession(sessionPath);
-					return { cancelled: !success };
-				},
-				reload: async () => {
-					await record.session.reload();
-				},
-				compact: instructionsOrOptions => runExtensionCompact(record.session, instructionsOrOptions),
-			},
-			// Per-session getter: `record.session.sessionId` reads through to
-			// `sessionManager.getSessionId()` (it's a getter, not a field), so an
-			// extension command that calls `ctx.newSession` / `ctx.switchSession`
-			// — both exposed in the block just above — mutates the underlying id
-			// mid-flight. Reading lazily on each elicitation matches every other
-			// `sessionUpdate` call in this file. Hoisting the factory to an
-			// `AcpAgent` field would still be wrong because it would also lose
-			// the per-`record` binding.
-			createAcpExtensionUiContext(this.#connection, () => record.session.sessionId, this.#clientCapabilities),
-		);
-		await extensionRunner.emit({ type: "session_start" });
-		record.extensionsConfigured = true;
-	}
-
-	async #configureMcpServers(record: ManagedSessionRecord, servers: McpServer[]): Promise<void> {
-		if (record.mcpManager) {
-			await record.mcpManager.disconnectAll();
-		}
-		if (servers.length === 0) {
-			record.mcpManager = undefined;
-			await record.session.refreshMCPTools([]);
-			return;
-		}
-
-		const manager = new MCPManager(record.session.sessionManager.getCwd());
-		const configs: MCPConfigMap = {};
-		const sources: MCPSourceMap = {};
-		for (const server of servers) {
-			configs[server.name] = this.#toMcpConfig(server);
-			sources[server.name] = {
-				provider: "acp",
-				providerName: "ACP Client",
-				path: `acp://${server.name}`,
-				level: "project",
-			};
-		}
-
-		const result = await manager.connectServers(configs, sources);
-		if (result.errors.size > 0) {
-			throw new Error(
-				Array.from(result.errors.entries())
-					.map(([name, message]) => `${name}: ${message}`)
-					.join("; "),
-			);
-		}
-
-		record.mcpManager = manager;
-		await record.session.refreshMCPTools(result.tools);
-	}
-
-	#toMcpConfig(server: McpServer): MCPServerConfig {
-		if ("command" in server) {
-			return {
-				type: "stdio",
-				command: server.command,
-				args: server.args,
-				env: this.#toNameValueMap(server.env),
-			};
-		}
-		if (server.type === "http") {
-			return {
-				type: "http",
-				url: server.url,
-				headers: this.#toNameValueMap(server.headers),
-			};
-		}
-		if (server.type === "sse") {
-			return {
-				type: "sse",
-				url: server.url,
-				headers: this.#toNameValueMap(server.headers),
-			};
-		}
-		throw new Error(`Unsupported ACP MCP transport: ${server.type}`);
-	}
-
-	#toNameValueMap(values: Array<{ name: string; value: string }>): { [name: string]: string } {
-		const mapped: { [name: string]: string } = {};
-		for (const value of values) {
-			mapped[value.name] = value.value;
-		}
-		return mapped;
-	}
-
-	async #closeManagedSession(sessionId: string, record: ManagedSessionRecord): Promise<void> {
-		this.#sessions.delete(sessionId);
-		await this.#cancelPromptForClose(record);
-		await this.#disposeSessionRecord(record);
-	}
-
-	async #cancelPromptForClose(record: ManagedSessionRecord): Promise<void> {
-		const promptTurn = record.promptTurn;
-		if (!isPromptTurnInFlight(promptTurn)) {
-			return;
-		}
-		const cleanup = promptTurn.cleanup ?? this.#beginCancelCleanup(record, promptTurn);
-		try {
-			await cleanup;
-		} catch (error) {
-			logger.warn("Failed to abort ACP prompt during session close", { error });
-		}
-	}
-	/**
-	 * Delete-specific strict prompt quiescence barrier. Mirrors the cancel setup of
-	 * {@link #cancelPromptForClose} but NEVER swallows abort/timeout failures, then
-	 * waits for full idle + async-delivery drain. A quiescence failure blocks the
-	 * destructive mutation that follows — it is not catch-and-logged. The best-effort
-	 * close path is preserved separately for nondestructive shutdown.
-	 */
-	async #quiesceForDelete(sessionId: string, record: ManagedSessionRecord): Promise<void> {
-		const promptTurn = record.promptTurn;
-		if (isPromptTurnInFlight(promptTurn)) {
-			const cleanup = promptTurn.cleanup ?? this.#beginCancelCleanup(record, promptTurn);
-			await cleanup;
-		}
-		await this.#waitForAcpPromptIdle(record);
-		// Explicit post-drain status check: the drain loop's boolean return is
-		// not trusted as proof. Treat a drain false/timeout/no-progress/max-pass
-		// as unproven and verify the owner-scoped delivery state directly. Any
-		// remaining queued/delivering work blocks the destructive mutation.
-		const delivery = record.session.getAsyncDeliveryStateForAcp();
-		if (delivery.queued > 0 || delivery.delivering) {
-			throw new Error(`ACP session ${sessionId} cannot be deleted: async delivery is not quiesced`);
-		}
-	}
-
-	/**
-	 * Record phase-aware same-connection retry evidence for an incomplete verified
-	 * delete. The transcript identity (carried by every cleanup_pending) is always
-	 * recorded so a retry can reject a replaced transcript; the artifacts identity
-	 * is recorded only at the artifacts phase.
-	 */
-	#recordPendingDeleteEvidence(sessionId: string, result: VerifiedSessionDeleteResult): void {
-		if (result.kind !== "cleanup_pending") {
-			return;
-		}
-		if (result.phase === "artifacts") {
-			this.#pendingDeleteEvidence.set(sessionId, {
-				transcriptIdentity: result.transcriptIdentity,
-				artifactsIdentity: result.artifactsIdentity,
-			});
-		} else {
-			// Transcript phase: artifacts were already removed successfully, so only
-			// the transcript identity remains for retry binding.
-			this.#pendingDeleteEvidence.set(sessionId, {
-				transcriptIdentity: result.transcriptIdentity,
-			});
-		}
-	}
-
-	/** Build the optional `expectedArtifactsIdentity` field for a retry target. */
-	#pendingArtifactsIdentity(sessionId: string): { expectedArtifactsIdentity?: SessionStorageFileIdentity } {
-		const pending = this.#pendingDeleteEvidence.get(sessionId);
-		return pending?.artifactsIdentity ? { expectedArtifactsIdentity: pending.artifactsIdentity } : {};
-	}
-
-	/**
-	 * Phase-aware retry gate: a preserved transcript identity must match the fresh
-	 * candidate's transcript identity before that candidate can authorize a
-	 * replacement. A mismatch (the transcript was externally replaced between the
-	 * cleanup_pending failure and the retry) fails closed — it never authorizes a
-	 * wrong mutation.
-	 */
-	#assertPendingTranscriptIdentity(sessionId: string, candidateIdentity: { dev: bigint; ino: bigint }): void {
-		const pending = this.#pendingDeleteEvidence.get(sessionId);
-		if (
-			pending &&
-			(pending.transcriptIdentity.dev !== candidateIdentity.dev ||
-				pending.transcriptIdentity.ino !== candidateIdentity.ino)
-		) {
-			throw new Error(
-				`ACP session ${sessionId} transcript identity changed since pending cleanup; replacement rejected`,
-			);
-		}
-	}
-
-	async #disposeSessionRecord(record: ManagedSessionRecord): Promise<void> {
-		record.lifetimeUnsubscribe?.();
-		if (record.mcpManager) {
-			try {
-				await record.mcpManager.disconnectAll();
-			} catch (error) {
-				logger.warn("Failed to disconnect ACP MCP servers", { error });
-			}
-			record.mcpManager = undefined;
-		}
-		try {
-			await record.session.dispose();
-		} catch (error) {
-			logger.warn("Failed to dispose ACP session", { error });
-		}
-	}
-
-	async #disposeStandaloneSession(session: AgentSession): Promise<void> {
-		try {
-			await session.dispose();
-		} catch (error) {
-			logger.warn("Failed to dispose ACP session", { error });
-		}
-	}
-
-	async #disposeAllSessions(): Promise<void> {
-		if (this.#disposePromise) {
-			await this.#disposePromise;
-			return;
-		}
-
-		this.#disposePromise = (async () => {
-			const records = Array.from(this.#sessions.entries());
-			this.#sessions.clear();
-			await Promise.all(
-				records.map(async ([sessionId, record]) => {
-					try {
-						await this.#cancelPromptForClose(record);
-						await this.#disposeSessionRecord(record);
-					} catch (error) {
-						logger.warn("Failed to clean up ACP session", { sessionId, error });
-					}
-				}),
-			);
-
-			const initialSession = this.#initialSession;
-			this.#initialSession = undefined;
-			if (initialSession) {
-				await this.#disposeStandaloneSession(initialSession);
-			}
-		})();
-
-		await this.#disposePromise;
 	}
 }