@namzu/sdk 30.2.0 → 31.0.0

package/src/runtime/query/index.ts

@@ -8,7 +8,11 @@ import {
 } from '../../advisory/index.js'
 import { drainQueuedMessages } from '../../agents/handle.js'
 import { AuthorizationGate } from '../../authorization/gate.js'
-import { findDanglingMessages, removeDanglingMessages } from '../../compaction/dangling.js'
+import {
+	type ToolHistoryRepairReport,
+	repairToolMessageHistory,
+	toolHistoryRepairChanged,
+} from '../../compaction/dangling.js'
 import { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
 import type { ContextReducer } from '../../compaction/reducer.js'
@@ -26,6 +30,7 @@ import {
 	type ServingMember,
 	withProviderFallback,
 } from '../../provider/fallback.js'
+import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../../provider/idle-timeout.js'
 import { type ProviderRetryConfig, withProviderRetry } from '../../provider/retry.js'
 import { DefaultFilesystemMigrator, loggingMigrationSink } from '../../session/migration/index.js'
 import type { PathBuilder } from '../../session/workspace/path-builder.js'
@@ -37,6 +42,7 @@ import {
 	parentContext,
 	serializeSpan,
 } from '../../telemetry/attributes.js'
+import type { SerializedSpanContext } from '../../telemetry/attributes.js'
 import { recordRunDuration } from '../../telemetry/metrics.js'
 import { getTracer } from '../../telemetry/runtime-accessors.js'
 import { buildAdvisoryTools } from '../../tools/advisory/index.js'
@@ -61,7 +67,12 @@ import {
 } from '../../types/hitl/index.js'
 import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
-import { type Message, createSystemMessage } from '../../types/message/index.js'
+import {
+	type AssistantMessage,
+	type Message,
+	type UserMessage,
+	createSystemMessage,
+} from '../../types/message/index.js'
 import type { AgentPersona } from '../../types/persona/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
@@ -81,6 +92,7 @@ import type {
 } from '../../types/run/index.js'
 import type { PromoteMemory } from '../../types/run/memory-promotion.js'
 import { memoryCandidateFor } from '../../types/run/memory-promotion.js'
+import type { RunState } from '../../types/run/state.js'
 import type { RunStore } from '../../types/run/store.js'
 import type { Sandbox, SandboxProvider } from '../../types/sandbox/index.js'
 import type { ProjectId, TopicId } from '../../types/session/ids.js'
@@ -107,11 +119,18 @@ import { IterationOrchestrator } from './iteration/index.js'
 import { isCompactionMessage } from './iteration/phases/compaction.js'
 import { isWorkingMemoryMessage } from './iteration/phases/working-memory.js'
 import { applyLifecycleHookResults } from './plugin-hooks.js'
+import {
+	type ProjectInstructionContext,
+	awaitProjectInstructionCallback,
+	collapseProjectInstructionSnapshots,
+	replaceProjectInstructionSnapshot,
+} from './project-instructions.js'
 import type { PromptCache } from './prompt-cache.js'
 import { PromptBuilder } from './prompt.js'
 import type { PromptSegments } from './prompt.js'
 import { PendingAnswers, QuestionParkBinding } from './question-park.js'
 import { RepeatCallTracker } from './repeat-call.js'
+import { resolveMaxRequestRichContentBytes } from './request-rich-content.js'
 import { ResultAssembler } from './result.js'
 import {
 	type PendingResumePlan,
@@ -121,6 +140,11 @@ import {
 	recoverCompletedCalls,
 	unansweredToolCalls,
 } from './resume-pending.js'
+import {
+	acquireSandbox,
+	resolveSandboxTeardownTimeoutMs,
+	teardownSandbox,
+} from './sandbox-lifecycle.js'
 import type { SteeringChannel } from './steering.js'
 import { ToolGrantSet } from './tool-grants.js'
 import { createToolPause } from './tool-pause.js'
@@ -243,7 +267,9 @@ export interface QueryParams {
 	 * Host-owned so it can outlive one run — a registry built per run could
 	 * never be the thing that kills a run's jobs when the run is already
 	 * gone. This run's jobs are torn down in the `finally` below; another
-	 * run's are untouched.
+	 * run's are untouched. The registry launches host processes, so a run
+	 * that also supplies a {@link sandboxProvider} does not expose it to tools:
+	 * background execution is refused rather than silently bypassing the sandbox.
 	 */
 	backgroundJobs?: BackgroundJobRegistry
 
@@ -615,6 +641,12 @@ export interface QueryParams {
 	 */
 	inboundMessages?: () => import('../../types/message/index.js').Message[]
 
+	/**
+	 * Live project policy for this run. Unlike `inboundMessages`, snapshot
+	 * replacement is durable state and never implies another model turn.
+	 */
+	projectInstructionContext?: ProjectInstructionContext
+
 	/**
 	 * Where this conversation's durable state lives.
 	 *
@@ -631,7 +663,9 @@ export interface QueryParams {
 	 * approval hook, and that is not this function. Sharing the object is
 	 * what lets an approved plan leave plan mode in the SAME run.
 	 */
-	permissionModeRef?: { current: import('../../types/permission/index.js').PermissionMode }
+	permissionModeRef?: {
+		current: import('../../types/permission/index.js').PermissionMode
+	}
 
 	/**
 	 * A name for the policy `resumeHandler` implements.
@@ -700,6 +734,16 @@ export interface QueryParams {
 
 	sandboxProvider?: SandboxProvider
 
+	/**
+	 * Maximum time the run waits for sandbox teardown, in milliseconds.
+	 *
+	 * Defaults to 30 seconds. A fresh private signal is passed to `destroy()`;
+	 * the run also races the returned promise so an implementation that ignores
+	 * cancellation cannot pin `drainQuery()`. Set `0` to retain an unbounded
+	 * teardown wait.
+	 */
+	sandboxTeardownTimeoutMs?: number
+
 	invocationState?: InvocationState
 
 	/**
@@ -715,6 +759,12 @@ export interface QueryParams {
 	strictCapabilities?: boolean
 }
 
+type SelectedResumeState = RunState & {
+	readonly checkpointId: CheckpointId
+	readonly traceContext?: SerializedSpanContext
+}
+const selectedResumeStates = new WeakMap<QueryParams, SelectedResumeState>()
+
 /**
  * Refuse to price a run whose tokens two differently-priced members may produce.
  *
@@ -810,11 +860,49 @@ async function resolveProviderContextWindow(
 	provider: LLMProvider,
 	model: string | undefined,
 	signal: AbortSignal | undefined,
+	timeoutMs: number,
 	log: Logger,
 ): Promise<number | undefined> {
 	if (!provider.resolveContextWindow || !model) return undefined
+	if (signal?.aborted) return undefined
+
+	// The resolver is an optional optimisation that runs before RunContext
+	// owns its child controller. Give it a private deadline signal and fuse
+	// caller cancellation into that transport in the safe direction: neither
+	// outcome aborts the caller's controller. Passing a signal is necessary
+	// but not sufficient, because a third-party driver can accept it and still
+	// leave its promise pending; the race below makes fallback independent of
+	// driver cooperation. Promise.race keeps the losing provider promise
+	// observed, so a later rejection cannot become unhandled.
+	const deadline = new AbortController()
+	const resolverSignal = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal
+	const interrupted = Symbol('provider-context-window-interrupted')
+	let onAbort: (() => void) | undefined
+	const interruption = new Promise<typeof interrupted>((resolve) => {
+		onAbort = () => resolve(interrupted)
+		resolverSignal.addEventListener('abort', onAbort, { once: true })
+	})
+	// Wire and directory config validation already limit this field to one
+	// hour. The clamp also keeps a direct QueryParams caller from triggering
+	// Node's >2^31-1 one-millisecond timer coercion and turning a huge run
+	// budget into an immediate metadata fallback.
+	const deadlineMs = Math.min(Math.max(0, timeoutMs), 2_147_483_647)
+	const timer = setTimeout(() => {
+		deadline.abort(new Error(`Provider context-window lookup exceeded ${deadlineMs}ms`))
+	}, deadlineMs)
+
 	try {
-		const reported = await provider.resolveContextWindow(model, signal)
+		const resolution = provider.resolveContextWindow(model, resolverSignal)
+		const reported = await Promise.race([resolution, interruption])
+		if (reported === interrupted) {
+			if (deadline.signal.aborted) {
+				log.debug('Provider context-window lookup timed out; using the table', {
+					'namzu.model.id': model,
+					'namzu.runtime.timeout_ms': deadlineMs,
+				})
+			}
+			return undefined
+		}
 		return typeof reported === 'number' && reported > 0 ? reported : undefined
 	} catch (err) {
 		log.debug('Provider could not report a context window; using the table', {
@@ -822,10 +910,76 @@ async function resolveProviderContextWindow(
 			'namzu.error.message': toErrorMessage(err),
 		})
 		return undefined
+	} finally {
+		clearTimeout(timer)
+		if (onAbort) resolverSignal.removeEventListener('abort', onAbort)
+	}
+}
+
+interface PendingHistoryRepairEvent {
+	readonly source: 'fresh-history' | 'abandoned-checkpoint'
+	readonly report: ToolHistoryRepairReport
+}
+
+/**
+ * Project historical system messages exactly as a new run will persist them.
+ *
+ * Arbitrary historical prompt floors are rebuilt for this run and therefore
+ * never reach its provider-bound conversation. Repair must happen AFTER that
+ * removal: treating a soon-to-be-dropped system message as a tool-result
+ * boundary can replace an exact real result with an invented unknown outcome.
+ * The two state-bearing system forms survive; fresh inherited compaction is
+ * pinned until this run can prove it reconstructed equivalent state.
+ */
+function projectStateBearingHistory(
+	messages: readonly Message[],
+	options: { readonly pinCompaction: boolean },
+): Message[] {
+	const projected: Message[] = []
+	for (const message of messages) {
+		if (message.role !== 'system') {
+			projected.push(message)
+			continue
+		}
+		if (isCompactionMessage(message.content)) {
+			projected.push(options.pinCompaction ? { ...message, retain: true } : message)
+		} else if (isWorkingMemoryMessage(message.content)) {
+			projected.push(message)
+		}
 	}
+	return collapseProjectInstructionSnapshots(projected)
+}
+
+/**
+ * Remove the incomplete turn still owned by a durable resume plan.
+ *
+ * The plan re-appends the exact assistant with real/denied/recovered results.
+ * Generic history repair must not synthesize a competing result first. Any
+ * partial results for that turn are removed too; the executor reconstructs
+ * them from the durable run transcript through `recoveredResults`.
+ */
+function withoutOwnedResumeTurn(
+	messages: readonly Message[],
+	assistant: AssistantMessage,
+): Message[] {
+	const ownerIndex = messages.lastIndexOf(assistant)
+	if (ownerIndex < 0) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: 'A pending checkpoint resume plan does not own a message in its checkpoint.',
+		})
+	}
+	const ownedIds = new Set((assistant.toolCalls ?? []).map((call) => call.id))
+	return messages.filter(
+		(message, index) =>
+			index !== ownerIndex &&
+			!(index > ownerIndex && message.role === 'tool' && ownedIds.has(message.toolCallId)),
+	)
 }
 
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
+	const selectedResumeState = selectedResumeStates.get(params)
+	selectedResumeStates.delete(params)
 	// Resolved at the DOOR, before a run id exists or a logger is built.
 	// A caller who set both spellings of a renamed field has a config bug,
 	// and refusing it here costs them nothing; refusing it at the read site
@@ -833,6 +987,20 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// provider call has been paid for and a partial transcript written.
 	const promptCache = params.promptCache
 	const taskScheduler = params.taskScheduler
+	const streamIdleTimeoutMs = resolveStreamIdleTimeoutMs(params.runConfig.streamIdleTimeoutMs)
+	const maxRequestRichContentBytes = resolveMaxRequestRichContentBytes(
+		params.runConfig.maxRequestRichContentBytes,
+	)
+	const sandboxTeardownTimeoutMs = resolveSandboxTeardownTimeoutMs(params.sandboxTeardownTimeoutMs)
+	// Persist the EFFECTIVE value, not only an override. A run replayed after a
+	// later release must be able to explain which liveness policy settled it;
+	// an absent field whose meaning follows the currently-installed default
+	// would rewrite that evidence at read time.
+	const runConfig: AgentRunConfig = {
+		...params.runConfig,
+		streamIdleTimeoutMs,
+		maxRequestRichContentBytes,
+	}
 
 	// The run's one correlated logger, built before anything below needs
 	// one — the migration check, the retry/fallback wrappers and `ctx`
@@ -846,7 +1014,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	const runId = params.runId ?? generateRunId()
 	const log = RunContextFactory.buildLogger({
 		agentName: params.agentName,
-		runConfig: params.runConfig,
+		runConfig,
 		runId,
 		parentRunId: params.parentRunId,
 		sessionId: params.sessionId,
@@ -901,9 +1069,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// call site — so without it the "failed, retrying" and "failed, giving
 	// up" lines were dead code and a backoff left no trace anywhere.
 	//
-	// With a chain declared, the same sentence holds one level out: retry is
-	// applied per MEMBER and the fallback decorator wraps the result, so the
-	// composition is `fallback(retry(m0), retry(m1), …)`. That order is not a
+	// With a chain declared, the same sentence holds two levels out. The idle
+	// watchdog is applied to each raw member, retry wraps that, and fallback
+	// wraps the members: `fallback(retry(idle(m0)), retry(idle(m1)), …)`. The
+	// idle layer cannot sit outside retry, because its timer would then count a
+	// legitimate backoff as provider silence. This order is not a
 	// preference. Assembled the other way round — which is what a host gets if
 	// it wraps its own chain and hands the result in, because this function
 	// would then wrap THAT in retry — an exhausted chain gets restarted from
@@ -916,8 +1086,15 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	]
 	assertCostIsAttributable(chain, params.pricing)
 	assertBudgetIsMeasurable(params)
-	const withRetry = (provider: LLMProvider): LLMProvider =>
-		params.retry === false ? provider : withProviderRetry(provider, { config: params.retry, log })
+	const withRecovery = (provider: LLMProvider): LLMProvider => {
+		const withIdleBound = withStreamIdleTimeout(provider, {
+			idleTimeoutMs: streamIdleTimeoutMs,
+			log,
+		})
+		return params.retry === false
+			? withIdleBound
+			: withProviderRetry(withIdleBound, { config: params.retry, log })
+	}
 	// Who is serving right now, for the run RECORD rather than for the request.
 	//
 	// It starts at the head and moves only when the chain does, which is the
@@ -929,7 +1106,10 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		current: { index: 0, providerId: params.provider.id },
 	}
 	const resilientProvider = withProviderFallback(
-		chain.map((member) => ({ ...member, provider: withRetry(member.provider) })),
+		chain.map((member) => ({
+			...member,
+			provider: withRecovery(member.provider),
+		})),
 		{
 			log,
 			onSwap: (to) => {
@@ -950,8 +1130,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// window is an optimisation over a working default, not a prerequisite.
 	const providerContextWindow = await resolveProviderContextWindow(
 		resilientProvider,
-		params.runConfig.model,
+		runConfig.model,
 		params.signal,
+		runConfig.timeoutMs,
 		log,
 	)
 
@@ -1005,14 +1186,91 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// image is a model answering about a picture it never saw.
 	const seeded: Message[] =
 		queuedForThisRun.length > 0 ? [...queuedForThisRun, ...params.messages] : params.messages
-	const initialMessages: Message[] = [...(await resolveAttachments(seeded, params.attachmentStore))]
+	let resolvedInitialMessages: Message[]
+	let attachmentResolutionCancelled = false
+	try {
+		resolvedInitialMessages = [
+			...(await resolveAttachments(seeded, params.attachmentStore, {
+				signal: params.signal,
+			})),
+		]
+		params.signal?.throwIfAborted()
+	} catch (error) {
+		// Attachment materialization precedes RunContext construction so stored
+		// bytes never enter a live run's checkpoints. Cancellation still belongs
+		// to that run: preserve the exact input refs, build the context below, and
+		// let its normal terminal path classify/persist a cancelled Run. Every
+		// other store failure remains a pre-run refusal.
+		if (!params.signal?.aborted || error !== params.signal.reason) throw error
+		resolvedInitialMessages = [...seeded]
+		attachmentResolutionCancelled = true
+	}
+	if (!attachmentResolutionCancelled && params.projectInstructionContext?.prepareInitialSnapshot) {
+		const preparationSignal = params.signal ?? new AbortController().signal
+		let snapshot: UserMessage | null | undefined
+		try {
+			const prepared = await awaitProjectInstructionCallback(preparationSignal, () =>
+				params.projectInstructionContext?.prepareInitialSnapshot?.({
+					messages: [...resolvedInitialMessages],
+					signal: preparationSignal,
+				}),
+			)
+			// The callback promise can settle, remove its listener, and queue this
+			// continuation immediately before a queued abort. Publication is a
+			// separate authority boundary, so fence it too.
+			preparationSignal.throwIfAborted()
+			snapshot = prepared
+		} catch (error) {
+			// This callback runs before RunContext owns its child controller. A
+			// caller cancellation here still belongs to the run: publish no late
+			// snapshot and let the context below settle the normal cancelled Run.
+			// Compare the exact reason: a callback failure that won first must not
+			// be erased merely because cancellation arrived before this catch ran.
+			if (!preparationSignal.aborted || error !== preparationSignal.reason) throw error
+		}
+		if (snapshot !== undefined) {
+			resolvedInitialMessages = replaceProjectInstructionSnapshot(
+				resolvedInitialMessages,
+				snapshot,
+				'before-latest-user',
+			)
+		}
+	}
+	const pendingHistoryRepairs: PendingHistoryRepairEvent[] = []
+	const projectedInitialMessages = collapseProjectInstructionSnapshots(
+		params.resumeFromCheckpoint || params.continuationMode
+			? resolvedInitialMessages
+			: projectStateBearingHistory(resolvedInitialMessages, {
+					pinCompaction: true,
+				}),
+	)
+	const initialRepair = params.resumeFromCheckpoint
+		? { messages: projectedInitialMessages, report: undefined }
+		: repairToolMessageHistory(projectedInitialMessages)
+	const initialMessages = initialRepair.messages
+	if (initialRepair.report && toolHistoryRepairChanged(initialRepair.report)) {
+		pendingHistoryRepairs.push({
+			source: 'fresh-history',
+			report: initialRepair.report,
+		})
+		log.warn('Repaired provider-invalid tool history before starting the run', {
+			[NAMZU.RUN_ID]: runId,
+			'namzu.history.source': 'fresh-history',
+			'namzu.history.duplicate_tool_results_removed':
+				initialRepair.report.duplicateToolResultsRemoved,
+			'namzu.history.orphaned_tool_results_removed':
+				initialRepair.report.orphanedToolResultsRemoved,
+			'namzu.history.synthetic_tool_results_inserted':
+				initialRepair.report.syntheticToolResultsInserted,
+		})
+	}
 
 	const ctx = RunContextFactory.build({
 		...(topicState ? { topicPermissionMode: topicState.permissionMode } : {}),
 		...(params.permissionModeRef ? { permissionModeRef: params.permissionModeRef } : {}),
 		agentId: params.agentId,
 		agentName: params.agentName,
-		runConfig: params.runConfig,
+		runConfig,
 		provider: resilientProvider,
 		workingDirectory: params.workingDirectory,
 		pricing: params.pricing,
@@ -1102,6 +1360,108 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	const eventTranslator = new EventTranslator(ctx.runMgr, undefined, ctx.log)
 	eventTranslator.wireActivityStore(ctx.activityStore, ctx.runId)
 	eventTranslator.wirePlanManager(ctx.planManager, ctx.runId)
+	eventTranslator.setGeneration(params.claimFence)
+
+	if (attachmentResolutionCancelled) {
+		// Attachment materialization happens before RunContext exists. Once it
+		// observes cancellation, do only the work required to leave an honest
+		// durable run: initialize the record, retain the unresolved references,
+		// and settle through the ordinary cancellation classifier. Prompt
+		// contributions/cache, host callbacks, tools, plugins, sandbox, guardrails,
+		// advisors, and providers are all authority-bearing work and stay out.
+		if (params.resumeFromCheckpoint && !selectedResumeState) {
+			// The canonical resume surface hands query the checkpoint state it
+			// already selected. A raw resume query has no such snapshot; after
+			// cancellation, reading the store again could hang without a signal,
+			// while persisting without it would erase the existing transcript.
+			// Refuse before binding/persisting rather than choose either failure.
+			ctx.abortController.signal.throwIfAborted()
+		}
+
+		const cancelledPrompt = params.systemPrompt ?? ''
+		const cancelledAssembler = new ResultAssembler({
+			runMgr: ctx.runMgr,
+			planManager: ctx.planManager,
+			activityStore: ctx.activityStore,
+			log: ctx.log,
+			emitEvent: eventTranslator.emitEvent,
+			drainPending: () => eventTranslator.drainPending(),
+			signal: ctx.abortController.signal,
+		})
+		const rootSpan = getTracer().startSpan(
+			agentRunSpanName(params.agentName),
+			{},
+			parentContext(params.parentSpan ?? selectedResumeState?.traceContext),
+		)
+		rootSpan.setAttributes({
+			[NAMZU.RUN_ID]: ctx.runMgr.id,
+			[GENAI.AGENT_NAME]: params.agentName,
+			[GENAI.AGENT_ID]: params.agentId,
+			[GENAI.REQUEST_MODEL]: runConfig.model,
+			[GENAI.SYSTEM]: params.provider.id,
+		})
+
+		try {
+			await ctx.runMgr.init()
+			if (selectedResumeState) {
+				ctx.runMgr.restoreUsage(
+					selectedResumeState.tokenUsage,
+					selectedResumeState.costInfo,
+					selectedResumeState.currentIteration,
+				)
+				for (const message of selectedResumeState.messages) ctx.runMgr.pushMessage(message)
+				for (const queued of queuedForThisRun) ctx.runMgr.pushMessage(queued)
+			} else if (params.continuationMode) {
+				for (const message of initialMessages) ctx.runMgr.pushMessage(message)
+			} else {
+				ctx.runMgr.pushMessage(createSystemMessage(cancelledPrompt, 'cache'))
+				for (const message of initialMessages) ctx.runMgr.pushMessage(message)
+			}
+			if (params.eventCursor) {
+				yield* catchUpFromCursor(
+					ctx.runMgr,
+					params.eventCursor,
+					params.onEventReplay,
+					params.claimFence,
+					(error) => {
+						ctx.log.warn('Replay observer failed after attachment cancellation', {
+							'exception.message': toErrorMessage(error),
+						})
+					},
+				)
+			}
+			if (selectedResumeState) {
+				await eventTranslator.emitEvent({
+					type: 'run_resuming',
+					runId: ctx.runId,
+					fromCheckpointId: selectedResumeState.checkpointId,
+				})
+				yield* eventTranslator.drainPending()
+			}
+			ctx.runMgr.markRunning()
+			await eventTranslator.emitEvent({
+				type: 'run_started',
+				runId: ctx.runId,
+				systemPrompt: cancelledPrompt,
+			})
+			yield* eventTranslator.drainPending()
+			ctx.abortController.signal.throwIfAborted()
+		} catch (error) {
+			// Attachment resolution has already observed the caller's abort. A
+			// reconnect callback can still throw while replay is being reported,
+			// but it cannot replace that terminal cause or turn a cancelled run
+			// into an unpersisted rejection.
+			const terminalError = ctx.abortController.signal.aborted
+				? ctx.abortController.signal.reason
+				: error
+			yield* cancelledAssembler.handleError(terminalError, rootSpan)
+		} finally {
+			rootSpan.end()
+		}
+
+		return await cancelledAssembler.finalize()
+	}
+
 	const unsubscribeTaskStore = params.taskStore
 		? eventTranslator.wireTaskStore(params.taskStore, ctx.runId)
 		: undefined
@@ -1161,7 +1521,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			throw new NamzuError({
 				code: 'capability_unavailable',
 				message,
-				details: { providerId: params.provider.id, capability: 'tools', registeredToolCount },
+				details: {
+					providerId: params.provider.id,
+					capability: 'tools',
+					registeredToolCount,
+				},
 			})
 		}
 		ctx.log.warn('Capability mismatch: the provider declares no tool support', {
@@ -1177,7 +1541,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			throw new NamzuError({
 				code: 'capability_unavailable',
 				message,
-				details: { providerId: params.provider.id, capability: 'vision', attachmentMessageCount },
+				details: {
+					providerId: params.provider.id,
+					capability: 'vision',
+					attachmentMessageCount,
+				},
 			})
 		}
 		ctx.log.warn('Capability mismatch: the provider declares no vision support', {
@@ -1193,7 +1561,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			throw new NamzuError({
 				code: 'capability_unavailable',
 				message,
-				details: { providerId: params.provider.id, capability: 'documents', documentMessageCount },
+				details: {
+					providerId: params.provider.id,
+					capability: 'documents',
+					documentMessageCount,
+				},
 			})
 		}
 		ctx.log.warn('Capability mismatch: the provider declares no document support', {
@@ -1253,7 +1625,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			runId: ctx.runId,
 			workingDirectory: ctx.cwd,
 			permissionMode: () => ctx.permissionMode.current,
-			env: params.runConfig.env ?? {},
+			env: runConfig.env ?? {},
 			abortSignal: ctx.abortController.signal,
 			allowedTools: effectiveAllowedTools,
 			invocationState: params.invocationState,
@@ -1319,10 +1691,10 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	})
 
 	const guard = new GuardCoordinator({
-		tokenBudget: params.runConfig.tokenBudget,
-		timeoutMs: params.runConfig.timeoutMs,
-		costLimitUsd: params.runConfig.costLimitUsd,
-		maxIterations: params.runConfig.maxIterations,
+		tokenBudget: runConfig.tokenBudget,
+		timeoutMs: runConfig.timeoutMs,
+		costLimitUsd: runConfig.costLimitUsd,
+		maxIterations: runConfig.maxIterations,
 	})
 
 	const checkpointMgr = new CheckpointManager(
@@ -1358,14 +1730,29 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 
 	let advisoryCtx: AdvisoryContext | undefined
 	if (params.advisory && params.advisory.advisors.length > 0) {
-		const advisorRegistry = new AdvisorRegistry(
-			params.advisory.advisors,
-			params.advisory.defaultAdvisorId,
-		)
+		// Advisors are model calls owned by this run even when they use a
+		// different provider. Sending the raw definitions into the registry
+		// lets a triggered or model-requested consultation bypass both the
+		// finite stream-silence bound and Stop. Bind every advisor provider at
+		// the query boundary, where the effective timeout and run signal are
+		// already known; standalone AdvisoryExecutor callers retain their
+		// explicitly chosen provider/cancellation policy.
+		const boundedAdvisors = params.advisory.advisors.map((advisor) => ({
+			...advisor,
+			provider: withStreamIdleTimeout(advisor.provider, {
+				idleTimeoutMs: streamIdleTimeoutMs,
+				log: ctx.log,
+			}),
+		}))
+		const advisorRegistry = new AdvisorRegistry(boundedAdvisors, params.advisory.defaultAdvisorId)
 		// A budget the runtime cannot measure is refused here rather than
 		// silently ignored for the length of the run.
 		assertBudgetEnforceable(params.advisory)
-		const advisoryExecutor = new AdvisoryExecutor(ctx.log, params.advisory.budget)
+		const advisoryExecutor = new AdvisoryExecutor(
+			ctx.log,
+			params.advisory.budget,
+			ctx.abortController.signal,
+		)
 		const triggerEvaluator = new TriggerEvaluator(
 			params.advisory.triggers ?? [],
 			params.advisory.budget,
@@ -1422,7 +1809,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	const iterationOrchestrator = new IterationOrchestrator({
 		provider: resilientProvider,
 		servingMember: () => serving.current,
-		runConfig: params.runConfig,
+		runConfig,
 		...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),
 		...(params.prepareStep ? { prepareStep: params.prepareStep } : {}),
 		...(params.beforeStep ? { beforeStep: params.beforeStep } : {}),
@@ -1463,6 +1850,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		...(params.repeatCallAdvisory === false ? {} : { repeatCalls: new RepeatCallTracker() }),
 		compactionConfig: params.compactionConfig,
 		...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
+		...(params.projectInstructionContext
+			? { projectInstructionContext: params.projectInstructionContext }
+			: {}),
 		...(providerContextWindow !== undefined ? { providerContextWindow } : {}),
 		workingStateManager,
 		taskRouter: params.taskRouter,
@@ -1494,9 +1884,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// waterfall, and for a replay fork (which mints a new run id) not
 		// even that. An explicit caller-supplied parent still wins: it is
 		// the more specific statement about where this run belongs.
-		const resumedTrace = params.resumeFromCheckpoint
-			? await checkpointMgr.readTraceContext(params.resumeFromCheckpoint)
-			: undefined
+		const resumedTrace = selectedResumeState
+			? selectedResumeState.traceContext
+			: params.resumeFromCheckpoint
+				? await checkpointMgr.readTraceContext(params.resumeFromCheckpoint)
+				: undefined
 
 		const rootSpan = tracer.startSpan(
 			agentRunSpanName(params.agentName),
@@ -1510,16 +1902,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		checkpointMgr.setTraceSource(() => serializeSpan(rootSpan))
 		// And every park it records carries an absolute deadline, so an
 		// unanswered approval cannot outlive the worker that asked for it.
-		checkpointMgr.setParkTtl(params.runConfig.hitlParkTtlMs)
+		checkpointMgr.setParkTtl(runConfig.hitlParkTtlMs)
 		// The claim this worker holds, if it took one. Without this hop the
 		// fence exists, the refusal exists, and no checkpoint a RUN writes ever
 		// carries a number — so a stalled worker is refused nowhere.
 		checkpointMgr.setClaimFence(params.claimFence)
-		// And every EVENT it records carries the same fence as its generation,
-		// so a consumer whose cursor was minted under an older holding is told
-		// the sequence space changed rather than handed a splice from it.
-		eventTranslator.setGeneration(params.claimFence)
-
 		// A question raised from inside a tool becomes a real checkpoint
 		// here. It used to park under a synthetic id nothing ever wrote, so
 		// the checkpoint did not exist: nothing on disk said a human owed
@@ -1581,7 +1968,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			[NAMZU.RUN_ID]: ctx.runMgr.id,
 			[GENAI.AGENT_NAME]: params.agentName,
 			[GENAI.AGENT_ID]: params.agentId,
-			[GENAI.REQUEST_MODEL]: params.runConfig.model,
+			[GENAI.REQUEST_MODEL]: runConfig.model,
 			[GENAI.SYSTEM]: params.provider.id,
 		})
 
@@ -1607,29 +1994,19 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					params.eventCursor,
 					params.onEventReplay,
 					params.claimFence,
+					(error) => {
+						ctx.log.warn('Replay observer failed', {
+							'exception.message': toErrorMessage(error),
+						})
+					},
 				)
 			}
 
-			// Handed over here, and the position is load-bearing in BOTH
-			// directions. It has to follow `wirePlanManager`, or a host that
-			// builds its plan in this callback — which is what the callback is
-			// for — does it into silence: `plan_ready`, `plan_approved` and
-			// every `plan_step_updated` are emitted with nothing subscribed,
-			// and the host then watches a stream that never mentions the plan
-			// it just created. It also has to follow `runMgr.init()`, because
-			// emitting appends to the run store and an uninitialised store
-			// throws — moving it up to the wiring alone traded a silent drop
-			// for 25 unhandled rejections.
-			//
-			// Still before the iteration loop, which is the guarantee the
-			// callback actually makes.
-			params.onContextCreated?.({ planManager: ctx.planManager })
-
 			ctx.log.info('Starting query', {
 				[NAMZU.RUN_ID]: ctx.runMgr.id,
 				'namzu.runtime.agent': params.agentName,
-				[GENAI.REQUEST_MODEL]: params.runConfig.model,
-				'namzu.runtime.token_budget': params.runConfig.tokenBudget,
+				[GENAI.REQUEST_MODEL]: runConfig.model,
+				'namzu.runtime.token_budget': runConfig.tokenBudget,
 				'namzu.runtime.activity_tracking': ctx.activityStore.enabled,
 				'namzu.runtime.permission_mode': ctx.permissionMode.current,
 				'namzu.runtime.resume_from_checkpoint': params.resumeFromCheckpoint ?? null,
@@ -1665,6 +2042,12 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 
 			if (params.resumeFromCheckpoint) {
 				const checkpoint = await checkpointMgr.restore(params.resumeFromCheckpoint)
+				const projectedCheckpoint = {
+					...checkpoint,
+					messages: projectStateBearingHistory(checkpoint.messages, {
+						pinCompaction: false,
+					}),
+				}
 				await eventTranslator.emitEvent({
 					type: 'run_resuming',
 					runId: ctx.runMgr.id,
@@ -1718,8 +2101,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				// re-decides, so "yes, delete that row" degrades into "ask
 				// again and hope it asks for the same thing".
 				pendingResume =
-					params.pendingDecision && checkpoint.pending
-						? planPendingResume(checkpoint, params.pendingDecision, ctx.log)
+					params.pendingDecision && projectedCheckpoint.pending
+						? planPendingResume(projectedCheckpoint, params.pendingDecision, ctx.log)
 						: null
 
 				// Results of tools that finished before the process died. The
@@ -1728,7 +2111,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				// durable all along — it was simply never read back, and the
 				// resumed run re-ran calls that had already charged a card or
 				// sent an email.
-				const unanswered = unansweredToolCalls(checkpoint.messages)
+				const unanswered = unansweredToolCalls(projectedCheckpoint.messages)
 				recoveredResults =
 					unanswered.length > 0
 						? await recoverCompletedCalls(ctx.runMgr, unanswered, ctx.log)
@@ -1740,32 +2123,35 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				// the transcript proves execution had begun — a tool-review
 				// park has no completions and keeps the cheap repair below.
 				if (!pendingResume && recoveredResults.size > 0) {
-					pendingResume = planCrashResume(checkpoint, recoveredResults, ctx.log)
+					pendingResume = planCrashResume(projectedCheckpoint, recoveredResults, ctx.log)
 				}
 
-				// A checkpoint taken at a tool-review park snapshots the
-				// assistant turn AFTER its `tool_use` blocks but BEFORE any
-				// `tool_result` exists, so replaying it verbatim would send a
-				// malformed request on the first model call of the resumed
-				// run. Repair the incomplete turn rather than inheriting it:
-				// the model re-decides from the last valid state.
-				//
-				// The pending-decision path uses the SAME repair: it strips
-				// the unanswered turn here and `applyPendingResume` re-appends
-				// it together with the results that answer it, so the history
-				// stays well-formed either way.
-				const dangling = findDanglingMessages(checkpoint.messages)
-				const restoredMessages = dangling.isValid
-					? checkpoint.messages
-					: removeDanglingMessages(checkpoint.messages)
-				if (!dangling.isValid && !pendingResume) {
-					ctx.log.warn('Checkpoint contained unanswered tool calls — repaired on restore', {
+				// An incomplete turn with a durable owner is NOT abandoned. A
+				// pending decision or crash-resume plan re-appends that exact
+				// assistant with real/denied/recovered results below. Remove it
+				// from the generic pass so no synthetic result competes with the
+				// authority that still owns the call. Everything else is abandoned
+				// history and is repaired conservatively rather than deleted.
+				const abandonedCheckpointMessages = pendingResume
+					? withoutOwnedResumeTurn(projectedCheckpoint.messages, pendingResume.assistant)
+					: projectedCheckpoint.messages
+				const checkpointRepair = repairToolMessageHistory(abandonedCheckpointMessages)
+				const restoredMessages = checkpointRepair.messages
+				if (toolHistoryRepairChanged(checkpointRepair.report)) {
+					pendingHistoryRepairs.push({
+						source: 'abandoned-checkpoint',
+						report: checkpointRepair.report,
+					})
+					ctx.log.warn('Repaired abandoned tool history while restoring a checkpoint', {
 						[NAMZU.RUN_ID]: ctx.runMgr.id,
 						'namzu.checkpoint.id': checkpoint.id,
-						'namzu.runtime.unanswered_assistant_turns':
-							dangling.assistantsWithUnmatchedCalls.length,
-						'namzu.runtime.orphaned_tool_messages': dangling.orphanedToolMessages.length,
-						'namzu.runtime.removed': checkpoint.messages.length - restoredMessages.length,
+						'namzu.history.source': 'abandoned-checkpoint',
+						'namzu.history.duplicate_tool_results_removed':
+							checkpointRepair.report.duplicateToolResultsRemoved,
+						'namzu.history.orphaned_tool_results_removed':
+							checkpointRepair.report.orphanedToolResultsRemoved,
+						'namzu.history.synthetic_tool_results_inserted':
+							checkpointRepair.report.syntheticToolResultsInserted,
 					})
 				}
 
@@ -1802,7 +2188,21 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				pushSystemMessages()
 				let isFirstUserMessage = true
 				for (const msg of initialMessages) {
-					if (msg.role === 'system') continue
+					if (msg.role === 'system') {
+						// A fresh run rebuilds its current static/dynamic prompt above,
+						// so arbitrary historical system messages stay out. These two
+						// are different: they are conversation STATE, and dropping them
+						// deletes the only surviving record of compacted history or the
+						// produced-artifact ledger. A compaction summary arriving from a
+						// prior run is pinned because this new WorkingStateManager cannot
+						// prove it has reconstructed equivalent state yet.
+						if (isCompactionMessage(msg.content)) {
+							ctx.runMgr.pushMessage({ ...msg, retain: true })
+						} else if (isWorkingMemoryMessage(msg.content)) {
+							ctx.runMgr.pushMessage(msg)
+						}
+						continue
+					}
 					ctx.runMgr.pushMessage(msg)
 
 					if (workingStateManager && msg.role === 'user' && msg.content) {
@@ -1825,6 +2225,25 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			})
 			yield* eventTranslator.drainPending()
 
+			// Pre-run materialization can observe cancellation before RunContext
+			// exists. The exact input has now been seeded and the run is writable;
+			// hand the cancellation to the normal terminal path before invoking
+			// any host callback, guardrail, plugin, sandbox, or provider. Those
+			// boundaries are not all cooperative and must not regain withdrawn
+			// authority merely because the run record still had to be created.
+			ctx.abortController.signal.throwIfAborted()
+
+			// Handed over here, and the position is load-bearing in three
+			// directions. It has to follow `wirePlanManager`, or a host that
+			// builds its plan in this callback does it into silence. It has to
+			// follow `runMgr.init()` and `run_started`, because plan events append
+			// to that durable run. It also has to follow the pre-model abort fence:
+			// a callback invoked after attachment resolution observed cancellation
+			// would regain withdrawn authority and could replace the cancellation
+			// with its own failure. This is still before the iteration loop, which
+			// is the guarantee the callback makes.
+			params.onContextCreated?.({ planManager: ctx.planManager })
+
 			// The box is handed out HERE, after `run_started`, and the position
 			// is load-bearing rather than tidy. It moved twice:
 			//
@@ -1842,6 +2261,21 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// being writable.
 			params.onApprovalPolicy?.(approvalPolicy)
 
+			// History repair happens before the run manager sees the first model
+			// request, but its durable event cannot precede run_started: there is no
+			// writable run log until that event initializes it. Emit the measured
+			// counts here, still before any provider call, so hosts can tell that the
+			// model received a repaired projection rather than the raw history.
+			for (const repair of pendingHistoryRepairs) {
+				await eventTranslator.emitEvent({
+					type: 'message_history_repaired',
+					runId: ctx.runMgr.id,
+					source: repair.source,
+					...repair.report,
+				})
+				yield* eventTranslator.drainPending()
+			}
+
 			// Surface capability degradation to the host as run events —
 			// explicit, not silent (the log.warn above fires at setup time;
 			// this is the machine-readable channel).
@@ -1865,11 +2299,21 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				})
 				yield* eventTranslator.drainPending()
 			}
+			if (documentMessageCount > 0) {
+				await eventTranslator.emitEvent({
+					type: 'capability_warning',
+					runId: ctx.runMgr.id,
+					capability: 'documents',
+					providerId: params.provider.id,
+					message: `Provider '${params.provider.id}' does not support documents — document attachments on ${documentMessageCount} user message(s) will not reach the model.`,
+				})
+				yield* eventTranslator.drainPending()
+			}
 
 			if (params.pluginManager) {
 				const hookResults = await params.pluginManager.executeHooks(
 					'run_start',
-					{ runId: ctx.runId },
+					{ runId: ctx.runId, signal: ctx.abortController.signal },
 					eventTranslator.emitEvent,
 				)
 				applyLifecycleHookResults('run_start', hookResults)
@@ -1878,7 +2322,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 
 			// --- Sandbox lifecycle: create before iteration loop ---
 			if (params.sandboxProvider) {
-				const rootAtCwd = params.runConfig.sandbox?.workspace === 'working-directory'
+				const rootAtCwd = runConfig.sandbox?.workspace === 'working-directory'
 				// Checked against what the CALLER passed, not against `ctx.cwd`.
 				// `ctx.cwd` falls back to `process.cwd()`, so reading it here
 				// would silently root the sandbox at whatever directory the
@@ -1897,12 +2341,54 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 						details: { workspace: 'working-directory' },
 					})
 				}
-				sandbox = await params.sandboxProvider.create({
-					...(rootAtCwd ? { workingDirectory: ctx.cwd } : {}),
-					timeoutMs: params.runConfig.sandbox?.timeoutMs,
-					memoryLimitMb: params.runConfig.sandbox?.memoryLimitMb,
-					maxProcesses: params.runConfig.sandbox?.maxProcesses,
+				const acquisition = await acquireSandbox({
+					provider: params.sandboxProvider,
+					config: {
+						...(rootAtCwd ? { workingDirectory: ctx.cwd } : {}),
+						timeoutMs: runConfig.sandbox?.timeoutMs,
+						memoryLimitMb: runConfig.sandbox?.memoryLimitMb,
+						maxProcesses: runConfig.sandbox?.maxProcesses,
+					},
+					signal: ctx.abortController.signal,
+					timeoutMs: guard.remainingUntilTimeoutMs(),
+					teardownTimeoutMs: sandboxTeardownTimeoutMs,
+					onLateTeardown: (result) => {
+						if (result.kind === 'destroyed') {
+							ctx.log.info('Late sandbox allocation was destroyed after the run stopped', {
+								[NAMZU.RUN_ID]: ctx.runId,
+							})
+							return
+						}
+						ctx.log.error('Late sandbox allocation did not stop cleanly', {
+							[NAMZU.RUN_ID]: ctx.runId,
+							...errorAttributes(result.error),
+						})
+					},
 				})
+				if (acquisition.kind !== 'created') {
+					if (acquisition.createPending) {
+						ctx.log.warn(
+							'Sandbox creation was unsettled when the run stopped; any returned handle will be released, but a remote allocation hidden behind a lost response requires provider-side reconciliation or a fleet reaper',
+							{
+								[NAMZU.RUN_ID]: ctx.runId,
+								'namzu.sandbox.provider_id': params.sandboxProvider.id,
+							},
+						)
+					}
+					if (acquisition.kind === 'cancelled') {
+						ctx.runMgr.markCancelled()
+					} else {
+						ctx.runMgr.setStopReason('timeout')
+						ctx.log.warn('Sandbox creation exhausted the run timeout', {
+							[NAMZU.RUN_ID]: ctx.runId,
+							'namzu.sandbox.provider_id': params.sandboxProvider.id,
+							...errorAttributes(acquisition.error),
+						})
+					}
+					yield* resultAssembler.completeRun(rootSpan)
+					return await resultAssembler.finalize()
+				}
+				sandbox = acquisition.sandbox
 				toolExecutor.setSandbox(sandbox)
 
 				await eventTranslator.emitEvent({
@@ -2022,7 +2508,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			if (params.pluginManager) {
 				const hookResults = await params.pluginManager.executeHooks(
 					'run_end',
-					{ runId: ctx.runId },
+					{ runId: ctx.runId, signal: ctx.abortController.signal },
 					eventTranslator.emitEvent,
 				)
 				applyLifecycleHookResults('run_end', hookResults)
@@ -2148,19 +2634,19 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// --- Sandbox lifecycle: destroy after run ---
 			if (sandbox) {
 				const sandboxId = sandbox.id
-				try {
-					await sandbox.destroy()
+				const teardown = await teardownSandbox(sandbox, sandboxTeardownTimeoutMs)
+				if (teardown.kind === 'destroyed') {
 					await eventTranslator.emitEvent({
 						type: 'sandbox_destroyed',
 						runId: ctx.runId,
 						sandboxId,
 					})
+					yield* eventTranslator.drainPending()
 					ctx.log.info('Sandbox destroyed', { 'namzu.sandbox.id': sandboxId })
-				} catch (destroyErr) {
+				} else {
 					ctx.log.error('Sandbox destroy failed', {
 						'namzu.sandbox.id': sandboxId,
-						'exception.message':
-							destroyErr instanceof Error ? destroyErr.message : String(destroyErr),
+						...errorAttributes(teardown.error),
 					})
 				}
 			}
@@ -2193,28 +2679,43 @@ async function* catchUpFromCursor(
 	cursor: RunEventCursor,
 	onEventReplay: ((replay: RunEventReplay) => void) | undefined,
 	generation: FencingToken | undefined,
+	onReplayObserverError: (error: unknown) => void,
 ): AsyncGenerator<RunEvent, void> {
 	const missed = await runMgr.getRunStore().readEvents({ sinceSeq: cursor.sinceSeq })
 	const replay = resolveRunEventReplay(
 		cursor,
-		{ lastSeq: runMgr.lastEventSeq, ...(generation !== undefined ? { generation } : {}) },
+		{
+			lastSeq: runMgr.lastEventSeq,
+			...(generation !== undefined ? { generation } : {}),
+		},
 		missed,
 	)
 
-	onEventReplay?.(replay)
+	if (onEventReplay) {
+		try {
+			// A callback typed `void` may still be implemented with `async` in
+			// TypeScript. Observe that runtime Promise so a late rejection cannot
+			// become process-wide, but never await host code here: replay delivery
+			// and an already-cancelled run must not inherit observer liveness.
+			const settlement = onEventReplay(replay)
+			void Promise.resolve(settlement).catch(onReplayObserverError)
+		} catch (error) {
+			onReplayObserverError(error)
+		}
+	}
 
 	if (replay.status !== 'replayed') return
 	for (const event of replay.events) yield event
 }
 
-export async function drainQuery(
-	params: Omit<QueryParams, 'resumeHandler'> & { resumeHandler?: ResumeHandler },
+type DrainQueryParams = Omit<QueryParams, 'resumeHandler'> & {
+	resumeHandler?: ResumeHandler
+}
+
+async function drainPreparedQuery(
+	fullParams: QueryParams,
 	listener?: RunEventListener,
 ): Promise<Run> {
-	const fullParams: QueryParams = {
-		...params,
-		resumeHandler: params.resumeHandler ?? autoApproveHandler,
-	}
 	const gen = query(fullParams)
 	let result = await gen.next()
 
@@ -2228,6 +2729,54 @@ export async function drainQuery(
 	return result.value
 }
 
+export async function drainQuery(
+	params: Omit<QueryParams, 'resumeHandler'> & {
+		resumeHandler?: ResumeHandler
+	},
+	listener?: RunEventListener,
+): Promise<Run> {
+	const fullParams: QueryParams = {
+		...params,
+		resumeHandler: params.resumeHandler ?? autoApproveHandler,
+	}
+	return await drainPreparedQuery(fullParams, listener)
+}
+
+/** @internal Canonical resume state already selected by `resumeRun`. */
+export async function drainQueryWithSelectedResumeState(
+	params: DrainQueryParams,
+	state: SelectedResumeState,
+	listener?: RunEventListener,
+): Promise<Run> {
+	const fullParams: QueryParams = {
+		...params,
+		resumeHandler: params.resumeHandler ?? autoApproveHandler,
+	}
+	if (fullParams.resumeFromCheckpoint !== state.checkpointId) {
+		throw new Error('The selected resume state does not match the requested checkpoint.')
+	}
+	assertSelectedResumeAttribution(fullParams, state)
+	selectedResumeStates.set(fullParams, state)
+	return await drainPreparedQuery(fullParams, listener)
+}
+
+function assertSelectedResumeAttribution(params: QueryParams, state: SelectedResumeState): void {
+	const mismatchedFields: string[] = []
+	if (params.runId !== state.runId) mismatchedFields.push('runId')
+	if (params.sessionId !== state.sessionId) mismatchedFields.push('sessionId')
+	if (params.topicId !== state.topicId) mismatchedFields.push('topicId')
+	if (params.projectId !== state.projectId) mismatchedFields.push('projectId')
+	if (params.tenantId !== state.tenantId) mismatchedFields.push('tenantId')
+	if (params.parentRunId !== state.parentRunId) mismatchedFields.push('parentRunId')
+	if (mismatchedFields.length === 0) return
+
+	throw new NamzuError({
+		code: 'invalid_config',
+		message: 'The selected resume state does not match the run attribution supplied to the query.',
+		details: { fields: mismatchedFields },
+	})
+}
+
 function withDeferredDiscoveryTool(
 	tools: ToolRegistryContract,
 	allowedTools?: string[],