@namzu/sdk 2.0.0 → 3.1.0

package/src/runtime/query/iteration/stream-turn.ts

@@ -1,6 +1,17 @@
+import { type Span, SpanStatusCode } from '@opentelemetry/api'
 import { isProviderRequestError } from '../../../provider/errors.js'
+import { GENAI, NAMZU, chatSpanName, parentContext } from '../../../telemetry/attributes.js'
+import {
+	recordModelDuration,
+	recordTimeToFirstToken,
+	recordTokenUsage,
+} from '../../../telemetry/metrics.js'
+import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { mergeTokenUsage } from '../../../types/common/index.js'
+import { NamzuError } from '../../../types/errors/index.js'
 import type { ToolUseId } from '../../../types/ids/index.js'
+import type { Citation, ReasoningBlock } from '../../../types/message/index.js'
+import { ProviderError } from '../../../types/provider/errors.js'
 import type {
 	ChatCompletionResponse,
 	LLMProvider,
@@ -52,8 +63,8 @@ export interface StreamingTurnResult {
  * end-of-message. The bus's ephemeral filter (D1) ensures these
  * deltas never hit transcript.jsonl.
  *
- * Edge cases (codex A3, A4, A5):
- * - Stream ends without `finishReason` (anthropic-sdk-typescript#842
+ * Edge cases A3, A4, A5:
+ * - Stream ends without `finishReason` (a known vendor-SDK failure mode
  *   dropped message_stop): we still emit `message_completed` from a
  *   finally-style fall-through path with `stopReason: 'refusal'`.
  * - `tool_input_delta` with no `toolUseId` registered yet: we drop
@@ -64,6 +75,55 @@ export interface StreamingTurnResult {
  *   we instead synthesize a tool call with runtime truncation metadata
  *   so the executor can return a model-readable retry hint.
  */
+/**
+ * Close out a turn that was cancelled part-way through.
+ *
+ * Everything a completed turn records, for a turn that stopped early: the
+ * usage it did accumulate, the latency it did spend, the span it opened,
+ * and a terminal event closing the message it announced.
+ *
+ * The event is emitted directly rather than yielded because this runs
+ * inside a `catch` that is about to re-throw — a `yield` there would never
+ * be pulled. Nothing here is allowed to throw over the cancellation: a
+ * failure while tidying up must not replace the reason the turn ended.
+ */
+async function settleCancelledTurn(args: {
+	emitEvent: EmitEvent
+	runId: import('../../../types/ids/index.js').RunId
+	iteration: number
+	messageId: import('../../../types/ids/index.js').MessageId
+	usage: ChatCompletionResponse['usage']
+	text: string
+	model: string
+	startedAt: number
+	span: Span
+}): Promise<void> {
+	try {
+		recordTokenUsage(args.model, args.usage)
+		recordModelDuration(args.model, Date.now() - args.startedAt)
+		args.span.setAttributes({
+			[GENAI.USAGE_INPUT_TOKENS]: args.usage.promptTokens,
+			[GENAI.USAGE_OUTPUT_TOKENS]: args.usage.completionTokens,
+			[NAMZU.CACHE_READ_TOKENS]: args.usage.cachedTokens ?? 0,
+			[NAMZU.CACHE_WRITE_TOKENS]: args.usage.cacheWriteTokens ?? 0,
+		})
+		args.span.setStatus({ code: SpanStatusCode.OK })
+		args.span.end()
+
+		await args.emitEvent({
+			type: 'message_completed',
+			runId: args.runId,
+			iteration: args.iteration,
+			messageId: args.messageId,
+			stopReason: 'cancelled',
+			usage: args.usage,
+			content: args.text || undefined,
+		})
+	} catch {
+		// Best effort. The cancellation is the news.
+	}
+}
+
 export async function* streamProviderTurn(
 	provider: LLMProvider,
 	params: import('../../../types/provider/index.js').ChatCompletionParams,
@@ -73,7 +133,24 @@ export async function* streamProviderTurn(
 	iteration: number,
 	forceFinalize: boolean,
 	log: Logger,
+	parentSpan?: Span,
 ): AsyncGenerator<RunEvent, StreamingTurnResult> {
+	// The `chat {model}` span the GenAI conventions require. There was none:
+	// `chatSpanName` existed with zero call sites, so a trace carried no LLM
+	// latency at all and the token counts landed on the iteration span
+	// instead of the operation that produced them.
+	const callStartedAt = Date.now()
+	let firstDeltaSeen = false
+	const chatSpan = getTracer().startSpan(chatSpanName(params.model), {}, parentContext(parentSpan))
+	chatSpan.setAttributes({
+		[GENAI.OPERATION_NAME]: 'chat',
+		[GENAI.REQUEST_MODEL]: params.model,
+		...(params.temperature !== undefined
+			? { [GENAI.REQUEST_TEMPERATURE]: params.temperature }
+			: {}),
+		...(params.maxTokens !== undefined ? { [GENAI.REQUEST_MAX_TOKENS]: params.maxTokens } : {}),
+	})
+
 	const messageId = generateMessageId()
 	await emitEvent({ type: 'message_started', runId, iteration, messageId })
 	yield* drainPending()
@@ -112,12 +189,23 @@ export async function* streamProviderTurn(
 			inputTruncated: boolean
 		}
 	>()
-	let streamError: Error | undefined
+	// Reasoning blocks, bucketed by stream index exactly like tool calls.
+	// Order matters on replay — a provider wants the assistant turn echoed
+	// verbatim — so the map is drained in index order at the end.
+	const reasoningBuckets = new Map<
+		number,
+		{ type: 'thinking' | 'redacted_thinking'; text: string; signature?: string; encrypted?: string }
+	>()
+
+	// Citations arrive as their own deltas, in the order the model made
+	// them, and are collected verbatim: they are evidence, so reordering or
+	// de-duplicating them would edit the record the reader checks against.
+	const citations: Citation[] = []
 
-	const stream = provider.chatStream({
-		...params,
-		stream: true,
-	}) as AsyncIterable<StreamChunk>
+	let streamError: string | undefined
+	let streamCause: unknown
+
+	const stream = provider.chatStream({ ...params, stream: true }) as AsyncIterable<StreamChunk>
 
 	// Drive the stream manually so each `.next()` can be RACED against the run
 	// abort: a Stop tears the in-flight model request down (the provider got
@@ -148,12 +236,96 @@ export async function* streamProviderTurn(
 			const res = await (aborted ? Promise.race([next, aborted]) : next)
 			if (res.done) break
 			const chunk = res.value
+
+			// A backoff notice from the retry decorator, not output. Emitted
+			// and drained here because this is the only moment the consumer
+			// runs during a retry — the decorator is about to sleep, and it
+			// is that silence a host cannot otherwise distinguish from a
+			// hang. It carries no delta, so nothing below applies to it.
+			if (chunk.retry) {
+				await emitEvent({
+					type: 'provider_retry',
+					runId,
+					iteration,
+					attempt: chunk.retry.attempt,
+					maxRetries: chunk.retry.maxRetries,
+					delayMs: chunk.retry.delayMs,
+					code: chunk.retry.code,
+					...(chunk.retry.status !== undefined ? { status: chunk.retry.status } : {}),
+					serverDirected: chunk.retry.serverDirected,
+				})
+				yield* drainPending()
+				continue
+			}
+
 			if (chunk.error) {
-				streamError = new Error(`Provider stream error: ${chunk.error}`)
+				streamError = chunk.error
 				break
 			}
 			if (!id && chunk.id) id = chunk.id
 
+			// The first delta of the turn, of ANY kind — text, reasoning or a
+			// tool call. namzu streams, so perceived latency is dominated by
+			// this number, and the request histogram measures the whole call:
+			// it cannot tell a fast-first-token long generation from a
+			// stalled one, which is exactly the distinction a streaming UI is
+			// judged on. Keyed off the delta rather than the first chunk
+			// because a provider may open with a metadata-only frame.
+			if (
+				!firstDeltaSeen &&
+				(chunk.delta.content || chunk.delta.reasoning || chunk.delta.toolCalls?.length)
+			) {
+				firstDeltaSeen = true
+				recordTimeToFirstToken(params.model, Date.now() - callStartedAt)
+			}
+
+			if (chunk.delta.citation) citations.push(chunk.delta.citation)
+
+			const reasoning = chunk.delta.reasoning
+			if (reasoning) {
+				let bucket = reasoningBuckets.get(reasoning.index)
+				if (!bucket) {
+					bucket = { type: reasoning.type ?? 'thinking', text: '' }
+					reasoningBuckets.set(reasoning.index, bucket)
+					await emitEvent({
+						type: 'reasoning_started',
+						runId,
+						iteration,
+						messageId,
+						blockIndex: reasoning.index,
+						reasoningType: bucket.type,
+					})
+					yield* drainPending()
+				}
+				if (reasoning.type) bucket.type = reasoning.type
+				if (reasoning.signature) bucket.signature = reasoning.signature
+				if (reasoning.encrypted) bucket.encrypted = reasoning.encrypted
+				if (reasoning.text) {
+					bucket.text += reasoning.text
+					await emitEvent({
+						type: 'reasoning_delta',
+						runId,
+						iteration,
+						messageId,
+						blockIndex: reasoning.index,
+						text: reasoning.text,
+					})
+					yield* drainPending()
+				}
+				if (reasoning.done) {
+					await emitEvent({
+						type: 'reasoning_completed',
+						runId,
+						iteration,
+						messageId,
+						blockIndex: reasoning.index,
+						...(bucket.text ? { text: bucket.text } : {}),
+						signed: bucket.signature !== undefined,
+					})
+					yield* drainPending()
+				}
+			}
+
 			if (chunk.delta.content) {
 				textBuf += chunk.delta.content
 				await emitEvent({
@@ -255,8 +427,36 @@ export async function* streamProviderTurn(
 		// An abort tears the turn down: propagate it so the run loop settles the
 		// run as cancelled rather than recording a normal (errored) turn. Any
 		// other stream error is captured into the synthesized response as before.
-		if (signal?.aborted) throw err
-		streamError = err instanceof Error ? err : new Error(String(err))
+		if (signal?.aborted) {
+			// Settle what the turn already produced BEFORE unwinding. Throwing
+			// straight from here skipped everything below: the usage merged so
+			// far was discarded wholesale, so every cancelled turn
+			// under-reported its own cost; the span opened for this call was
+			// never ended, so it never exported at all; and a host consuming
+			// the message lifecycle saw a message begin and never end.
+			//
+			// The stream-ERROR path a few lines down already does exactly
+			// this. Cancel was the one exit that skipped it, which is the
+			// opposite of what its frequency deserves.
+			await settleCancelledTurn({
+				emitEvent,
+				runId,
+				iteration,
+				messageId,
+				usage,
+				text: textBuf,
+				model: params.model,
+				startedAt: callStartedAt,
+				span: chatSpan,
+			})
+			throw err
+		}
+		streamError = err instanceof Error ? err.message : String(err)
+		// Kept, not just its text. The classification a driver produced —
+		// which code, which status, whether repeating the call could work —
+		// is the whole basis for settling a transient fault as PAUSED rather
+		// than failed, and flattening it to a message threw all of it away.
+		streamCause = err
 	} finally {
 		if (onAbort) signal?.removeEventListener('abort', onAbort)
 		// Release the underlying connection on every exit (natural end, error,
@@ -270,7 +470,7 @@ export async function* streamProviderTurn(
 	// arrived — defensive against providers that don't yet emit it, and
 	// the load-bearing path when the provider stream ends with
 	// `stop_reason: "max_tokens"` mid-`input_json_delta`. In that case
-	// Anthropic's SSE never sends `content_block_stop` for the open
+	// A provider's stream never sends a block-stop for the open
 	// tool_use block: the upstream model ran out of completion tokens
 	// before it could close the JSON literal, so the buffered
 	// `argsBuf` ends with something like `"content":"…some prefix` —
@@ -347,7 +547,13 @@ export async function* streamProviderTurn(
 				name: b.name,
 				arguments: JSON.stringify(b.parsed ?? {}),
 			},
-			...(b.inputTruncated ? { metadata: { inputTruncated: true } } : {}),
+			// Carry the partial buffer alongside the flag. `arguments` is
+			// normalized to `{}` above, so without this the only record of
+			// what the model was actually saying is gone — and a
+			// `repairToolCall` hook has nothing to repair.
+			...(b.inputTruncated
+				? { metadata: { inputTruncated: true, partialArguments: b.argsBuf } }
+				: {}),
 		}))
 
 	const recoveredToolInputFromStreamError =
@@ -359,7 +565,7 @@ export async function* streamProviderTurn(
 		log.warn('provider stream failed after tool input; surfacing tool call to executor', {
 			runId,
 			iteration,
-			error: streamError?.message ?? 'provider stream failed',
+			error: streamError,
 			toolCallCount: toolCalls.length,
 		})
 	}
@@ -382,10 +588,49 @@ export async function* streamProviderTurn(
 	yield* drainPending()
 
 	if (streamError && !recoveredToolInputFromStreamError) {
-		if (isProviderRequestError(streamError)) throw streamError
-		throw new Error(`Provider stream error: ${streamError.message}`)
+		chatSpan.setStatus({ code: SpanStatusCode.ERROR, message: streamError })
+		chatSpan.end()
+
+		// A classified provider failure is rethrown AS ITSELF. Wrapping it in
+		// a fresh error dropped `retryable`, `status` and `retryAfterMs`,
+		// and `NamzuError`'s own default for `provider_error` is
+		// not-retryable — so a 429 that had exhausted its backoff settled the
+		// run FAILED, where the documented behaviour is a pause with a
+		// checkpoint to resume from. `toPlatformError` already projects this
+		// shape correctly; it was never reached.
+		//
+		// The asymmetry this fixes was visible: the same 529 raised inside
+		// the compaction verifier propagates untouched and DOES pause, so
+		// identical faults settled oppositely depending on whether compaction
+		// happened to run that iteration.
+		if (streamCause instanceof ProviderError) throw streamCause
+		// The newer classified shape carries the same guarantee, and the run
+		// boundary reads it to decide between a pause and a failure.
+		if (isProviderRequestError(streamCause)) throw streamCause
+
+		throw new NamzuError({
+			code: 'provider_error',
+			message: `Provider stream error: ${streamError}`,
+			details: { model: params.model },
+			// Even when the cause is not classified, keeping it means a host
+			// reading the chain sees what actually happened rather than a
+			// sentence about it.
+			...(streamCause !== undefined ? { cause: streamCause } : {}),
+		})
 	}
 
+	// Drained in stream-index order: the replay contract is about the
+	// original block order, and a Map preserves insertion order, not index
+	// order, when a provider interleaves blocks.
+	const reasoningBlocks: ReasoningBlock[] = [...reasoningBuckets.entries()]
+		.sort(([a], [b]) => a - b)
+		.map(([, bucket]) => ({
+			type: bucket.type,
+			...(bucket.text ? { text: bucket.text } : {}),
+			...(bucket.signature ? { signature: bucket.signature } : {}),
+			...(bucket.encrypted ? { encrypted: bucket.encrypted } : {}),
+		}))
+
 	const response: ChatCompletionResponse = {
 		id: id || messageId,
 		model: model || params.model,
@@ -393,9 +638,34 @@ export async function* streamProviderTurn(
 			role: 'assistant',
 			content: textBuf.length > 0 ? textBuf : null,
 			toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+			...(reasoningBlocks.length > 0 ? { reasoning: reasoningBlocks } : {}),
+			...(citations.length > 0 ? { citations } : {}),
 		},
 		finishReason: effectiveFinishReason,
 		usage,
 	}
+
+	// The same numbers as a MEASUREMENT, not only as a span attribute.
+	// A span answers "what happened in this run"; a metric answers "what is
+	// this costing across every run", and no amount of span attributes adds
+	// up to the second question without a trace backend willing to
+	// aggregate them.
+	recordTokenUsage(params.model, usage)
+	recordModelDuration(params.model, Date.now() - callStartedAt)
+
+	// Usage belongs on the span for the call that produced it, not on the
+	// iteration that happened to contain it.
+	chatSpan.setAttributes({
+		[GENAI.RESPONSE_MODEL]: response.model,
+		[GENAI.RESPONSE_ID]: response.id,
+		[GENAI.RESPONSE_FINISH_REASONS]: [response.finishReason],
+		[GENAI.USAGE_INPUT_TOKENS]: usage.promptTokens,
+		[GENAI.USAGE_OUTPUT_TOKENS]: usage.completionTokens,
+		[NAMZU.CACHE_READ_TOKENS]: usage.cachedTokens ?? 0,
+		[NAMZU.CACHE_WRITE_TOKENS]: usage.cacheWriteTokens ?? 0,
+	})
+	chatSpan.setStatus({ code: SpanStatusCode.OK })
+	chatSpan.end()
+
 	return { response, messageId }
 }

package/src/runtime/query/plugin-hooks.ts

@@ -1,3 +1,4 @@
+import { NamzuError } from '../../types/errors/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../../types/plugin/index.js'
 
 /**
@@ -17,11 +18,14 @@ export function applyLifecycleHookResults(
 			case 'continue':
 				continue
 			case 'error':
-				throw new Error(`Plugin hook ${event} reported error: ${result.message}`)
+				throw new NamzuError({
+					code: 'plugin_error',
+					message: `Plugin hook ${event} reported error: ${result.message}`,
+					details: { event },
+				})
 			case 'skip':
 			case 'modify':
 			case 'retry':
-			case 'resume':
 				throw new Error(
 					`Plugin hook ${event} returned unsupported action '${result.action}' for a lifecycle event`,
 				)

package/src/runtime/query/prompt.ts

@@ -60,9 +60,34 @@ IMPORTANT: Always use absolute paths based on the working directory above. Befor
 	return lines.join('\n')
 }
 
+/**
+ * Does this run have a tool that needs to know where it is?
+ *
+ * Decided from what a tool DECLARES — `category: 'filesystem'` or a
+ * `file_read` / `file_write` permission — not from its name.
+ *
+ * The name set alone was a real hole: a host registering a perfectly
+ * well-formed filesystem tool called `read_file` got no `<env>` block at
+ * all, so the model was never told the working directory and the host had
+ * to hand-encode the paths into its system prompt. The structured facts
+ * were right there on the `ToolDefinition` and the gate ignored them in
+ * favour of the four built-in names.
+ *
+ * The name set is kept as a fallback for tools that declare neither.
+ */
 function hasFilesystemTools(tools: ToolRegistryContract, allowedTools?: string[]): boolean {
 	const activeTools = allowedTools ?? tools.listNames()
-	return activeTools.some((name) => FILESYSTEM_TOOLS.has(name))
+	return activeTools.some((name) => {
+		if (FILESYSTEM_TOOLS.has(name)) return true
+		const tool = tools.get?.(name)
+		if (!tool) return false
+		if (tool.category === 'filesystem' || tool.category === 'shell') return true
+		return Boolean(
+			tool.permissions?.some(
+				(p) => p === 'file_read' || p === 'file_write' || p === 'shell_execute',
+			),
+		)
+	})
 }
 
 export class PromptBuilder {

package/src/runtime/query/question-park.ts

@@ -0,0 +1,120 @@
+import type { CheckpointId, HITLResumeDecision, UserQuestionData } from '../../types/hitl/index.js'
+
+/**
+ * Durability for a question raised from inside a tool.
+ *
+ * `ask_user_question` parked through the raw handler with a synthetic
+ * `cp_question_<toolUseId>` id that was never written anywhere. The
+ * checkpoint therefore did not exist: nothing on disk said a human owed
+ * this run an answer, `findPendingCheckpoint` could never return it, and a
+ * remote host could not even OBSERVE the question except through the
+ * in-process callback. Kill the process while somebody is looking at the
+ * question card and the answer can never be applied — the restore path
+ * strips the whole assistant turn, discarding work that sibling tools in
+ * the same batch had already finished, and re-bills the turn.
+ *
+ * Two halves, and the second is the one that was hard:
+ *
+ *  1. **Record.** Write a real checkpoint through the manager, so the park
+ *     is durable and visible on every surface a tool-review park is.
+ *  2. **Re-enter.** On resume, deliver the answer to the tool that asked
+ *     rather than re-asking. The batch is re-executed — which is how the
+ *     asking tool gets re-entered at all — and this registry is what makes
+ *     that re-entry return the recorded answer instead of parking again.
+ *     Siblings that already completed are answered from the transcript, so
+ *     re-execution costs nothing beyond the one tool that was waiting.
+ */
+export interface QuestionParkRecorder {
+	/**
+	 * Record the park and return the checkpoint id it was written under, or
+	 * `null` when it could not be recorded.
+	 *
+	 * `null` rather than a throw: an unrecorded park is a lost cross-process
+	 * handoff, not a reason to fail the tool. The in-process await is still
+	 * perfectly valid, and taking the run down would turn a durability
+	 * shortfall into an outage.
+	 */
+	record(question: UserQuestionData): Promise<CheckpointId | null>
+	/** Clear the park once an answer arrives, so a queue stops serving it. */
+	resolve(checkpointId: CheckpointId, decision: HITLResumeDecision): Promise<void>
+}
+
+/**
+ * A recorder whose backing store is attached later.
+ *
+ * The tool that asks is built before the run exists — an agent constructs
+ * its tool registry, and only then hands it to `query()`, which is where
+ * the checkpoint manager is created. Binding late is what lets the same
+ * tool instance be durable inside a run and inert outside one, without the
+ * tool builder needing to know about checkpoints at all.
+ *
+ * Unbound, `record` returns `null` and `resolve` is a no-op, which is
+ * exactly the previous behaviour: the in-process await still works, only
+ * the cross-process handoff is missing.
+ */
+export class QuestionParkBinding implements QuestionParkRecorder {
+	private backing?: QuestionParkRecorder
+
+	bind(recorder: QuestionParkRecorder): void {
+		this.backing = recorder
+	}
+
+	/** Detach when the run settles, so a later run cannot write into it. */
+	unbind(): void {
+		this.backing = undefined
+	}
+
+	async record(question: UserQuestionData): Promise<CheckpointId | null> {
+		return (await this.backing?.record(question)) ?? null
+	}
+
+	async resolve(checkpointId: CheckpointId, decision: HITLResumeDecision): Promise<void> {
+		await this.backing?.resolve(checkpointId, decision)
+	}
+}
+
+/**
+ * Answers carried into a resumed run, keyed by the `questionId` of the
+ * tool call that asked.
+ *
+ * Consulted before the park handler, so a re-entered `ask_user_question`
+ * returns the recorded answer rather than parking a second time — which
+ * would ask the user something they have already answered, and in a
+ * headless resume would deadlock or auto-answer with the no-consent
+ * sentinel.
+ *
+ * Each answer is consumed once. A tool that somehow asks the same question
+ * twice in one resumed run is asking a genuinely new question the second
+ * time, and answering it from a stale record would be fabricating consent.
+ */
+export class PendingAnswers {
+	private readonly answers = new Map<string, HITLResumeDecision>()
+
+	static from(decision: HITLResumeDecision | undefined): PendingAnswers {
+		const pending = new PendingAnswers()
+		if (decision?.action === 'answer_question' && decision.questionId !== undefined) {
+			pending.set(decision.questionId, decision)
+		}
+		return pending
+	}
+
+	set(questionId: string, decision: HITLResumeDecision): void {
+		this.answers.set(questionId, decision)
+	}
+
+	/** Take the answer for this question, removing it. */
+	take(questionId: string): HITLResumeDecision | undefined {
+		const answer = this.answers.get(questionId)
+		if (answer !== undefined) this.answers.delete(questionId)
+		return answer
+	}
+
+	/** Every recorded answer, for copying between instances. */
+	entries(): Iterable<[string, HITLResumeDecision]> {
+		return this.answers.entries()
+	}
+
+	get size(): number {
+		return this.answers.size
+	}
+}

package/src/runtime/query/result.ts

@@ -4,6 +4,9 @@ import type { RunPersistence } from '../../manager/run/persistence.js'
 import { isProviderRequestError } from '../../provider/errors.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import { GENAI, NAMZU } from '../../telemetry/attributes.js'
+import { explainError } from '../../types/errors/catalog.js'
+import { toPlatformError } from '../../types/errors/index.js'
+import type { CheckpointId } from '../../types/hitl/index.js'
 import type { Run, RunEvent } from '../../types/run/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import type { Logger } from '../../utils/logger.js'
@@ -16,6 +19,14 @@ export interface ResultAssemblerConfig {
 	log: Logger
 	emitEvent: EmitEvent
 	drainPending: () => Generator<RunEvent>
+	/**
+	 * The state a host should resume from if the run settles recoverably.
+	 *
+	 * A function rather than a value: checkpoints are written per iteration,
+	 * so the answer changes as the run proceeds and reading it at
+	 * construction would pin the first one forever.
+	 */
+	resumeCheckpointId?: () => CheckpointId | undefined
 }
 
 export class ResultAssembler {
@@ -62,6 +73,51 @@ export class ResultAssembler {
 	async *handleError(err: unknown, rootSpan: Span): AsyncGenerator<RunEvent> {
 		const { runMgr, planManager, log, emitEvent, drainPending } = this.config
 		const errorMessage = toErrorMessage(err)
+		// The classifier at the provider boundary already walked the cause
+		// chain over status, errno and `Retry-After`, so a fully-populated
+		// error arrives here — and used to be flattened to a string one line
+		// later, discarding every field of it. `toPlatformError` is the
+		// projection that was written for exactly this and had no callers.
+		const failure = toPlatformError(err)
+
+		// A transient failure that survived every in-turn recovery is not the
+		// same thing as a bad API key, and settling both as `failed` gave the
+		// host no way to tell them apart — recovery meant knowing about
+		// checkpoints and driving replay itself. The state is already there:
+		// checkpoints are written every iteration by default. Only the settle
+		// and the signal were missing.
+		const resumeFrom = failure.retryable ? this.config.resumeCheckpointId?.() : undefined
+		if (resumeFrom !== undefined) {
+			runMgr.setLastError(errorMessage)
+			runMgr.setStopReason('paused')
+
+			await emitEvent({
+				type: 'run_paused',
+				runId: runMgr.id,
+				checkpointId: resumeFrom,
+				reason: errorMessage,
+			})
+			yield* drainPending()
+
+			// OK, not ERROR: the run is resumable, and a span marked failed
+			// puts it in an error dashboard it does not belong in.
+			rootSpan.setAttributes({
+				[NAMZU.RUN_STATUS]: 'paused',
+				[NAMZU.ITERATION]: runMgr.currentIteration,
+			})
+			rootSpan.setStatus({ code: SpanStatusCode.OK })
+
+			log.warn('Run paused on a recoverable failure — resume from the checkpoint', {
+				runId: runMgr.id,
+				checkpointId: resumeFrom,
+				code: failure.code,
+				error: errorMessage,
+			})
+			return
+		}
+
+		// The driver's classification, carried onto the run so a host can
+		// branch on WHAT failed without re-parsing a sentence.
 		const providerError = isProviderRequestError(err)
 			? {
 					kind: err.kind,
@@ -76,11 +132,19 @@ export class ResultAssembler {
 			planManager.failPlan(errorMessage)
 		}
 
+		// The classification says what kind of failure it is; the catalog
+		// says what a person should do about it. Keeping them separate is the
+		// point — classification is structural and belongs at the boundary,
+		// remediation is editorial and belongs in a list a human appends to.
+		const explanation = explainError(err) ?? undefined
+
 		await emitEvent({
 			type: 'run_failed',
 			runId: runMgr.id,
 			error: errorMessage,
+			failure,
 			...(providerError ? { providerError } : {}),
+			...(explanation ? { explanation } : {}),
 		})
 		yield* drainPending()