@namzu/sdk 42.0.2 → 44.0.0

package/src/bridge/a2a/client.ts

@@ -234,7 +234,7 @@ function operationBoundary(options: {
  * and a protocol version this kernel does not implement means every
  * subsequent request is a guess. Both are found once, at wiring time, which
  * is the only moment a human is looking; degrade here and the failure moves
- * to the middle of a delegation with a run waiting on it.
+ * to the middle of a delegation with a turn waiting on it.
  *
  * The version comparison is on major.minor, not the patch. A2A is
  * pre-1.0, where the minor carries breaking changes — matching on the full
@@ -414,7 +414,7 @@ export class A2ADelegate implements Delegate {
 			// Refused at construction. `supportedInterfaces` is what the card
 			// exists to tell us, and a peer offering only gRPC is a peer this
 			// client cannot talk to — discovering that mid-delegation would
-			// waste a run's time on a wiring mistake.
+			// waste a turn's time on a wiring mistake.
 			throw new InvalidAgentCardError({
 				url: config.card.supportedInterfaces[0]?.url ?? '(no interface)',
 				reason: 'no jsonrpc interface; this client speaks jsonrpc only',

package/src/bridge/a2a/context.ts

@@ -0,0 +1,46 @@
+import type { SessionId } from '../../types/ids/index.js'
+import type { Origin } from '../../types/session/turn.js'
+import { type ExternalSessionLookup, resolveExternalSession } from '../external-session.js'
+
+/**
+ * An A2A `contextId`, resolved to the namzu session it names.
+ *
+ * A context is a session. An incoming id that is an existing session, or that
+ * a session already claimed, reaches that session; any other id creates one.
+ * The id is opaque: a legacy client that still sends its project UUID gets one
+ * session for that id, and the id is never read as a project. With no
+ * `contextId`, a new session is created and its id is the context id the host
+ * returns.
+ */
+export interface A2AContextResolution {
+	readonly sessionId: SessionId
+	/** The context id to put on every task and event: the peer's own, or the new session's id. */
+	readonly contextId: string
+	/** True when the host must create the session (its first turn records `origin`). */
+	readonly created: boolean
+	/** Present when `created`: record it on the new session's first turn. */
+	readonly origin?: Origin
+}
+
+export async function resolveA2AContext(
+	contextId: string | undefined,
+	index: ExternalSessionLookup,
+	options: { readonly newSessionId?: () => SessionId } = {},
+): Promise<A2AContextResolution> {
+	const resolution = await resolveExternalSession({
+		index,
+		protocol: 'a2a',
+		...(contextId !== undefined && { externalId: contextId }),
+		...(options.newSessionId !== undefined && { newSessionId: options.newSessionId }),
+	})
+	const echoed = contextId !== undefined && contextId.length > 0 ? contextId : resolution.sessionId
+	if (resolution.kind === 'existing') {
+		return { sessionId: resolution.sessionId, contextId: echoed, created: false }
+	}
+	return {
+		sessionId: resolution.sessionId,
+		contextId: echoed,
+		created: true,
+		origin: { ...resolution.origin, kind: 'prompt' },
+	}
+}

package/src/bridge/a2a/index.ts

@@ -1,17 +1,24 @@
 export { buildAgentCard } from './agent-card.js'
 
 export {
-	runToA2ATask,
+	mapTurnToA2ATask,
 	isTerminalState,
-	runStatusToA2AState,
-	a2aMessageToCreateRun,
-	type CreateRunFromA2A,
+	turnStatusToA2AState,
+	a2aMessageToCreateTurn,
+	type CreateTurnFromA2A,
+	type MapTurnToA2ATaskOptions,
 } from './task.js'
 
+export { resolveA2AContext, type A2AContextResolution } from './context.js'
+
 export {
 	messageToA2A,
 	extractTextFromA2AMessage,
 	a2aMessageToInput,
 } from './message.js'
 
-export { mapRunToA2AEvent, mapSessionToA2AEvent } from './mapper.js'
+export { mapTurnToA2AEvent, mapSessionToA2AEvent } from './mapper.js'
+
+// A host's JSON-RPC server maps a turn refused because another is active to
+// the A2A error of its choice, naming the active task (`activeTurnId`).
+export { isTurnInProgressError } from '../../types/session/turn.js'

package/src/bridge/a2a/mapper.ts

@@ -4,7 +4,7 @@ import type {
 	TaskStatusUpdateEvent,
 } from '../../types/a2a/index.js'
 
-import type { RunEvent } from '../../types/run/events.js'
+import type { SessionEvent } from '../../types/session/events.js'
 
 function statusEvent(
 	taskId: string,
@@ -39,30 +39,33 @@ function artifactEvent(
 	}
 }
 
-type A2ATransform<K extends RunEvent['type']> =
-	| ((event: Extract<RunEvent, { type: K }>, contextId?: string) => A2AStreamEvent | null)
+// An A2A task is one namzu turn: every mapped event's `taskId` is its
+// `turnId`, and each of them is an event that only happens inside a turn.
+// The context is the session.
+type A2ATransform<K extends SessionEvent['type']> =
+	| ((event: Extract<SessionEvent, { type: K }>, contextId: string) => A2AStreamEvent | null)
 	| null
 
 const MAPPING: {
-	[K in RunEvent['type']]: A2ATransform<K>
+	[K in SessionEvent['type']]: A2ATransform<K>
 } = {
 	// Internal cumulative admission ledger, not a public UI event.
 	tool_calls_admitted: null,
-	// Hosted activity is retained in the run log; A2A exposes the resulting answer.
+	// Hosted activity is retained in the session log; A2A exposes the resulting answer.
 	hosted_tool: null,
-	run_started: (e, ctx) => statusEvent(e.runId, 'running', false, ctx),
+	turn_started: (e, ctx) => statusEvent(e.turnId, 'running', false, ctx),
 
-	run_completed: (e, ctx) => {
-		const completedEvent = statusEvent(e.runId, 'completed', true, ctx, {
+	turn_completed: (e, ctx) => {
+		const completedEvent = statusEvent(e.turnId, 'completed', true, ctx, {
 			role: 'agent',
 			parts: [{ kind: 'text', text: e.result }],
 		})
 		return completedEvent
 	},
 
-	run_failed: (e, ctx) =>
+	turn_failed: (e, ctx) =>
 		statusEvent(
-			e.runId,
+			e.turnId,
 			'failed',
 			true,
 			ctx,
@@ -98,7 +101,7 @@ const MAPPING: {
 	approval_policy_changed: null,
 
 	iteration_started: (e, ctx) =>
-		statusEvent(e.runId, 'running', false, ctx, {
+		statusEvent(e.turnId, 'running', false, ctx, {
 			role: 'agent',
 			parts: [{ kind: 'text', text: `Iteration ${e.iteration} started` }],
 		}),
@@ -111,7 +114,7 @@ const MAPPING: {
 	// still running and this says why nothing is arriving. Reported as
 	// working rather than failed: the call has not given up.
 	provider_retry: (e, ctx) =>
-		statusEvent(e.runId, 'running', false, ctx, {
+		statusEvent(e.turnId, 'running', false, ctx, {
 			role: 'agent',
 			parts: [
 				{
@@ -123,9 +126,9 @@ const MAPPING: {
 
 	// A swap is news for a remote peer for the same reason it is news for a
 	// local operator: the answer arriving next was produced by a provider the
-	// peer did not ask for. Still `running` — the run did not fail, it moved.
+	// peer did not ask for. Still `running` — the turn did not fail, it moved.
 	provider_fallback: (e, ctx) =>
-		statusEvent(e.runId, 'running', false, ctx, {
+		statusEvent(e.turnId, 'running', false, ctx, {
 			role: 'agent',
 			parts: [
 				{
@@ -138,7 +141,7 @@ const MAPPING: {
 		}),
 
 	tool_completed: (e, ctx) =>
-		artifactEvent(e.runId, ctx, {
+		artifactEvent(e.turnId, ctx, {
 			artifactId: `tool-${e.toolName}-${Date.now()}`,
 			name: `${e.toolName} result`,
 			parts: [{ kind: 'text', text: e.result }],
@@ -150,7 +153,7 @@ const MAPPING: {
 		}),
 
 	user_question_asked: (e, ctx) =>
-		statusEvent(e.runId, 'input-required', false, ctx, {
+		statusEvent(e.turnId, 'input-required', false, ctx, {
 			role: 'agent',
 			parts: [
 				{ kind: 'text', text: e.question },
@@ -163,12 +166,12 @@ const MAPPING: {
 		}),
 
 	// The task leaves `input-required` by the next status event it emits;
-	// a second one here would only restate what the resumed run says.
+	// a second one here would only restate what the resumed turn says.
 	user_question_answered: null,
 
 	tool_review_requested: (e, ctx) => {
 		const toolNames = e.toolCalls.map((tc) => tc.name).join(', ')
-		return statusEvent(e.runId, 'input-required', false, ctx, {
+		return statusEvent(e.turnId, 'input-required', false, ctx, {
 			role: 'agent',
 			parts: [
 				{ kind: 'text', text: `Review requested for tools: ${toolNames}` },
@@ -188,7 +191,7 @@ const MAPPING: {
 	},
 
 	plan_ready: (e, ctx) =>
-		statusEvent(e.runId, 'input-required', false, ctx, {
+		statusEvent(e.turnId, 'input-required', false, ctx, {
 			role: 'agent',
 			parts: [
 				{ kind: 'text', text: `Plan ready: ${e.title}` },
@@ -209,15 +212,15 @@ const MAPPING: {
 			],
 		}),
 
-	run_paused: (e, ctx) =>
+	turn_paused: (e, ctx) =>
 		statusEvent(
-			e.runId,
+			e.turnId,
 			'input-required',
 			false,
 			ctx,
 			{
 				role: 'agent',
-				parts: [{ kind: 'text', text: `Run paused: ${e.reason}` }],
+				parts: [{ kind: 'text', text: `Turn paused: ${e.reason}` }],
 			},
 			// A remote host has the same recovery decision as a local one. The
 			// checkpoint is the address of that recovery; the classification tells
@@ -241,7 +244,7 @@ const MAPPING: {
 	// is tracking, and it is the largest single payload the kernel emits.
 	request_envelope: null,
 	// Declined. This carries whole message bodies including tool output, and
-	// a peer models a task lifecycle — shipping a run's deleted history over
+	// a peer models a task lifecycle — shipping a session's deleted history over
 	// an external wire by default is a disclosure nobody asked for.
 	compaction_shed: null,
 	compaction_completed: null,
@@ -249,7 +252,7 @@ const MAPPING: {
 	// strategies fired is a property of how it manages its own window, and a
 	// peer modelling a task lifecycle can act on none of them.
 	compaction_tool_results_cleared: null,
-	// What the run wrote to its own memory store is this runtime's business;
+	// What the turn wrote to its own memory store is this runtime's business;
 	// a peer sees the task's outcome, not its housekeeping.
 	memory_consolidated: null,
 	// A job's exit is housekeeping of this runtime's host; the peer sees the
@@ -259,7 +262,7 @@ const MAPPING: {
 	// manages its own context. A peer models a task lifecycle and cannot act on
 	// either outcome.
 	compaction_failed: null,
-	// A refusal is the run's own policy decision; the peer sees it in the
+	// A refusal is the turn's own policy decision; the peer sees it in the
 	// terminal task state, not as a separate signal.
 	guardrail_triggered: null,
 	// Reasoning is kernel-internal: an A2A peer models a task lifecycle,
@@ -270,7 +273,7 @@ const MAPPING: {
 	tool_executing: null,
 	tool_review_completed: null,
 	checkpoint_created: null,
-	run_resuming: null,
+	turn_resuming: null,
 	token_usage_updated: null,
 	activity_created: null,
 	activity_updated: null,
@@ -303,12 +306,11 @@ const MAPPING: {
 	sandbox_exec: null,
 	sandbox_destroyed: null,
 
-	// Sub-session lifecycle events (session-hierarchy.md §10.4). These are
-	// in-flight visibility signals for the kernel bus; the A2A bridge does not
-	// surface them today.
-	subsession_spawned: null,
-	subsession_messaged: null,
-	subsession_idled: null,
+	// Child-session lifecycle events: this runtime's division of labour, for
+	// the same reason as `agent_pending` above.
+	child_session_spawned: null,
+	child_session_messaged: null,
+	child_session_idled: null,
 
 	// v3 message + tool-input lifecycle (ses_001-tool-stream-events). A2A's
 	// status-update model is coarse-grained, so per-delta events are dropped
@@ -319,7 +321,7 @@ const MAPPING: {
 	text_delta: null,
 	message_completed: (e, ctx) => {
 		if (!e.content) return null
-		return statusEvent(e.runId, 'running', false, ctx, {
+		return statusEvent(e.turnId, 'running', false, ctx, {
 			role: 'agent',
 			parts: [{ kind: 'text', text: e.content }],
 		})
@@ -329,14 +331,22 @@ const MAPPING: {
 	tool_input_completed: null,
 }
 
-export function mapRunToA2AEvent(event: RunEvent, contextId?: string): A2AStreamEvent | null {
+/**
+ * One session event as an A2A stream event, or `null` for the events a peer
+ * modelling a task lifecycle has no use for.
+ *
+ * `taskId` is the event's turn. `contextId` is the session as the peer knows
+ * it: pass the peer's own context id when the session was reached through
+ * one; absent, the event's `sessionId` is used.
+ */
+export function mapTurnToA2AEvent(event: SessionEvent, contextId?: string): A2AStreamEvent | null {
 	const transform = MAPPING[event.type]
 	if (!transform) return null
-	return (transform as (event: RunEvent, contextId?: string) => A2AStreamEvent | null)(
+	return (transform as (event: SessionEvent, contextId: string) => A2AStreamEvent | null)(
 		event,
-		contextId,
+		contextId ?? event.sessionId,
 	)
 }
 
-/** @deprecated Use mapRunToA2AEvent */
-export const mapSessionToA2AEvent = mapRunToA2AEvent
+/** @deprecated Use mapTurnToA2AEvent */
+export const mapSessionToA2AEvent = mapTurnToA2AEvent

package/src/bridge/a2a/task.ts

@@ -1,5 +1,6 @@
-import { RUN_STATUS_TO_A2A, TERMINAL_STATES } from '../../constants/a2a/index.js'
-import type { RunConfig, WireRun, WireRunStatus } from '../../contracts/index.js'
+import { TERMINAL_STATES, TURN_STATUS_TO_A2A } from '../../constants/a2a/index.js'
+import type { WireTurnStatus } from '../../contracts/session/turn-status.js'
+import type { WireTurn, WireTurnConfig } from '../../contracts/session/turn.js'
 import type {
 	A2AArtifact,
 	A2AMessage,
@@ -9,81 +10,121 @@ import type {
 	A2ATaskStatus,
 } from '../../types/a2a/index.js'
 import type { Message } from '../../types/message/index.js'
+import type { ExternalRef, Origin } from '../../types/session/turn.js'
 import { extractTextFromA2AMessage, messageToA2A } from './message.js'
 
+// An A2A task is one namzu turn, and an A2A context is one namzu session. The
+// task's `id` is the turn id; its `contextId` names the session, either as the
+// session id itself or as the caller's own context id that was mapped onto it.
+
 export function isTerminalState(state: A2ATaskState): boolean {
 	return TERMINAL_STATES.has(state)
 }
 
-export function runStatusToA2AState(status: WireRunStatus): A2ATaskState {
-	return RUN_STATUS_TO_A2A[status]
+export function turnStatusToA2AState(status: WireTurnStatus): A2ATaskState {
+	return TURN_STATUS_TO_A2A[status]
 }
 
-function buildTaskStatus(run: WireRun): A2ATaskStatus {
-	const state = runStatusToA2AState(run.status)
-	const timestamp = run.completed_at ?? run.started_at ?? run.created_at
+function buildTaskStatus(turn: WireTurn): A2ATaskStatus {
+	const state = turnStatusToA2AState(turn.status)
+	const timestamp = turn.completed_at ?? turn.started_at ?? turn.created_at
 
-	const message: A2AMessage | undefined = run.result
-		? { role: 'agent', parts: [{ kind: 'text', text: run.result }] }
-		: run.last_error
-			? { role: 'agent', parts: [{ kind: 'text', text: run.last_error }] }
+	const message: A2AMessage | undefined = turn.result
+		? { role: 'agent', parts: [{ kind: 'text', text: turn.result }] }
+		: turn.last_error
+			? { role: 'agent', parts: [{ kind: 'text', text: turn.last_error }] }
 			: undefined
 
 	return { state, message, timestamp }
 }
 
-function buildArtifacts(run: WireRun): A2AArtifact[] | undefined {
-	if (!run.result) return undefined
+function buildArtifacts(turn: WireTurn): A2AArtifact[] | undefined {
+	if (!turn.result) return undefined
 
 	return [
 		{
-			artifactId: `${run.id}-result`,
+			artifactId: `${turn.turn_id}-result`,
 			name: 'Agent Response',
-			parts: [{ kind: 'text', text: run.result }],
+			parts: [{ kind: 'text', text: turn.result }],
 			metadata: {
-				model: run.model,
-				iterations: run.iterations,
-				duration_ms: run.duration_ms,
-				...(run.usage && {
-					input_tokens: run.usage.input_tokens,
-					output_tokens: run.usage.output_tokens,
-					total_cost_usd: run.usage.total_cost_usd,
+				model: turn.model,
+				iterations: turn.iterations,
+				duration_ms: turn.duration_ms,
+				...(turn.usage && {
+					input_tokens: turn.usage.input_tokens,
+					output_tokens: turn.usage.output_tokens,
+					total_cost_usd: turn.usage.total_cost_usd,
 				}),
 			},
 		},
 	]
 }
 
-export function runToA2ATask(run: WireRun, messages?: readonly Message[]): A2ATask {
+export interface MapTurnToA2ATaskOptions {
+	/**
+	 * The context id the peer addressed this session by, echoed back verbatim.
+	 * Defaults to the turn's `session_id`. Pass the peer's own id when the
+	 * session was reached through it, so the peer sees the id it sent.
+	 */
+	readonly contextId?: string
+}
+
+/**
+ * One turn as an A2A task: `id` is the turn, `contextId` the session.
+ *
+ * The context is never the project. A host that serves `tasks/get` or
+ * `tasks/list` reads the turns from `SessionIndex.listTurns` and hands each
+ * one here with the session's messages.
+ */
+export function mapTurnToA2ATask(
+	turn: WireTurn,
+	messages?: readonly Message[],
+	options: MapTurnToA2ATaskOptions = {},
+): A2ATask {
 	return {
-		id: run.id,
-		contextId: run.project_id ?? undefined,
-		status: buildTaskStatus(run),
+		id: turn.turn_id,
+		contextId: options.contextId ?? turn.session_id,
+		status: buildTaskStatus(turn),
 		history: messages?.map(messageToA2A),
-		artifacts: buildArtifacts(run),
+		artifacts: buildArtifacts(turn),
 		metadata: {
-			agent_id: run.agent_id,
-			agent_name: run.agent_name,
-			stop_reason: run.stop_reason,
+			agent_id: turn.agent_id,
+			agent_name: turn.agent_name,
+			stop_reason: turn.stop_reason,
 		},
 	}
 }
 
-export interface CreateRunFromA2A {
+/**
+ * What an incoming `message/send` asks for: a new turn of one session.
+ *
+ * `contextId` is the peer's own name for the session, verbatim. It is any
+ * string and is never read as a namzu id or a project id: the project comes
+ * from the host's configuration. A host resolves it with
+ * `resolveA2AContext` (an existing session, or a new one), and starts the turn
+ * with `origin`, which is how the mapping reaches the session log and so
+ * survives an index rebuild.
+ */
+export interface CreateTurnFromA2A {
 	readonly agentId: string
 	readonly input: string
-	readonly projectId?: string
-	readonly config: RunConfig
+	/** The peer's context id, when it sent one. Absent means a new session. */
+	readonly contextId?: string
+	/** The ref the index resolves `contextId` through: `a2a` / `context`. */
+	readonly externalRef?: ExternalRef
+	/** Recorded on the turn (and on the session when the turn creates it). */
+	readonly origin: Origin
+	readonly config: WireTurnConfig
 }
 
-export function a2aMessageToCreateRun(
+export function a2aMessageToCreateTurn(
 	agentId: string,
 	params: A2AMessageSendParams,
-): CreateRunFromA2A {
+): CreateTurnFromA2A {
 	const input = extractTextFromA2AMessage(params.message)
 	const meta = params.metadata ?? {}
 
-	const config: RunConfig = {
+	const config: WireTurnConfig = {
 		...(typeof meta.model === 'string' && { model: meta.model }),
 		...(typeof meta.tokenBudget === 'number' && { tokenBudget: meta.tokenBudget }),
 		...(typeof meta.timeoutMs === 'number' && { timeoutMs: meta.timeoutMs }),
@@ -97,10 +138,23 @@ export function a2aMessageToCreateRun(
 		...(typeof meta.systemPrompt === 'string' && { systemPrompt: meta.systemPrompt }),
 	}
 
+	const contextId =
+		typeof params.contextId === 'string' && params.contextId.length > 0
+			? params.contextId
+			: undefined
+
 	return {
 		agentId,
 		input,
-		projectId: params.contextId,
+		...(contextId !== undefined && {
+			contextId,
+			externalRef: { protocol: 'a2a', kind: 'context', externalId: contextId },
+		}),
+		origin: {
+			protocol: 'a2a',
+			kind: 'prompt',
+			...(contextId !== undefined && { externalSessionId: contextId }),
+		},
 		config,
 	}
 }

package/src/bridge/acp/permission.ts

@@ -6,7 +6,7 @@ import type { HITLResumeDecision, ToolCallSummary } from '../../types/hitl/index
  * The kernel's own `ToolCallSummary`, not a re-declared one: this is the
  * shape the HITL path already produces, and a copy would be a second
  * definition of "which calls am I being asked about" that can drift from the
- * one the run actually parked on.
+ * one the turn actually parked on.
  */
 export interface AcpPermissionRequest {
 	readonly sessionId: string
@@ -19,7 +19,7 @@ export interface AcpPermissionRequest {
  * Three outcomes, matching what a human can actually mean about a batch of
  * calls: run it, run it and stop asking, or do not run it and here is why.
  * `reject` carries optional feedback because a denial with a reason is the
- * one a model can act on — "no, use the staging bucket" redirects a run,
+ * one a model can act on — "no, use the staging bucket" redirects a turn,
  * where a bare denial only ends it.
  */
 export type AcpPermissionOutcome =

package/src/bridge/acp/server.ts

@@ -25,7 +25,9 @@ import type {
 	AcpSessionUpdate,
 } from '../../types/acp/index.js'
 import type { MCPJsonRpcMessage, MCPTransport } from '../../types/connector/mcp.js'
-import type { RunEvent } from '../../types/run/events.js'
+import type { SessionEvent } from '../../types/session/events.js'
+import { isTurnInProgressError } from '../../types/session/turn.js'
+import { generateSessionId } from '../../utils/id.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import type { AcpClientFilesystem } from './filesystem.js'
 import type {
@@ -61,7 +63,13 @@ import { toAcpSessionUpdate, toAcpStopReason } from './update.js'
 /** What the bridge needs from the runtime, taken as an interface. */
 export interface AcpAgentGateway {
 	/**
-	 * Run one prompt, streaming events, and resolve with the stop reason.
+	 * Run one prompt as one turn of the session, streaming its events, and
+	 * resolve with the stop reason.
+	 *
+	 * A session has one active turn at a time. A gateway whose session log
+	 * refuses the turn because another is active (in this process or another)
+	 * throws the `TurnInProgressError`; the bridge answers the prompt with
+	 * `INVALID_REQUEST` naming the active turn.
 	 *
 	 * Deliberately not `AgentManagerContract` itself. This bridge needs one
 	 * verb, and a session front end holding the whole manager could cancel
@@ -73,7 +81,7 @@ export interface AcpAgentGateway {
 		readonly sessionId: string
 		readonly prompt: string
 		readonly cwd: string
-		readonly onEvent: (event: RunEvent) => void
+		readonly onEvent: (event: SessionEvent) => void
 		readonly signal: AbortSignal
 		/**
 		 * Ask the human in front of the client about a tool batch.
@@ -95,7 +103,7 @@ export interface AcpAgentGateway {
 	}): Promise<{
 		readonly stopReason?: string
 		/**
-		 * The exact conversation to use for the next prompt, after the run has
+		 * The exact conversation to use for the next prompt, after the turn has
 		 * settled. Omit it when the gateway does not own durable history.
 		 */
 		readonly history?: readonly unknown[]
@@ -107,8 +115,13 @@ export interface AcpAgentGateway {
 	 * Optional: a gateway with no session store cannot resume, and saying so
 	 * by not implementing this is better than returning an empty history that
 	 * a client cannot tell apart from a session that really had no turns.
+	 *
+	 * Resolves `undefined` when the store has no session by that id, which
+	 * the bridge answers with `INVALID_PARAMS` naming the id. The id is the
+	 * client's and may be any string: a namzu session id, or one the gateway
+	 * maps to a session through the index's `acp` / `session` refs.
 	 */
-	load?(sessionId: string): Promise<readonly unknown[]>
+	load?(sessionId: string): Promise<readonly unknown[] | undefined>
 }
 
 export interface AcpServerOptions {
@@ -124,7 +137,11 @@ export interface AcpServerOptions {
 	readonly commands: HostCommandRegistry
 	readonly presenter: ToolPresenter
 	readonly agentInfo: { readonly name: string; readonly version: string }
-	/** Injectable so a test does not depend on a random id. */
+	/**
+	 * The id `session/new` answers with. Defaults to a new namzu session id
+	 * (UUIDv7). A host may return any string; the bridge treats it as opaque,
+	 * and injecting it also keeps a test off a random id.
+	 */
 	readonly newSessionId?: () => string
 	readonly log?: Logger
 }
@@ -169,7 +186,6 @@ export class ACPServer {
 	private initialized = false
 	private stopped = false
 	private clientCapabilities: readonly string[] = []
-	private sessionSeq = 0
 
 	/**
 	 * The method table, authored INDEPENDENTLY of `ACP_METHODS`.
@@ -231,7 +247,7 @@ export class ACPServer {
 	 * Ask the client something and wait for its answer.
 	 *
 	 * The direction this bridge did not have. A notification is fire and
-	 * forget; a permission prompt is a question the run cannot proceed past,
+	 * forget; a permission prompt is a question the turn cannot proceed past,
 	 * so it needs an id, a place to park the promise, and a `dispatch` that
 	 * recognises a response frame.
 	 */
@@ -277,7 +293,7 @@ export class ACPServer {
 			// A frame with no method is the client ANSWERING something this side
 			// asked. Before permission requests existed there was nothing out on
 			// the wire, so ignoring it was right; now dropping it would leave the
-			// asker waiting forever and the run parked with nobody coming.
+			// asker waiting forever and the turn parked with nobody coming.
 			if (message.id !== undefined && this.pending.has(message.id)) {
 				const waiting = this.pending.get(message.id)
 				if (message.error) {
@@ -402,6 +418,12 @@ export class ACPServer {
 		const token = this.reserveSessionId(params.sessionId)
 		try {
 			const history = await this.options.gateway.load(params.sessionId)
+			if (history === undefined) {
+				throw new AcpError(
+					ACP_ERROR_CODES.INVALID_PARAMS,
+					`There is no session "${params.sessionId}" to load. Create a new session instead.`,
+				)
+			}
 			if (!Array.isArray(history)) {
 				throw new AcpError(
 					ACP_ERROR_CODES.INTERNAL_ERROR,
@@ -435,9 +457,12 @@ export class ACPServer {
 			return { sessionId, token: this.reserveSessionId(sessionId) }
 		}
 
+		// A namzu session id, so the gateway can open the session log under the
+		// very id the client holds. A collision with an open or reserved id is
+		// astronomically unlikely, and minting again is cheaper than reasoning
+		// about it.
 		for (;;) {
-			this.sessionSeq += 1
-			const sessionId = `acp_${this.sessionSeq}`
+			const sessionId: string = generateSessionId()
 			if (this.sessions.has(sessionId) || this.reservedSessionIds.has(sessionId)) continue
 			return { sessionId, token: this.reserveSessionId(sessionId) }
 		}
@@ -550,6 +575,15 @@ export class ACPServer {
 			}
 		} catch (error) {
 			if (controller.signal.aborted) return { stopReason: 'cancelled' }
+			// The session log refused the turn: another one is active, perhaps
+			// started by another process on the same session. A client error, not
+			// an internal one, and it says what to do.
+			if (isTurnInProgressError(error)) {
+				throw new AcpError(
+					ACP_ERROR_CODES.INVALID_REQUEST,
+					`Session "${params.sessionId}" already has an active turn (${error.activeTurnId}, ${error.state}). Wait for it to settle, or resume or abandon it, before sending another prompt.`,
+				)
+			}
 			throw error
 		} finally {
 			session.promptInFlight = false