@namzu/sdk 41.0.0 → 42.0.1

package/src/runtime/query/index.ts

@@ -6,14 +6,8 @@ import {
 	TriggerEvaluator,
 	assertBudgetEnforceable,
 } from '../../advisory/index.js'
-import { drainQueuedMessages } from '../../agents/handle.js'
 import { AuthorizationGate } from '../../authorization/gate.js'
-import { consolidationEntry } from '../../compaction/consolidation.js'
-import {
-	type ToolHistoryRepairReport,
-	repairToolMessageHistory,
-	toolHistoryRepairChanged,
-} from '../../compaction/dangling.js'
+import { 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'
@@ -23,21 +17,14 @@ import { type CompactionConfig, CompactionConfigSchema } from '../../config/runt
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
 import { EmergencySaveManager } from '../../manager/run/emergency.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
-import { resolveModelPricing } from '../../pricing/index.js'
 import { PromptContributionRegistry } from '../../prompt/contributions.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
-import { isCallerAbortError } from '../../provider/errors.js'
-import {
-	type ProviderChainMember,
-	type ServingMember,
-	withProviderFallback,
-} from '../../provider/fallback.js'
-import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../../provider/idle-timeout.js'
-import { type ProviderRetryConfig, withProviderRetry } from '../../provider/retry.js'
+import type { ProviderChainMember } from '../../provider/fallback.js'
+import { withStreamIdleTimeout } from '../../provider/idle-timeout.js'
+import type { ProviderRetryConfig } from '../../provider/retry.js'
 import { withTokenBudget } from '../../provider/token-budget.js'
 import type { TokenBudget } from '../../run/token-budget.js'
 import type { PathBuilder } from '../../session/workspace/path-builder.js'
-import { resolveAttachments } from '../../store/attachment/index.js'
 import {
 	GENAI,
 	NAMZU,
@@ -45,8 +32,6 @@ 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'
 import { SearchToolsTool } from '../../tools/builtins/search-tools.js'
@@ -60,6 +45,7 @@ import type { AgentRuntimeContext, RuntimeToolOverrides } from '../../types/agen
 import type { AgentContextLevel } from '../../types/agent/factory.js'
 import type { WorkingMemoryProvider } from '../../types/agent/working-memory.js'
 import type { AuthorizationGateConfig } from '../../types/authorization/index.js'
+import { isTerminalStatus } from '../../types/common/index.js'
 import { NamzuError } from '../../types/errors/index.js'
 import type { InputGuardrailSpec, OutputGuardrailSpec } from '../../types/guardrail/index.js'
 import {
@@ -67,23 +53,20 @@ import {
 	type ResumeHandler,
 	autoApproveHandler,
 } from '../../types/hitl/index.js'
-import type { CheckpointId, PlanId, RunId, SessionId, TenantId } from '../../types/ids/index.js'
+import type { CheckpointId, RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import type { MemoryStore } from '../../types/memory/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'
 import type { ReviewAnswer } from '../../types/run/answer-review.js'
-import { cancelCauseOf } from '../../types/run/cancel-cause.js'
 import type { CheckpointStore, FencingToken } from '../../types/run/checkpoint-store.js'
 import type { RunEventCursor, RunEventReplay } from '../../types/run/event-cursor.js'
-import { resolveRunEventReplay } from '../../types/run/event-cursor.js'
 import type {
 	AgentRunConfig,
 	BeforeStep,
@@ -95,8 +78,6 @@ import type {
 	StopCondition,
 } 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 { TokenBudgetStore } from '../../types/run/token-budget-store.js'
 import type { Sandbox, SandboxProvider } from '../../types/sandbox/index.js'
@@ -109,50 +90,46 @@ import type { RepairToolCall } from '../../types/tool/repair.js'
 import type { BackoffPolicy } from '../../utils/backoff.js'
 import type { ModelPricing } from '../../utils/cost.js'
 import { toErrorMessage } from '../../utils/error.js'
-import { generateCheckpointId, generateRunId } from '../../utils/id.js'
 import { errorAttributes } from '../../utils/log/exception.js'
 import type { Logger } from '../../utils/logger.js'
 import { AwaitedJobs } from '../jobs/awaited-jobs.js'
 import type { BackgroundJobRegistry } from '../jobs/registry.js'
-import { AUTO_APPROVE_POLICY_NAME, createRunApprovalPolicy } from './approval-policy.js'
-import { CheckpointManager } from './checkpoint.js'
-import { RunContextFactory } from './context.js'
-import { EventTranslator } from './events.js'
+import { catchUpFromCursor, settlePreStartCancellation } from './cancelled-before-start.js'
+import { CheckpointManager, findPendingCheckpoint } from './checkpoint.js'
+import { finalizeRun } from './finalize-run.js'
 import { GuardCoordinator } from './guard.js'
-import { runInputGuardrails, runOutputGuardrails } from './guardrails.js'
+import { runInputGuardrails } from './guardrails.js'
 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'
+	type SelectedResumeState,
+	prepareRun,
+	projectStateBearingHistory,
+	resolveProviderContextWindow,
+	selectedResumeStates,
+} from './prepare-run.js'
+import type { ProjectInstructionContext } 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 { releaseRunResources } from './release-run.js'
 import { RepeatCallTracker } from './repeat-call.js'
-import { resolveMaxRequestRichContentBytes } from './request-rich-content.js'
 import { ResultAssembler } from './result.js'
 import {
 	type PendingResumePlan,
+	answersParkOf,
 	applyPendingResume,
 	interruptedToolCalls,
 	planCrashResume,
 	planPendingResume,
 	recoverCompletedCalls,
+	supersededByRecovery,
 } from './resume-pending.js'
-import {
-	acquireSandbox,
-	resolveSandboxTeardownTimeoutMs,
-	teardownSandbox,
-} from './sandbox-lifecycle.js'
+import { acquireSandbox } from './sandbox-lifecycle.js'
 import { SteeringBinding, type SteeringChannel, isOperatorUserMessage } from './steering.js'
-import { resolveQueryBudget } from './token-budget.js'
-import { assertMaxToolCalls } from './tool-call-budget.js'
 import { ToolGrantSet } from './tool-grants.js'
 import { createToolPause } from './tool-pause.js'
 import { ToolingBootstrap } from './tooling.js'
@@ -363,6 +340,20 @@ export interface QueryParams {
 	 * agent decides the rest is worth re-reading. Set `0` to disable.
 	 */
 	maxToolOutputChars?: number
+	/**
+	 * Screens to run against every tool result, where the registry was not
+	 * built with its own.
+	 *
+	 * This is the run's half of a boundary whose only other door is the
+	 * registry constructor — and a registry is usually the HOST's, assembled
+	 * before the run exists, so a run-config option is the only way a run
+	 * screens a registry it did not build. A registry built WITH
+	 * `resultGuardrails` states its own policy and wins, `[]` included.
+	 *
+	 * Absent installs {@link DEFAULT_TOOL_RESULT_GUARDRAILS}; an empty array
+	 * installs none, which is how a caller turns the default off.
+	 */
+	toolResultGuardrails?: readonly import('../../types/guardrail/index.js').ToolResultGuardrailSpec[]
 	/**
 	 * Smaller preview for text that exceeded maxToolOutputChars, after its full
 	 * host output and integrity manifest have been saved. Unset/0 keeps the old
@@ -818,196 +809,6 @@ 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.
- *
- * `RunPersistence` holds ONE {@link ModelPricing} table and applies it to every
- * accumulation regardless of which model produced the tokens. Across a swap that
- * makes `costInfo.totalCost` wrong by an unbounded margin, and silently — the
- * number keeps the shape of an answer. `CostInfo` cannot express the truth
- * either: it carries `inputCostPer1M` / `outputCostPer1M`, and there is no
- * honest value for those once a total spans two rate cards.
- *
- * So the total is refused rather than blended. Naming what that costs is part
- * of the refusal, because the caller loses `costLimitUsd` with it: the guard
- * enforces that limit from this same accumulated total, and a limit enforced
- * with the wrong rate card stops a run early or late by the same unbounded
- * margin. A budget that is quietly wrong is worse than a budget that is
- * declined.
- *
- * Reachable, not decorative: a host that passes `pricing` and declares a chain
- * hits it on the first call. It costs `@namzu/cli` nothing, which passes no
- * pricing at all — its `/cost` already reports that the provider gave no price.
- *
- * The way out is per-member pricing, which needs a `CostInfo` that can sum over
- * heterogeneous rates. That is a public-type change and it is not this one.
- */
-function assertCostIsAttributable(
-	chain: readonly ProviderChainMember[],
-	pricing: ModelPricing | undefined,
-): void {
-	if (pricing === undefined || chain.length < 2) return
-	throw new NamzuError({
-		code: 'invalid_config',
-		message:
-			`A provider chain of ${chain.length} members was declared together with a single pricing table. ` +
-			'One table cannot price two members, so the run would report a total that is wrong by an unbounded ' +
-			'margin — and `runConfig.costLimitUsd` would be enforced against that same wrong total. ' +
-			'Either drop `pricing` (usage is still reported per model in the run) or declare one member.',
-		details: { chainLength: chain.length },
-	})
-}
-
-/**
- * Refuse a budget that cannot be measured.
- *
- * `runConfig.costLimitUsd` is enforced against `costInfo.totalCost`, and that
- * total only moves for tokens something has a rate for. A model no rate card
- * covers therefore produced a limit that could never trip — a host that set a
- * cost cap had no cost cap, and nothing said so. That was every run before the
- * price catalogue existed, which is how it went unnoticed.
- *
- * Refusing at the front is the cheap half of the answer: it costs the caller
- * nothing, fires before any spend, and names both ways out. The other half is
- * the `cost_unmeasurable` stop, for the models this cannot see — a step naming
- * its own, or a chain member declaring one.
- *
- * This is the same shape `advisory/budget.ts` already applies to
- * `AdvisoryBudget.maxCostPerRun`, one layer down, and for the same reason. The
- * run path simply never had it.
- */
-function assertBudgetIsMeasurable(params: QueryParams): void {
-	const limit = params.runConfig.costLimitUsd
-	if (limit === undefined || limit <= 0) return
-	// A host-supplied table prices whatever it is pointed at, so a caller who
-	// brought one has answered the question themselves.
-	if (params.pricing !== undefined) return
-	const model = params.runConfig.model
-	if (resolveModelPricing(params.provider.id, model) !== undefined) return
-
-	throw new NamzuError({
-		code: 'invalid_config',
-		message:
-			`runConfig.costLimitUsd is set to ${limit}, but no rate is known for model "${model}" on ` +
-			`provider "${params.provider.id}". The limit is enforced against the run's accumulated ` +
-			'cost, and tokens with no rate never reach that total — so the budget would read as ' +
-			'satisfied for the whole run and stop nothing. Either pass `pricing` to declare the rate ' +
-			'yourself, add the model to packages/sdk/src/pricing/rates.source.json, or drop ' +
-			'`costLimitUsd` and bound the run with `tokenBudget`, which is measurable here.',
-		details: { model, providerId: params.provider.id, costLimitUsd: limit },
-	})
-}
-
-/**
- * Ask the driver what this model's window is, and never let the answer
- * cost the run.
- *
- * Three outcomes collapse to two here on purpose. No member and a resolved
- * `undefined` both mean "no answer" — the distinction matters to a driver
- * author, not to a caller about to fall through to the table. A rejection
- * is the third, and it is logged rather than propagated: a run that would
- * have worked on the table must not fail because a listing endpoint was
- * down.
- */
-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 })
-	})
-	// Direct QueryParams callers can supply a large run deadline. The clamp
-	// avoids Node's >2^31-1 one-millisecond timer coercion during metadata lookup.
-	// Metadata discovery remains optional and bounded even without a run deadline.
-	const deadlineMs = timeoutMs === 0 ? 5_000 : 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 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', {
-			'namzu.model.id': model,
-			'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.
  *
@@ -1086,520 +887,32 @@ function withOwnedResumeOutcomes(
 }
 
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
-	assertMaxToolCalls(params.maxToolCalls)
-	// Required types do not protect JavaScript callers. Reject missing scope
-	// before opening a budget or persisting a run without its owning identity.
-	const missingFields = (['sessionId', 'topicId', 'projectId', 'tenantId'] as const).filter(
-		(field) => !params[field],
-	)
-	if (missingFields.length > 0) {
-		throw new NamzuError({
-			code: 'invalid_config',
-			message: `query requires sessionId, topicId, projectId, and tenantId; missing: ${missingFields.join(', ')}.`,
-			details: { missingFields },
-		})
-	}
-	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
-	// deep in the loop turns the same bug into a mid-run failure, after a
-	// 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`
-	// itself all read this SAME object, so a retry warning and the run
-	// record it retried for carry the identical `namzu.run.id` instead of
-	// three separate `getRootLogger()` reads that happened to agree by
-	// accident. `runId` is resolved here, once, rather than left to
-	// `build`'s own `config.runId ?? generateRunId()` fallback —
-	// generating it twice would silently hand the log and the run two
-	// different ids.
-	const runId = params.runId ?? generateRunId()
-	const budget = await resolveQueryBudget(params, runId, selectedResumeState)
-	const log = RunContextFactory.buildLogger({
-		agentName: params.agentName,
+	const prepared = await prepareRun(params)
+	const {
 		runConfig,
-		runId,
-		parentRunId: params.parentRunId,
-		sessionId: params.sessionId,
-		topicId: params.topicId,
-		projectId: params.projectId,
-		tenantId: params.tenantId,
-	})
-
-	// Every model call in the run — the loop's turns, the forced-final
-	// summary, advisory and compaction side calls — goes through this one
-	// wrapped provider, so the retry policy cannot be bypassed by a code
-	// path that happens to hold the raw driver.
-	// The logger is passed on purpose: `withProviderRetry` guards every one
-	// of its warns behind `options.log`, and this is its only production
-	// 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 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
-	// the head by the outer loop and a throttle on the last member is counted
-	// by two budgets. Building it here is what makes the order unspellable
-	// wrong.
-	const chain: readonly ProviderChainMember[] = [
-		{ provider: params.provider },
-		...(params.fallbackProviders ?? []),
-	]
-	assertCostIsAttributable(chain, params.pricing)
-	assertBudgetIsMeasurable(params)
-	const withRecovery = (provider: LLMProvider): LLMProvider => {
-		const withIdleBound = withStreamIdleTimeout(provider, {
-			idleTimeoutMs: streamIdleTimeoutMs,
-			log,
-		})
-		const metered = withTokenBudget(withIdleBound, budget)
-		return params.retry === false
-			? metered
-			: withProviderRetry(metered, {
-					config: params.retry,
-					log,
-					canRetry: () => budget.remaining > 0,
-				})
-	}
-	// 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
-	// whole of the truth because the cursor never rewinds. The run cannot read
-	// this off `resilientProvider`: that wrapper reports the head's `id` on
-	// purpose, so asking it produces the declaration back — the defect this
-	// record exists to fix.
-	const serving: { current: ServingMember } = {
-		current: { index: 0, providerId: params.provider.id },
-	}
-	const resilientProvider = withProviderFallback(
-		chain.map((member) => ({
-			...member,
-			provider: withRecovery(member.provider),
-		})),
-		{
-			log,
-			canFallback: () => budget.remaining > 0,
-			onSwap: (to) => {
-				serving.current = to
-				// `ctx` is declared below and is initialized before anything can
-				// call the provider: this fires from inside a `chatStream`, and
-				// the first one is issued by the loop that `ctx` is built for.
-				ctx.runMgr.setServingProvider(to.providerId)
-			},
-		},
-	)
-
-	// Asked ONCE, here, before the loop exists. Both readers are synchronous
-	// and hot, so this can never move inside the iteration — and a driver
-	// that rejects, or one that hangs until the run is cancelled, must not
-	// take down a run the table could have served perfectly well. That is
-	// why the failure path is a swallow with a log rather than a throw: the
-	// window is an optimisation over a working default, not a prerequisite.
-	const providerContextWindow = await resolveProviderContextWindow(
-		resilientProvider,
-		runConfig.model,
-		params.signal,
-		runConfig.timeoutMs,
-		log,
-	)
-	const modelContextWindows = new Map<string, number | undefined>()
-	if (runConfig.model) modelContextWindows.set(runConfig.model, providerContextWindow)
-
-	// The mode this conversation was left in, when the run config names none.
-	// Read once, before the loop exists, for the same reason the context
-	// window is: the executor's resolver is synchronous and hot.
-	//
-	// A store that throws is not a run failure — the run falls back to the
-	// config's answer, which is exactly what it did before this existed.
-	const topicState = params.topicStateStore
-		? await params.topicStateStore
-				.getState(params.topicId, params.tenantId)
-				.catch((err: unknown) => {
-					log.debug('Could not read the topic state; using the run config', {
-						'namzu.topic.id': params.topicId,
-						'namzu.error.message': toErrorMessage(err),
-					})
-					return null
-				})
-		: null
-
-	// Whatever a host left for "the next run", taken and cleared in one
-	// compare-and-set write. Prepended to the messages this run starts from,
-	// so it is in the FIRST request rather than arriving a turn late.
-	//
-	// Cleared as it is read: a queue read and cleared separately re-delivers
-	// on a crash between the two, and "start with this" arriving twice is a
-	// different instruction from the one that was left.
-	const queuedForThisRun: readonly Message[] = params.topicStateStore
-		? await drainQueuedMessages(params.topicStateStore, params.topicId, params.tenantId).catch(
-				(err: unknown) => {
-					log.debug('Could not drain the topic queue; starting without it', {
-						'namzu.topic.id': params.topicId,
-						'namzu.error.message': toErrorMessage(err),
-					})
-					return []
-				},
-			)
-		: []
-
-	// One effective list, used everywhere the run is seeded from. Three
-	// branches below push from it, and computing it at each would be three
-	// places to forget the queue.
-	//
-	// Stored attachments are resolved HERE, once, before the messages reach
-	// the run record. Resolving later — at the provider boundary — would put
-	// refs in the durable transcript and in every checkpoint, and a run
-	// resumed against a store that had since forgotten a ref would fail
-	// replaying its own history rather than at the moment somebody asked for
-	// the bytes. Every failure refuses: a message that silently lost its
-	// image is a model answering about a picture it never saw.
-	const seeded: Message[] =
-		queuedForThisRun.length > 0 ? [...queuedForThisRun, ...params.messages] : params.messages
-	let resolvedInitialMessages: Message[]
-	let attachmentResolutionCancelled = false
-	try {
-		resolvedInitialMessages = [
-			...(await resolveAttachments(seeded, params.attachmentStore, {
-				signal: params.signal,
-				timeoutMs: params.attachmentResolveTimeoutMs,
-			})),
-		]
-		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({
 		budget,
-		...(topicState ? { topicPermissionMode: topicState.permissionMode } : {}),
-		...(params.permissionModeRef ? { permissionModeRef: params.permissionModeRef } : {}),
-		agentId: params.agentId,
-		agentName: params.agentName,
-		runConfig,
-		provider: resilientProvider,
-		workingDirectory: params.workingDirectory,
-		pricing: params.pricing,
-		enableActivityTracking: params.enableActivityTracking,
-		messages: initialMessages,
-		signal: params.signal,
-		sessionId: params.sessionId,
-		topicId: params.topicId,
-		projectId: params.projectId,
-		tenantId: params.tenantId,
-		pathBuilder: params.pathBuilder,
-		checkpointStore: params.checkpointStore,
-		runStore: params.runStore,
-		runId,
-		parentRunId: params.parentRunId,
-		depth: params.depth,
 		log,
-	})
-
-	// Built here because the plan-approval closure below captures it, and
-	// its `emit` resolves `eventTranslator` at CALL time — the translator is
-	// a `const` some lines further down.
-	//
-	// The HANDOUT is therefore deliberately NOT here. A host given the box
-	// at this point can call `set` synchronously, `emit` reaches
-	// `eventTranslator` inside its temporal dead zone, and the run dies
-	// before it starts. That is not hypothetical: it is what the first
-	// version of this did, and the test that hands out the box and
-	// immediately swaps the policy is the one that found it.
-	const approvalPolicy = createRunApprovalPolicy({
-		runId: ctx.runId,
-		initial: {
-			// By identity against the default, not by presence. `resumeHandler`
-			// is REQUIRED on `QueryParams` — `drainQuery` substitutes
-			// `autoApproveHandler` before calling here — so "is it set" is
-			// always yes and would name every run `host`, including the ones
-			// approving everything unattended. Identity is what actually
-			// separates the two.
-			name:
-				params.approvalPolicyName ??
-				(params.resumeHandler === autoApproveHandler ? AUTO_APPROVE_POLICY_NAME : 'host'),
-			handler: params.resumeHandler,
-		},
-		emit: (event) => eventTranslator.emitEvent(event),
-	})
-
-	const planApprovalIds = new Map<PlanId, CheckpointId>()
-	ctx.planManager.setApprovalHandler(async (request) => {
-		let checkpointId = planApprovalIds.get(request.planId)
-		if (!checkpointId) {
-			checkpointId = generateCheckpointId()
-			planApprovalIds.set(request.planId, checkpointId)
-		}
-		// `.current.handler`, never a captured `params.resumeHandler`. That
-		// capture is what made changing the policy mean ending the run.
-		const decision = await approvalPolicy.current.handler({
-			type: 'plan_approval',
-			runId: ctx.runId,
-			checkpointId,
-			plan: {
-				planId: request.planId,
-				title: request.title,
-				steps: request.steps.map((s, i) => ({
-					id: s.id,
-					description: s.description,
-					toolName: s.toolName,
-					agentId: s.agentId,
-					dependsOn: s.dependsOn,
-					order: s.order ?? i + 1,
-				})),
-				summary: request.summary,
-			},
-		})
-
-		if (decision.action === 'approve_plan') {
-			// Optional approve-with-edits channel: the host may attach
-			// feedback to an approval. `PlanApprovalResponse.feedback`
-			// already exists on the type; threading it through lets the
-			// coordinator's approve_plan tool surface the user's edits in
-			// the same tool_result that unblocks the park. Bare approvals
-			// stay byte-identical (`{ approved: true }`).
-			return decision.feedback
-				? { approved: true, feedback: decision.feedback }
-				: { approved: true }
-		}
-		if (decision.action === 'reject_plan') {
-			return { approved: false, feedback: decision.feedback }
-		}
-
-		return { approved: false, feedback: `Action: ${decision.action}` }
-	})
-
-	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)
-	let interruptHooksStarted = false
-	const executeUserInterruptHooks = async (terminalError: unknown): Promise<void> => {
-		if (
-			interruptHooksStarted ||
-			!params.pluginManager ||
-			!isCallerAbortError(terminalError, ctx.abortController.signal) ||
-			params.parentRunId !== undefined ||
-			(params.depth ?? 0) !== 0 ||
-			cancelCauseOf(ctx.abortController.signal.reason) !== 'user'
-		) {
-			return
-		}
-
-		interruptHooksStarted = true
-		try {
-			// Deliberately omit the already-aborted run signal. The lifecycle
-			// manager still supplies each handler its own deadline signal, while
-			// `run_interrupt`'s observational fan-out prevents one result from
-			// suppressing the cleanup hooks that follow it.
-			await params.pluginManager.executeHooks(
-				'run_interrupt',
-				{ runId: ctx.runId, cancelCause: 'user' },
-				eventTranslator.emitEvent,
-			)
-		} catch (error) {
-			// Cancellation is the terminal authority. A hook event sink or an
-			// unexpected manager failure is reported, but cannot turn Stop into a
-			// failed run or prevent the durable cancellation verdict.
-			ctx.log.error('Run interrupt hooks did not settle cleanly', {
-				[NAMZU.RUN_ID]: ctx.runId,
-				...errorAttributes(error),
-			})
-		}
-	}
+		ctx,
+		resilientProvider,
+		serving,
+		providerContextWindow,
+		modelContextWindows,
+		approvalPolicy,
+		eventTranslator,
+		executeUserInterruptHooks,
+		pendingHistoryRepairs,
+		initialMessages,
+		queuedForThisRun,
+		selectedResumeState,
+		attachmentResolutionCancelled,
+		streamIdleTimeoutMs,
+		sandboxTeardownTimeoutMs,
+		promptCache,
+		taskScheduler,
+	} = prepared
 
 	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.
-		// The dedicated root interrupt notification is the sole plugin exception:
-		// it runs after cancellation under its own deadline and cannot regain model
-		// or tool authority.
-		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
-			await executeUserInterruptHooks(terminalError)
-			yield* eventTranslator.drainPending()
-			yield* cancelledAssembler.handleError(terminalError, rootSpan)
-		} finally {
-			rootSpan.end()
-		}
-
-		return await cancelledAssembler.finalize()
+		return yield* settlePreStartCancellation(params, prepared)
 	}
 
 	const unsubscribeTaskStore = params.taskStore
@@ -1841,6 +1154,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			...(params.maxToolOutputChars !== undefined
 				? { maxToolOutputChars: params.maxToolOutputChars }
 				: {}),
+			...(params.toolResultGuardrails !== undefined
+				? { toolResultGuardrails: params.toolResultGuardrails }
+				: {}),
 			...(params.retainedToolPreviewChars !== undefined
 				? { retainedToolPreviewChars: params.retainedToolPreviewChars }
 				: {}),
@@ -2125,7 +1441,12 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 
 	const tracer = getTracer()
 
-	return yield* (async function* (): AsyncGenerator<RunEvent, Run> {
+	// Whether the run reached its settle. Read by the `finally` below, and
+	// the only thing that distinguishes a run that finished from one whose
+	// consumer walked away — see `settleAbandonedRun`.
+	let settled = false
+
+	const runBody = (async function* (): AsyncGenerator<RunEvent, Run> {
 		// Parent explicitly when a caller supplied one. Without this every
 		// run starts its OWN root trace, so a supervisor delegating to three
 		// children produced four disconnected traces instead of one tree —
@@ -2235,6 +1556,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// Decided during checkpoint restore, executed after the sandbox
 		// exists — the approved tools may well need it.
 		let pendingResume: PendingResumePlan | null = null
+		/**
+		 * The cadence park this resume answered, when the decision is one the
+		 * ordinary continue path carries out. See the restore path below.
+		 */
+		let answeredParkId: CheckpointId | undefined
 		/** Tool results recovered from the transcript; see the restore path. */
 		let recoveredResults: ReadonlyMap<string, { result: string; isError: boolean }> = new Map()
 		let emergencyManager: EmergencySaveManager | undefined
@@ -2390,6 +1716,49 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 						? planPendingResume(projectedCheckpoint, params.pendingDecision, ctx.log)
 						: null
 
+				// The park this resume ANSWERS even though there is no plan to
+				// carry the decision out through.
+				//
+				// `planPendingResume` covers the two arms whose decision has to
+				// reach something — the calls a `tool_review` park is about, the
+				// tool a `user_question` park is inside. An `iteration_checkpoint`
+				// park has neither, so it returns no plan, and the unpark further
+				// down — which ran only when there was one — never fired for it.
+				// A run that parked on the cadence, was resumed with
+				// `{action: 'continue'}` and went on to finish its work therefore
+				// kept reporting an OUTSTANDING park to `findPendingCheckpoint`,
+				// so a second resume of the finished run was refused with
+				// `awaiting-decision` for a decision already taken, and because
+				// `prune` skips an unresolved park the row could no longer be
+				// collected by anything.
+				//
+				// The decision IS carried out here — continuing is exactly what
+				// the loop below does, and a plan verdict is the answer to the
+				// question the plan park asked — so the park is resolved at the
+				// same point and with the same meaning "resolved" carries
+				// everywhere else: the record stays, and only its pending state
+				// ends. A `pause` is deliberately not resolved: it holds the
+				// park rather than answering it, which is how the live path
+				// treats it too. `answersParkOf` is the whole map, park type to
+				// answering decision, so an arm cannot go missing by being
+				// absent from a condition again — which is how the plan arm
+				// leaked a finished run's park.
+				//
+				// Resolving it does not depend on the resumed process being able
+				// to act on it, and that is deliberate: the plan's own fate is a
+				// separate defect (nothing restores a plan on the resume path at
+				// all, so the new process has none to approve, execute or
+				// reject) and making the resolution wait for it would leave the
+				// row outstanding for exactly the runs that need it cleared.
+				const parked = projectedCheckpoint.pending
+				answeredParkId =
+					params.pendingDecision &&
+					parked !== undefined &&
+					parked.resolvedAt === undefined &&
+					answersParkOf(parked.request.type, params.pendingDecision)
+						? projectedCheckpoint.id
+						: undefined
+
 				// Recover completed observations and explicitly unknown outcomes.
 				// A recorded start is not proof that its external effect failed.
 				const unanswered = interruptedToolCalls(projectedCheckpoint.messages)
@@ -2717,6 +2086,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 						})
 					}
 					yield* resultAssembler.completeRun(rootSpan)
+					// The run HAS settled, so the outer `finally` must not read
+					// this as an abandonment — it would persist a second time.
+					settled = true
 					return await resultAssembler.finalize()
 				}
 				sandbox = acquisition.sandbox
@@ -2787,7 +2159,15 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				ctx.runMgr.setStopReason('input_guardrail')
 				ctx.runMgr.setLastError(inputVerdict.reason ?? 'blocked by an input guardrail')
 				yield* resultAssembler.completeRun(rootSpan)
-				return ctx.runMgr.getRun()
+				// Same two lines as the sandbox path above, and for the same
+				// reasons — with one that path does not have. This return used to
+				// hand back `getRun()` without persisting, so the terminal state
+				// reached the disk only because the abandonment path found
+				// `settled` false and settled it a second time. A branch that
+				// exists for runs which did NOT settle must not be the reason a
+				// settled one is written down.
+				settled = true
+				return await resultAssembler.finalize()
 			}
 
 			// Honor the approval a human already gave, before the loop's
@@ -2813,149 +2193,59 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 
 				await applyPendingResume(pendingResume, ctx.runMgr, toolExecutor, recoveredResults)
 				yield* eventTranslator.drainPending()
-
-				// The decision has now actually been carried out, so the park
-				// is no longer outstanding. Without this the checkpoint keeps
-				// reporting `pending` with no `resolvedAt`, and an approval
-				// queue re-serves a destructive call that already ran — which
-				// defeats the entire point of recording the park.
-				const resolvedCheckpointId = pendingResume.checkpointId
-				if (params.pendingDecision) {
-					await checkpointMgr
-						.unpark(resolvedCheckpointId, params.pendingDecision)
-						.catch((err: unknown) => {
-							ctx.log.error('Applied a pending decision but failed to clear the park', {
-								[NAMZU.RUN_ID]: ctx.runId,
-								'namzu.checkpoint.id': resolvedCheckpointId,
-								'exception.message': err instanceof Error ? err.message : String(err),
-							})
-							return null
-						})
-				}
 			}
 
-			yield* iterationOrchestrator.runLoop()
-
-			if (params.pluginManager) {
-				const hookResults = await params.pluginManager.executeHooks(
-					'run_end',
-					{ runId: ctx.runId, signal: ctx.abortController.signal },
-					eventTranslator.emitEvent,
-				)
-				applyLifecycleHookResults('run_end', hookResults)
-				yield* eventTranslator.drainPending()
-				// A delegated run says so once more, by name, so a hook that
-				// only cares when a subagent finishes need not read parent ids
-				// off every run_end.
-				if (params.parentRunId !== undefined) {
-					const stopResults = await params.pluginManager.executeHooks(
-						'subagent_stop',
-						{
-							runId: ctx.runId,
-							parentRunId: params.parentRunId,
-							signal: ctx.abortController.signal,
-						},
-						eventTranslator.emitEvent,
-					)
-					applyLifecycleHookResults('subagent_stop', stopResults)
-					yield* eventTranslator.drainPending()
-				}
-			}
-
-			// Hand the step record to the run before it settles, so the
-			// returned `Run` carries it.
-			ctx.runMgr.setSteps(iterationOrchestrator.getSteps())
-
-			// Gates the FINAL result, not the stream — `text_delta` already
-			// reached the host as the model produced it. A rewrite is
-			// therefore a correction, and the event says so; buffering every
-			// token to gate the stream itself would trade the streaming UX
-			// for the guarantee, which is the host's call, not the SDK's.
-			if (params.outputGuardrails && params.outputGuardrails.length > 0) {
-				// Read what the run produced WITHOUT settling it. This used to
-				// call `markCompleted()` just to materialize the text, which
-				// force-marked a cancelled or paused run `completed` merely
-				// because a guardrail was configured — the presence of a
-				// safety check silently rewrote the run's own outcome.
-				const produced = ctx.runMgr.materializeResult()
-				const outputVerdict = await runOutputGuardrails(
-					params.outputGuardrails,
-					{ runId: ctx.runId, output: produced, messages: ctx.runMgr.messages },
-					ctx.log,
-				)
-
-				if (outputVerdict.blocked || outputVerdict.rewritten !== undefined) {
-					ctx.runMgr.clearStructuredOutput()
-					if (
-						params.structuredOutput &&
-						outputVerdict.rewritten !== undefined &&
-						ctx.runMgr.stopReason === 'end_turn'
-					)
-						ctx.runMgr.setStopReason('output_guardrail')
-				}
-
-				if (outputVerdict.blocked) {
-					await eventTranslator.emitEvent({
-						type: 'guardrail_triggered',
-						runId: ctx.runId,
-						stage: 'output',
-						action: 'block',
-						...(outputVerdict.name ? { guardrail: outputVerdict.name } : {}),
-						...(outputVerdict.reason ? { reason: outputVerdict.reason } : {}),
-					})
-					yield* eventTranslator.drainPending()
-					// Same reasoning as the input-guardrail branch above.
-					await ctx.runMgr.recordAudit({
-						what: { action: 'guardrail:output', resource: outputVerdict.name },
-						outcome: 'refused',
-						reason: outputVerdict.reason ?? 'blocked by an output guardrail',
-						...(params.persona?.identity.role ? { persona: params.persona.identity.role } : {}),
-					})
-					ctx.runMgr.setStopReason('output_guardrail')
-					ctx.runMgr.setLastError(outputVerdict.reason ?? 'blocked by an output guardrail')
-					ctx.runMgr.setResult('')
-				} else if (outputVerdict.rewritten !== undefined) {
-					await eventTranslator.emitEvent({
-						type: 'guardrail_triggered',
-						runId: ctx.runId,
-						stage: 'output',
-						action: 'rewrite',
-						...(outputVerdict.name ? { guardrail: outputVerdict.name } : {}),
-						...(outputVerdict.reason ? { reason: outputVerdict.reason } : {}),
+			// The decision has now actually been carried out, so the park it
+			// answered is no longer outstanding. Without this the checkpoint
+			// keeps reporting `pending` with no `resolvedAt`, and an approval
+			// queue re-serves a call that already ran — or a question already
+			// answered — which defeats the entire point of recording the park.
+			//
+			// Two arms reach this point, and being outside `if (pendingResume)`
+			// is what the second one needs. One is a plan whose decision was
+			// applied to a batch above. The other is the cadence arm, for which
+			// `planPendingResume` rightly produces no plan because the loop
+			// resuming IS its decision being carried out (`answeredParkId`, set
+			// on the restore path). Resolving only the first left a finished run
+			// reporting `awaiting-decision` forever.
+			//
+			// What is RECORDED depends on which of the two produced the plan. A
+			// recovery plan means the batch was answered by the crash path
+			// rather than by the decision — the calls the human was asked about
+			// were closed with explicitly unknown outcomes — so the human's
+			// answer must not be written down as what ended the park. The park is
+			// still resolved: the question is moot, and leaving it outstanding
+			// would have `findPendingCheckpoint` serve it as the newest
+			// outstanding park, so a host resuming it would rewind this run to
+			// the checkpoint the crash happened on and re-execute a batch the run
+			// has long since moved past.
+			const resolvedCheckpointId = pendingResume?.checkpointId ?? answeredParkId
+			const recordedDecision =
+				pendingResume?.source === 'recovery' && params.pendingDecision
+					? supersededByRecovery(params.pendingDecision)
+					: params.pendingDecision
+			if (recordedDecision && resolvedCheckpointId) {
+				await checkpointMgr.unpark(resolvedCheckpointId, recordedDecision).catch((err: unknown) => {
+					ctx.log.error('Applied a pending decision but failed to clear the park', {
+						[NAMZU.RUN_ID]: ctx.runId,
+						'namzu.checkpoint.id': resolvedCheckpointId,
+						'exception.message': err instanceof Error ? err.message : String(err),
 					})
-					yield* eventTranslator.drainPending()
-					ctx.runMgr.setResult(outputVerdict.rewritten)
-				}
-			}
-
-			if (params.consolidateInto && workingStateManager) {
-				const entry = consolidationEntry(workingStateManager.getState(), {
-					runId: ctx.runId,
-					at: Date.now(),
+					return null
 				})
-				if (entry) {
-					try {
-						const { entry: saved } = await params.consolidateInto.create(entry)
-						await eventTranslator.emitEvent({
-							type: 'memory_consolidated',
-							runId: ctx.runId,
-							memoryId: saved.id,
-							title: entry.title,
-							decisions: workingStateManager.getState().decisions.length,
-							discoveries: workingStateManager.getState().discoveries.length,
-							failures: workingStateManager.getState().failures.length,
-						})
-						yield* eventTranslator.drainPending()
-					} catch (error) {
-						ctx.log.warn('consolidation into the memory store failed', {
-							[NAMZU.RUN_ID]: ctx.runId,
-							'namzu.memory.error': toErrorMessage(error),
-						})
-					}
-				}
 			}
-			if (ctx.abortController.signal.aborted) ctx.runMgr.markCancelled()
-			yield* resultAssembler.completeRun(rootSpan)
+
+			yield* iterationOrchestrator.runLoop()
+
+			yield* finalizeRun({
+				ctx,
+				params,
+				eventTranslator,
+				takeSteps: () => iterationOrchestrator.getSteps(),
+				workingStateManager,
+				resultAssembler,
+				rootSpan,
+			})
 		} catch (err) {
 			// A failed run still spent its steps; report them.
 			ctx.runMgr.setSteps(iterationOrchestrator.getSteps())
@@ -2963,109 +2253,129 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			yield* eventTranslator.drainPending()
 			yield* resultAssembler.handleError(err, rootSpan)
 		} finally {
-			// Release the process's termination path as soon as this run is
-			// done with it. Leaving the handlers installed would keep a
-			// WeakRef'd, settled run as the crash target for the rest of the
-			// process's life.
-			emergencyManager?.detach()
-
-			// A background job outlives the tool call that started it — that
-			// is what it is for — so nothing but this stops it outliving the
-			// RUN. Scoped to this run's id: a shared registry serving several
-			// runs must not have one of them tear down another's work.
-			//
-			// Awaited, and its failure swallowed. A job that would not die is
-			// worth a log line, and is not worth retracting a run's answer.
-			unsubscribeJobExits?.()
-			// The wait-intent recorder listens on the same shared registry and
-			// leaks the same way if it is left attached.
-			awaitedJobs?.close()
-			// Only jobs bound to this run. Jobs a host bound to its session are
-			// the host's to stop, when the session ends.
-			if (params.backgroundJobs && (params.backgroundJobOwner ?? ctx.runId) === ctx.runId) {
-				try {
-					const stopped = await params.backgroundJobs.killOwner(ctx.runId)
-					if (stopped.length > 0) {
-						ctx.log.info('Background jobs stopped with the run', {
-							[NAMZU.RUN_ID]: ctx.runId,
-							'namzu.jobs.stopped': stopped.length,
-						})
-					}
-				} catch (jobErr) {
-					ctx.log.error('A background job did not stop cleanly', {
-						[NAMZU.RUN_ID]: ctx.runId,
-						...errorAttributes(jobErr),
-					})
-				}
-			}
-
-			// Same reasoning for the question channel: the tools outlive the
-			// run that bound them, so leaving it attached would have a later
-			// run's question written into this run's checkpoint store.
-			questionParks.unbind()
-
-			// Offer what the run learned to whoever decides what is worth
-			// keeping. In `finally` and awaited: a run that failed still
-			// discovered things, and a fire-and-forget write would race the
-			// process exiting on a one-shot CLI run. A throw here is
-			// swallowed — a memory that failed to form must not retract an
-			// answer that was already produced.
-			const candidate = memoryCandidateFor(ctx.runId, workingStateManager)
-			if (params.promoteMemory && candidate) {
-				try {
-					await params.promoteMemory(candidate)
-				} catch (promoteErr) {
-					ctx.log.error('Memory promotion threw — the run is unaffected', {
-						[NAMZU.RUN_ID]: ctx.runId,
-						'exception.message':
-							promoteErr instanceof Error ? promoteErr.message : String(promoteErr),
-					})
-				}
-			}
-
-			// --- Sandbox lifecycle: destroy after run ---
-			if (sandbox) {
-				const sandboxId = sandbox.id
-				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 })
-				} else {
-					ctx.log.error('Sandbox destroy failed', {
-						'namzu.sandbox.id': sandboxId,
-						...errorAttributes(teardown.error),
-					})
-				}
-			}
-
-			unsubscribeTaskStore?.()
-			// Keyed by HOW it settled, not just that it did: a run that was
-			// cancelled and a run that hit its budget have very different
-			// duration distributions, and averaging them together describes
-			// neither.
-			recordRunDuration(ctx.runMgr.getRun().status ?? 'unknown', Date.now() - runStartedAt)
-			rootSpan.end()
+			yield* releaseRunResources({
+				ctx,
+				eventTranslator,
+				emergencyManager,
+				unsubscribeJobExits,
+				unsubscribeTaskStore,
+				awaitedJobs,
+				backgroundJobs: params.backgroundJobs,
+				backgroundJobOwner: params.backgroundJobOwner,
+				questionParks,
+				workingStateManager,
+				promoteMemory: params.promoteMemory,
+				sandbox,
+				sandboxTeardownTimeoutMs,
+				runStartedAt,
+				rootSpan,
+			})
 		}
 
+		// Reached only by a run that settled on its own terms. `finalize()` is
+		// the only thing in this body that writes the durable half of the run,
+		// and a `return` completion arriving from a consumer (`break` out of
+		// `for await`, `gen.return()`) runs the `finally` above and stops short
+		// of here. The flag is what tells the two apart, and this is one of
+		// three sites that set it — the sandbox-acquisition and input-guardrail
+		// returns settle early and set it there. Set before the await rather
+		// than after, because a store that throws on the way out must not send
+		// the abandonment path over the same broken ground.
+		settled = true
 		return await resultAssembler.finalize()
 	})()
+
+	try {
+		return yield* runBody
+	} finally {
+		if (!settled) await settleAbandonedRun(ctx.runMgr, ctx.log)
+	}
 }
 
 /**
- * Hand a returning consumer what it missed, or tell it why it cannot have it.
+ * Write a terminal durable record for a run whose consumer walked away.
+ *
+ * `for await (… ) break` and an explicit `gen.return()` both end the run
+ * body early. Everything the run's `finally` owns still happens — background
+ * jobs are killed, the sandbox is destroyed, the span ends, the duration is
+ * recorded — and then the generator stops. `finalize()` never runs, so
+ * `persist()` never runs, and the store keeps whatever `init()` wrote: a
+ * non-terminal status for a run that no longer exists. `deriveRunStatus`
+ * reads that record back as `queued`, work waiting to start, and a host
+ * rebuilding its view from the store believes it.
+ *
+ * There is nothing to emit here and nothing to emit it to: the consumer
+ * that would have received the events is the one that left. This is about
+ * the durable record only.
+ *
+ * `cancelled` is the verdict, and it is chosen from the existing vocabulary
+ * because it is the one that is true. The run did not complete — no result
+ * was produced and no terminal event was ever delivered — and nothing
+ * failed, so `failed` would name an error that never happened; a run whose
+ * consumer stopped reading and whose processes were torn down under it is
+ * the same fact `markCancelled` already records when a run abort tears one
+ * down. It needs no new `RunExecutionStatus` and no new `StopReason`.
  *
- * Yields NOTHING on a refusal. A partial catch-up is the failure this exists to
- * prevent: a consumer that receives some of the gap folds it into its state and
- * cannot tell the state is wrong, where one that receives an explicit
- * `unavailable` re-derives from the transcript and is right. The run continues
- * either way — a stale cursor belongs to the client, and must not be able to
- * stop the work.
+ * A verdict the run already reached is left standing. A run that failed,
+ * or was cancelled, before the consumer left still says so; what the
+ * abandonment adds is that the record reaches the disk at all.
+ *
+ * Neither is a verdict written over a PARK. A park is a promise to a human
+ * that outlives the consumer: the run is resumable and somebody is still owed
+ * an answer, and `deriveRunStatus` reads a terminal status BEFORE it reads the
+ * park — so recording `cancelled` turns `awaiting_hitl` into `cancelled` for a
+ * run nobody answered for, while the unanswered question stays on the record
+ * and the checkpoint it belongs to stays the place a resume starts from. The
+ * durable state is asked rather than the in-memory one because the in-memory
+ * one is the misleading half here: `handleHITLDecision` emits `run_paused` and
+ * drains it BEFORE it calls `setStopReason('paused')`, so a consumer that
+ * leaves on that event leaves a run whose status is `running` and whose stop
+ * reason is unset at the exact instant its park is already durable.
+ * `findPendingCheckpoint` is the same read an approval queue is built from,
+ * expired parks included in its judgement: a park nobody answered in time is
+ * not somebody still being asked.
+ *
+ * Never throws. It runs while an exception may already be unwinding, and a
+ * store that cannot be written must not replace the run's real failure with
+ * its own.
  */
+async function settleAbandonedRun(runMgr: RunPersistence, log: Logger): Promise<void> {
+	try {
+		// A terminal verdict is written whatever the park says: `deriveRunStatus`
+		// settles a run that finished, failed or was cancelled BEFORE it looks at
+		// a park ("terminal beats parked"), so a settled run is not waiting for
+		// anybody and the row it already wrote must reach the disk. This ordering
+		// is also what keeps a stale park from suppressing the write.
+		if (!isTerminalStatus(runMgr.status)) {
+			const parked = await findPendingCheckpoint(runMgr.getCheckpointStore(), runMgr.getRunScope())
+			if (parked) {
+				// Left exactly as it stands: no verdict, no write. The park row is
+				// this run's durable state, and `persist()` here would add a
+				// second claim — `running`, for a process that is gone — beside it.
+				log.info('Abandoned run left parked for a human to answer', {
+					[NAMZU.RUN_ID]: runMgr.id,
+					'namzu.checkpoint.id': parked.id,
+					'namzu.runtime.park_type': parked.pending?.request.type,
+				})
+				return
+			}
+			runMgr.markCancelled()
+		}
+		// Once: the `finally` that calls this runs once, and every site in the
+		// run body that settles through `finalize()` sets `settled` before it
+		// returns, so the two can never both write.
+		await runMgr.persist()
+		log.info('Abandoned run recorded as cancelled', {
+			[NAMZU.RUN_ID]: runMgr.id,
+		})
+	} catch (err) {
+		log.error('Failed to record the terminal state of an abandoned run', {
+			[NAMZU.RUN_ID]: runMgr.id,
+			'exception.message': err instanceof Error ? err.message : String(err),
+		})
+	}
+}
+
 /** The text of the newest user turn, which is what a prompt hook is asked about. */
 function lastUserPrompt(messages: readonly Message[]): string {
 	for (let i = messages.length - 1; i >= 0; i--) {
@@ -3075,40 +2385,6 @@ function lastUserPrompt(messages: readonly Message[]): string {
 	return ''
 }
 
-async function* catchUpFromCursor(
-	runMgr: RunPersistence,
-	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 } : {}),
-		},
-		missed,
-	)
-
-	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
-}
-
 type DrainQueryParams = Omit<QueryParams, 'resumeHandler'> & {
 	resumeHandler?: ResumeHandler
 }