@namzu/sdk 43.0.0 → 44.1.0

package/src/runtime/query/iteration/index.ts

@@ -33,14 +33,14 @@ import {
 } from '../../../types/message/index.js'
 import { classifyProviderError } from '../../../types/provider/errors.js'
 import type { ChatCompletionResponse } from '../../../types/provider/index.js'
-import type { AnswerReview, AnswerReviewContext } from '../../../types/run/answer-review.js'
+import type { AnswerReview, AnswerReviewContext } from '../../../types/session/answer-review.js'
 import type {
-	RunEvent,
+	SessionEvent,
 	StepFailure,
 	StepProvenance,
 	StepResult,
 	StopReason,
-} from '../../../types/run/index.js'
+} from '../../../types/session/index.js'
 import type { LLMToolSchema, ToolRegistryContract } from '../../../types/tool/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
 import { stableDigest } from '../../../utils/hash.js'
@@ -74,7 +74,7 @@ import {
 import type { IterationContext } from './phases/index.js'
 import { runPlanGate } from './phases/plan.js'
 import { runToolReview } from './phases/tool-review.js'
-import { refreshWorkingMemory } from './phases/working-memory.js'
+import { refreshWorkingMemory, splitWorkingMemoryForRequest } from './phases/working-memory.js'
 import { streamWithProviderRejectedImageRecovery } from './provider-rejected-image.js'
 import {
 	type StepShaping,
@@ -105,16 +105,16 @@ export type { PhaseSignal } from './phases/index.js'
 export type { ToolReviewOutcome } from './phases/index.js'
 
 /**
- * How many times an answer may be handed back before the run stops.
+ * How many times an answer may be handed back before the turn stops.
  *
  * Bounded for the same reason the structured-output re-prompt is: a judge
  * that never accepts would otherwise spend the whole token budget
- * rediscovering that, and the run would end on a budget error rather than
+ * rediscovering that, and the turn would end on a budget error rather than
  * on the thing that actually went wrong.
  */
 const DEFAULT_ANSWER_REVIEW_LIMIT = 3
 
-// Ending a run changes the available actions, not the strength of its evidence.
+// Ending a turn changes the available actions, not the strength of its evidence.
 // Use the same standard for warning closure and empty-completion recovery.
 const CLOSING_RESPONSE_GUIDANCE =
 	'Give a concise response using only what the available evidence supports. Attribute unverified statements to their source instead of presenting them as observed facts. If evidence is missing or conflicting, state what cannot be established. Do not claim unfinished work is complete. Do not request any more tool calls.'
@@ -136,20 +136,20 @@ export class IterationOrchestrator {
 		| import('../../../advisory/executor.js').AdvisoryTurnContext
 		| undefined {
 		const turn = this.advisoryTurn
-		if (!turn || turn.iteration !== this.ctx.runMgr.currentIteration) return undefined
-		const start = this.ctx.runMgr.messages.indexOf(turn.response)
+		if (!turn || turn.iteration !== this.ctx.recorder.currentIteration) return undefined
+		const start = this.ctx.recorder.messages.indexOf(turn.response)
 		if (start < 0) return undefined
 		return {
 			iteration: turn.iteration,
 			requestMessages: turn.requestMessages,
-			subsequentMessages: this.ctx.runMgr.messages.slice(start),
+			subsequentMessages: this.ctx.recorder.messages.slice(start),
 		}
 	}
 	/** Rejections so far. See {@link DEFAULT_ANSWER_REVIEW_LIMIT}. */
 	private answerReviewAttempts = 0
 	/**
-	 * The last request envelope this run recorded, so an unchanged one
-	 * costs a hash and no event. Per RUNNER, not module-level: two runs in
+	 * The last request envelope this turn recorded, so an unchanged one
+	 * costs a hash and no event. Per RUNNER, not module-level: two turns in
 	 * one process must not suppress each other's first envelope.
 	 */
 	private lastEnvelopeKey: string | undefined
@@ -166,10 +166,10 @@ export class IterationOrchestrator {
 	/**
 	 * The previous iteration held a `stopWhen` decision open for a worker.
 	 *
-	 * Set when the stop predicate fired and the run took one extra turn to
-	 * read a delegated result, so the turn that then ends the run can report
+	 * Set when the stop predicate fired and the turn took one extra turn to
+	 * read a delegated result, so the turn that then ends the turn can report
 	 * WHY it is over. Without it the outcome was right and the record was
-	 * wrong: the run stopped because the host said so and reported `end_turn`,
+	 * wrong: the turn stopped because the host said so and reported `end_turn`,
 	 * and this repo carries thirteen `StopReason` values precisely so that a
 	 * run which ends for a nameable reason names it.
 	 *
@@ -266,7 +266,7 @@ export class IterationOrchestrator {
 			})
 			await this.ctx.emitEvent({
 				type: 'capability_warning',
-				runId: this.ctx.runMgr.id,
+				turnId: this.ctx.recorder.turnId,
 				capability,
 				contentSource: 'tool-result',
 				providerId: this.ctx.provider.id,
@@ -279,19 +279,19 @@ export class IterationOrchestrator {
 	}
 
 	/**
-	 * Adopt the run's span after construction.
+	 * Adopt the turn's span after construction.
 	 *
 	 * The orchestrator is built before `query()` enters its generator body,
-	 * which is where the run span is created — so the parent cannot be a
+	 * which is where the turn span is created — so the parent cannot be a
 	 * constructor argument without reordering setup around one field.
 	 */
 	setRootSpan(span: Span): void {
 		this.ctx = { ...this.ctx, rootSpan: span }
 	}
 
-	async *runLoop(): AsyncGenerator<RunEvent> {
-		const { runConfig, runMgr } = this.ctx
-		const { model } = runConfig
+	async *runLoop(): AsyncGenerator<SessionEvent> {
+		const { turnConfig, recorder } = this.ctx
+		const { model } = turnConfig
 		const tracer = getTracer()
 		// Resume hydration happens after construction, before the loop starts.
 		this.latestUserMessage = this.ctx.checkpointMgr.restoredLatestUserMessage
@@ -299,22 +299,29 @@ export class IterationOrchestrator {
 		this.structuredReviewAttempts = this.ctx.checkpointMgr.restoredStructuredReviewAttempts ?? 0
 		this.nativeStructuredAttempts = this.ctx.checkpointMgr.restoredNativeStructuredAttempts ?? 0
 		if (!this.latestUserMessage) {
-			for (const message of runMgr.messages) this.rememberUserMessage(message, false)
+			for (const message of recorder.messages) this.rememberUserMessage(message, false)
 		}
 		// The restored field can outlive the historical message it describes.
 		// Only known post-checkpoint arrivals may supersede it, never an old
 		// retained user turn encountered while scanning restored history.
 		for (const message of this.ctx.resumedInput ?? []) this.rememberUserMessage(message)
 
-		// One context-overflow relief per *stuck point*, not per run.
+		// What a recoverable failure pauses on when it lands before this
+		// loop wrote a checkpoint of its own: without it a 429 on the first
+		// request failed the turn, while the same 429 one request later
+		// paused it. Taken after the intent above is known, so the
+		// checkpoint names the message the turn is answering.
+		await this.ctx.checkpointMgr.markLoopStart?.(recorder)
+
+		// One context-overflow relief per *stuck point*, not per turn.
 		//
 		// The latch exists so that a second overflow immediately after a
 		// successful compaction — meaning the prompt is irreducible — stops
 		// instead of looping. It was never meant to disarm the mechanism for
-		// the rest of the run, which is what a run-scoped flag did: one
+		// the rest of the turn, which is what a turn-scoped flag did: one
 		// relief at iteration 3 left iteration 40 to die on an overflow with
 		// obvious moves left. It is cleared by a turn that actually
-		// succeeded, which is the evidence that the run is no longer stuck.
+		// succeeded, which is the evidence that the turn is no longer stuck.
 		let overflowRelieved = false
 
 		const planSignal = yield* runPlanGate(this.ctx)
@@ -324,7 +331,7 @@ export class IterationOrchestrator {
 		// beside `iterSpan.end()` below: this loop leaves by eight `break`s,
 		// two `return`s and a `throw`, and a rule every future edit has to
 		// remember is a rule that gets forgotten — measured, it had been. Only
-		// the ordinary final-answer exit consulted the inbox, so a run that
+		// the ordinary final-answer exit consulted the inbox, so a turn that
 		// ended on a terminal tool, a structured output or the host's
 		// `stopWhen` settled over a finished worker's output and threw it away.
 		// A `finally` also covers a generator abandoned by its consumer, which
@@ -332,22 +339,22 @@ export class IterationOrchestrator {
 		try {
 			while (true) {
 				if (this.ctx.abortController.signal.aborted) {
-					runMgr.setStopReason('cancelled')
-					runMgr.markCancelled()
+					recorder.setStopReason('cancelled')
+					recorder.markCancelled()
 					break
 				}
 				if (
 					this.ctx.structuredOutput?.mode === 'native' &&
 					this.nativeStructuredAttempts > this.structuredOutputRetryLimit()
 				) {
-					runMgr.setStopReason('structured_output_failed')
+					recorder.setStopReason('structured_output_failed')
 					break
 				}
 				if (
 					this.ctx.reviewAnswer &&
 					this.answerReviewAttempts > (this.ctx.maxAnswerReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT)
 				) {
-					runMgr.setStopReason('answer_rejected')
+					recorder.setStopReason('answer_rejected')
 					break
 				}
 				if (
@@ -355,7 +362,7 @@ export class IterationOrchestrator {
 					this.structuredReviewAttempts >
 						(this.ctx.structuredOutput.maxReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT)
 				) {
-					runMgr.setStopReason('answer_rejected')
+					recorder.setStopReason('answer_rejected')
 					break
 				}
 				// Read AND clear, in that order, in this one place.
@@ -372,30 +379,33 @@ export class IterationOrchestrator {
 				const stopWasDeferredForOutstandingWork = this.stopDeferredForOutstandingWork
 				this.stopDeferredForOutstandingWork = false
 
-				const guardResult = this.ctx.guard.beforeIteration(runMgr, this.ctx.abortController.signal)
+				const guardResult = this.ctx.guard.beforeIteration(
+					recorder,
+					this.ctx.abortController.signal,
+				)
 
 				if (guardResult.shouldStop) {
 					if (guardResult.isCancelled) {
-						this.ctx.log.info('Run cancelled by signal', {
-							[NAMZU.RUN_ID]: runMgr.id,
+						this.ctx.log.info('Turn cancelled by signal', {
+							[NAMZU.TURN_ID]: recorder.turnId,
 						})
-						runMgr.setStopReason('cancelled')
-						runMgr.markCancelled()
+						recorder.setStopReason('cancelled')
+						recorder.markCancelled()
 						break
 					}
 
 					const stopReason = guardResult.stopReason ?? 'end_turn'
 					this.ctx.log.info('Guard enforcing stop', {
-						[NAMZU.RUN_ID]: runMgr.id,
+						[NAMZU.TURN_ID]: recorder.turnId,
 						'namzu.runtime.stop_reason': stopReason,
-						[NAMZU.ITERATION]: runMgr.currentIteration,
-						'namzu.runtime.input_tokens': runMgr.tokenUsage.promptTokens,
-						'namzu.runtime.output_tokens': runMgr.tokenUsage.completionTokens,
+						[NAMZU.ITERATION]: recorder.currentIteration,
+						'namzu.runtime.input_tokens': recorder.tokenUsage.promptTokens,
+						'namzu.runtime.output_tokens': recorder.tokenUsage.completionTokens,
 					})
 					// A hard stop has no budget left for another model request.
 					// Closing prose is requested at the warning threshold while
 					// headroom remains; the completed work is already in history.
-					runMgr.setStopReason(stopReason)
+					recorder.setStopReason(stopReason)
 					break
 				}
 
@@ -404,13 +414,13 @@ export class IterationOrchestrator {
 				// and so can only speak after the step it disliked has already
 				// run and been paid for; this is the seam a host with a live
 				// rate limit or a revoked tenant actually needs.
-				const veto = await beforeStep(this.stepShaping(), runMgr.currentIteration + 1)
-				// The hook may settle because its run signal was aborted. Stop
+				const veto = await beforeStep(this.stepShaping(), recorder.currentIteration + 1)
+				// The hook may settle because its turn signal was aborted. Stop
 				// before interpreting that settlement as a policy refusal or
 				// counting an iteration that will never reach the provider.
 				if (this.ctx.abortController.signal.aborted) {
-					runMgr.setStopReason('cancelled')
-					runMgr.markCancelled()
+					recorder.setStopReason('cancelled')
+					recorder.markCancelled()
 					break
 				}
 				if (veto) {
@@ -418,23 +428,23 @@ export class IterationOrchestrator {
 					// the frozen inventory LOG-22 exists to drain; a new call site
 					// has no reason to join it.
 					this.ctx.log.info('Step refused by beforeStep', {
-						[NAMZU.RUN_ID]: runMgr.id,
-						[NAMZU.ITERATION]: runMgr.currentIteration + 1,
+						[NAMZU.TURN_ID]: recorder.turnId,
+						[NAMZU.ITERATION]: recorder.currentIteration + 1,
 						'namzu.step.veto_reason': veto.reason,
 					})
-					runMgr.setLastError(`beforeStep refused the next step: ${veto.reason}`)
-					runMgr.setStopReason('step_refused')
+					recorder.setLastError(`beforeStep refused the next step: ${veto.reason}`)
+					recorder.setStopReason('step_refused')
 					break
 				}
 
 				const forceFinalize = guardResult.forceFinalize
-				const iterationNum = runMgr.incrementIteration()
+				const iterationNum = recorder.incrementIteration()
 				this.ctx.log.debug('Iteration started', {
-					[NAMZU.RUN_ID]: runMgr.id,
+					[NAMZU.TURN_ID]: recorder.turnId,
 					[NAMZU.ITERATION]: iterationNum,
 					[GENAI.REQUEST_MODEL]: model,
 					'namzu.runtime.force_finalize': forceFinalize,
-					'namzu.runtime.message_count': runMgr.messages.length,
+					'namzu.runtime.message_count': recorder.messages.length,
 				})
 
 				const iterationActivity = this.ctx.activityStore.create({
@@ -447,7 +457,7 @@ export class IterationOrchestrator {
 
 				// Parent explicitly: this body is an async generator, so the
 				// ambient context at resume time belongs to the CONSUMER, not to
-				// whoever created the run span. Without this every iteration
+				// whoever created the turn span. Without this every iteration
 				// emits as its own root and a 20-turn run shows up as 21
 				// disconnected traces.
 				const iterSpan = tracer.startSpan(
@@ -472,8 +482,8 @@ export class IterationOrchestrator {
 				// where they always did, so compaction and the working-memory
 				// refresh stay outside a successful step's window.
 				let stepStartedAt = Date.now()
-				let usageBefore: TokenUsage = { ...runMgr.tokenUsage }
-				let costBefore: CostInfo = { ...runMgr.costInfo }
+				let usageBefore: TokenUsage = { ...recorder.tokenUsage }
+				let costBefore: CostInfo = { ...recorder.costInfo }
 				let stepModel = model
 				let stepMessageId: MessageId | undefined
 				let stepResponse: ChatCompletionResponse | undefined
@@ -484,18 +494,19 @@ export class IterationOrchestrator {
 					// the try rather than before it: a throw from any of these left
 					// the span open, and an iteration span that never ends is a
 					// trace that never closes — the export is incomplete for exactly
-					// the run that failed.
+					// the turn that failed.
 					this.ctx.toolExecutor.setParentSpan(iterSpan)
 
 					iterSpan.setAttributes({
 						[NAMZU.ITERATION]: iterationNum,
-						[NAMZU.RUN_ID]: runMgr.id,
+						[GENAI.CONVERSATION_ID]: recorder.sessionId,
+						[NAMZU.TURN_ID]: recorder.turnId,
 						[GENAI.REQUEST_MODEL]: model,
 					})
 
 					await this.ctx.emitEvent({
 						type: 'iteration_started',
-						runId: runMgr.id,
+						turnId: recorder.turnId,
 						iteration: iterationNum,
 					})
 					yield* this.ctx.drainPending()
@@ -504,7 +515,8 @@ export class IterationOrchestrator {
 						const hookResults = await this.ctx.pluginManager.executeHooks(
 							'iteration_start',
 							{
-								runId: runMgr.id,
+								sessionId: recorder.sessionId,
+								turnId: recorder.turnId,
 								iteration: iterationNum,
 								signal: this.ctx.abortController.signal,
 							},
@@ -528,7 +540,7 @@ export class IterationOrchestrator {
 					// risks a 400 because the history still carries
 					// tool_use/tool_result blocks.
 					// Snapshot the cumulative counters so the step can report ITS
-					// own usage rather than the run total.
+					// own usage rather than the turn total.
 					stepStartedAt = Date.now()
 
 					// Shape this step before calling the model. `stopWhen` decides
@@ -536,9 +548,9 @@ export class IterationOrchestrator {
 					// supplied no hook.
 					const contextModelBeforePreparation = this.ctx.contextModel ?? model
 					const step = await prepareStep(this.stepShaping(), iterationNum)
-					// Preparation inference belongs to the run, not the main-model step.
-					usageBefore = { ...runMgr.tokenUsage }
-					costBefore = { ...runMgr.costInfo }
+					// Preparation inference belongs to the turn, not the main-model step.
+					usageBefore = { ...recorder.tokenUsage }
+					costBefore = { ...recorder.costInfo }
 					stepModel = step.model ?? model
 					await selectContextModel(this.stepShaping(), stepModel)
 					// Preserve post-compaction preparation/recall semantics. A changed
@@ -564,20 +576,21 @@ export class IterationOrchestrator {
 					const enforceToolInputSchema = enforcedModelInputToolNames(this.ctx.tools, llmTools)
 					stepModel = step.model ?? model
 
-					const baseMessages = forceFinalize
-						? [
-								...runMgr.messages,
-								createRuntimeContextMessage(
-									`[SYSTEM] You are approaching your resource limits. ${CLOSING_RESPONSE_GUIDANCE}`,
-									'limit-finalization',
-								),
-							]
-						: runMgr.messages
+					// The closing directive is appended LAST, after every piece of
+					// request-only context below, so it is the final thing the model
+					// reads on a forced-final step.
+					const closingDirective = forceFinalize
+						? createRuntimeContextMessage(
+								`[SYSTEM] You are approaching your resource limits. ${CLOSING_RESPONSE_GUIDANCE}`,
+								'limit-finalization',
+							)
+						: undefined
+					const baseMessages = recorder.messages
 
 					// Step guidance is appended to the REQUEST, never pushed onto
-					// the run's history: it applies to this step only, and pushing
+					// the turn's history: it applies to this step only, and pushing
 					// it would accumulate one stale instruction per iteration.
-					// Copy before it crosses the provider boundary. `runMgr.messages`
+					// Copy before it crosses the provider boundary. `recorder.messages`
 					// is the LIVE run array, and the loop pushes onto it after the
 					// call returns — so a driver that retains what it was handed
 					// (to log it, cache it, or replay it on retry) watched its own
@@ -597,7 +610,7 @@ export class IterationOrchestrator {
 					// A supervision change rides the same ephemeral slot, and for
 					// the same reason: it applies to what happens next, not to the
 					// run's history. The model plans around how closely it is being
-					// watched — a run that silently stops asking a human leaves it
+					// watched — a turn that silently stops asking a human leaves it
 					// batching destructive calls it expects to be reviewed, and one
 					// that silently starts leaves it waiting on permission nobody
 					// is left to give.
@@ -609,7 +622,7 @@ export class IterationOrchestrator {
 					const policyNotice = policyChange
 						? `Approval policy changed from "${policyChange.from}" to "${policyChange.to}" (${policyChange.reason}). Tool calls from here on are reviewed under the new policy.`
 						: null
-					// State that changed during the run, reported once per turn.
+					// State that changed during the turn, reported once per turn.
 					// `turn` contributions are recomputed here, not fixed when the
 					// run's prompt is assembled. They retain system authority and
 					// may affect caching just like the other system contributions.
@@ -618,31 +631,51 @@ export class IterationOrchestrator {
 							iteration: iterationNum,
 						}) ?? []
 
+					// Request-only context: observations that need no system
+					// authority and change from request to request. They ride
+					// runtime-context messages of kind `step-context` after the
+					// history, which every driver keeps there and a caching driver
+					// ends its breakpoint before — so a changed pin or a new turn
+					// snapshot costs its own tokens, not a re-read of the history.
+					// The working-memory slot keeps its place in the turn's history
+					// (compaction preserves it there) and leaves the request's
+					// system run here.
+					const workingMemory = splitWorkingMemoryForRequest(baseMessages)
+					const contextSections =
+						this.ctx.promptContributions?.render('context', {
+							iteration: iterationNum,
+						}) ?? []
+
 					const stepPreamble = [step.system, stepSkills, policyNotice, ...turnSections]
 						.filter(Boolean)
 						.join('\n\n')
 					const requestHistory = stepPreamble
-						? [...baseMessages, createSystemMessage(stepPreamble)]
-						: [...baseMessages]
+						? [...workingMemory.history, createSystemMessage(stepPreamble)]
+						: [...workingMemory.history]
+					if (workingMemory.context) requestHistory.push(workingMemory.context)
+					if (contextSections.length > 0)
+						requestHistory.push(stepContextMessage(contextSections.join('\n\n')))
 					if (step.context) requestHistory.push(stepContextMessage(step.context))
 					const messages = projectRequestRichContent(
 						this.projectObservations(requestHistory),
-						this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
+						this.ctx.turnConfig.maxRequestRichContentBytes ??
+							DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
 					appendWorkContext(this.stepShaping(), messages, iterationNum, step)
+					if (closingDirective) messages.push(closingDirective)
 					await this.reportUnsupportedToolResults(messages)
 					yield* this.ctx.drainPending()
 
 					// What the model is about to be ASKED, recorded when it
-					// changed. `run_started` carries one system prompt and tool
+					// changed. `turn_started` carries one system prompt and tool
 					// schemas never reached the transcript at all — while
 					// `prepareStep` rewrites the system text, narrows the tool
 					// list or swaps the model, and a step's skills ride the
 					// ephemeral preamble above. So a transcript showed one
-					// question for a run that had asked several.
+					// question for a turn that had asked several.
 					//
 					// Emitted only on a change: the digest is compared against
-					// the last one this run recorded, so the common case costs
+					// the last one this turn recorded, so the common case costs
 					// one hash and nothing else. Copying an unchanged system
 					// prompt every iteration is the fastest way to make a
 					// durable log too large to read.
@@ -650,7 +683,7 @@ export class IterationOrchestrator {
 						model: stepModel,
 						// Read off `messages`, which is what the request is actually
 						// built from — including the ephemeral preamble. Recomputing
-						// it from the run's history would describe a request nobody
+						// it from the turn's history would describe a request nobody
 						// sent the moment the two diverge.
 						systemPrompt: messages
 							.filter((m) => m.role === 'system')
@@ -669,7 +702,7 @@ export class IterationOrchestrator {
 						this.lastEnvelopeKey = envelopeKey
 						await this.ctx.emitEvent?.({
 							type: 'request_envelope',
-							runId: runMgr.id,
+							turnId: recorder.turnId,
 							iteration: iterationNum,
 							...envelope,
 							toolNames: Object.freeze([...envelope.toolNames]),
@@ -690,21 +723,22 @@ export class IterationOrchestrator {
 						const hookResults = await this.ctx.pluginManager.executeHooks(
 							'pre_llm_call',
 							{
-								runId: runMgr.id,
+								sessionId: recorder.sessionId,
+								turnId: recorder.turnId,
 								iteration: iterationNum,
 								signal: this.ctx.abortController.signal,
-								// Built inside the guard: a run with no plugins installed
+								// Built inside the guard: a turn with no plugins installed
 								// pays nothing for a projection nobody reads.
 								request: Object.freeze({
 									context,
 									model: stepModel,
 									// Copied per turn, not handed over live: these are the
 									// run's own message objects, and a hook writing into
-									// one would edit the history the run is about to send.
+									// one would edit the history the turn is about to send.
 									messages: Object.freeze(messages.map((m) => Object.freeze({ ...m }))),
 									toolNames: Object.freeze(llmTools.map((t) => t.function.name)),
-									temperature: step.temperature ?? runConfig.temperature,
-									maxTokens: step.maxResponseTokens ?? runConfig.maxResponseTokens,
+									temperature: step.temperature ?? turnConfig.temperature,
+									maxTokens: step.maxResponseTokens ?? turnConfig.maxResponseTokens,
 								}),
 							},
 							this.ctx.emitEvent,
@@ -716,7 +750,7 @@ export class IterationOrchestrator {
 					// Phase 4 (ses_001-tool-stream-events): consume the
 					// streaming response natively, emitting message and
 					// tool-input lifecycle events as deltas arrive. The
-					// helper yields RunEvents through drainPending() so SSE
+					// helper yields SessionEvents through drainPending() so SSE
 					// consumers see live progress; its return value is the
 					// aggregated `ChatCompletionResponse` for the legacy
 					// downstream paths (assistantMsg construction, working
@@ -776,20 +810,22 @@ export class IterationOrchestrator {
 									: llmTools.length > 0
 										? step.toolChoice
 										: undefined,
-							temperature: step.temperature ?? runConfig.temperature,
-							maxTokens: step.maxResponseTokens ?? runConfig.maxResponseTokens,
+							temperature: step.temperature ?? turnConfig.temperature,
+							maxTokens: step.maxResponseTokens ?? turnConfig.maxResponseTokens,
 							cacheControl: { type: 'auto' },
-							...(runConfig.thinking ? { thinking: runConfig.thinking } : {}),
-							...(runConfig.effort ? { effort: runConfig.effort } : {}),
-							...(!forceFinalize && runConfig.webSearch ? { webSearch: runConfig.webSearch } : {}),
-							// Thread the run abort into the model call so a Stop tears the
+							...(turnConfig.thinking ? { thinking: turnConfig.thinking } : {}),
+							...(turnConfig.effort ? { effort: turnConfig.effort } : {}),
+							...(!forceFinalize && turnConfig.webSearch
+								? { webSearch: turnConfig.webSearch }
+								: {}),
+							// Thread the turn abort into the model call so a Stop tears the
 							// in-flight turn down (provider passes it to fetch; the consumer
 							// also races it). Inert when never aborted.
 							signal: this.ctx.abortController.signal,
 						},
 						this.ctx.emitEvent,
 						this.ctx.drainPending,
-						runMgr.id,
+						recorder.turnId,
 						iterationNum,
 						forceFinalize,
 						this.ctx.log,
@@ -801,6 +837,7 @@ export class IterationOrchestrator {
 						Boolean(
 							this.ctx.reviewAnswer || this.ctx.structuredOutput?.review || this.ctx.advisoryCtx,
 						),
+						recorder.sessionId,
 					)
 					stepResponse = response
 					const reviewRequest: ReviewRequest = {
@@ -841,13 +878,13 @@ export class IterationOrchestrator {
 					// model it was asked for. This is the seam that ended the
 					// always-zero cost: the rate lookup happens per turn,
 					// against who actually answered, rather than against one
-					// table the run was constructed with.
-					runMgr.recordTurnUsage(response.usage, {
+					// table the turn was constructed with.
+					recorder.recordTurnUsage(response.usage, {
 						providerId: servedBy.providerId,
 						model: servedBy.model,
 					})
 
-					// The turn went through, so the run is not sitting on an
+					// The turn went through, so the turn is not sitting on an
 					// irreducible prompt any more. Re-arm relief for the next one.
 					overflowRelieved = false
 
@@ -855,7 +892,8 @@ export class IterationOrchestrator {
 						const hookResults = await this.ctx.pluginManager.executeHooks(
 							'post_llm_call',
 							{
-								runId: runMgr.id,
+								sessionId: recorder.sessionId,
+								turnId: recorder.turnId,
 								iteration: iterationNum,
 								signal: this.ctx.abortController.signal,
 								response: Object.freeze({
@@ -874,7 +912,7 @@ export class IterationOrchestrator {
 					}
 
 					this.ctx.log.debug('LLM response received', {
-						[NAMZU.RUN_ID]: runMgr.id,
+						[NAMZU.TURN_ID]: recorder.turnId,
 						[NAMZU.ITERATION]: iterationNum,
 						'namzu.runtime.finish_reason': response.finishReason,
 						'namzu.runtime.has_content':
@@ -882,8 +920,8 @@ export class IterationOrchestrator {
 						'namzu.runtime.tool_call_count': response.message.toolCalls?.length ?? 0,
 						[GENAI.USAGE_INPUT_TOKENS]: response.usage.promptTokens,
 						[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
-						'namzu.usage.total_tokens': runMgr.tokenUsage.totalTokens,
-						'namzu.runtime.total_cost': runMgr.costInfo.totalCost,
+						'namzu.usage.total_tokens': recorder.tokenUsage.totalTokens,
+						'namzu.runtime.total_cost': recorder.costInfo.totalCost,
 					})
 
 					// The context figures ride with the spend figures because a
@@ -893,7 +931,7 @@ export class IterationOrchestrator {
 					// are measured here rather than left to be derived, since the
 					// only correct derivation needs internals a host cannot see.
 					//
-					// Absent when the run has no compaction config: nothing then
+					// Absent when the turn has no compaction config: nothing then
 					// resolves a window, and inventing one would be the guess this
 					// replaces.
 					const contextFigures = this.ctx.compactionConfig
@@ -911,10 +949,10 @@ export class IterationOrchestrator {
 
 					await this.ctx.emitEvent({
 						type: 'token_usage_updated',
-						runId: runMgr.id,
-						usage: runMgr.tokenUsage,
-						budget: runMgr.budget?.summary(),
-						cost: runMgr.costInfo,
+						turnId: recorder.turnId,
+						usage: recorder.tokenUsage,
+						budget: recorder.budget?.summary(),
+						cost: recorder.costInfo,
 						...contextFigures,
 					})
 
@@ -939,7 +977,7 @@ export class IterationOrchestrator {
 						},
 						response.message.textParts,
 					)
-					runMgr.pushMessage(assistantMsg)
+					recorder.pushMessage(assistantMsg)
 					if (this.ctx.advisoryCtx && requestMessages) {
 						this.advisoryTurn = { iteration: iterationNum, requestMessages, response: assistantMsg }
 					}
@@ -988,7 +1026,7 @@ export class IterationOrchestrator {
 						// Every task-dispatch tool (create_task, continue_task, Agent)
 						// is BLOCKING: the worker's output returns as the dispatching
 						// tool_use's canonical tool_result, so by the time the model
-						// ends its turn nothing launched by this run should still be
+						// ends its turn nothing launched by this turn should still be
 						// in flight. A running task here is an orphan (interrupted
 						// tool execution, cancel race) with no delivery path back to
 						// the parent — the <task-notification> producer was removed
@@ -996,9 +1034,9 @@ export class IterationOrchestrator {
 						// out. Log the orphans honestly and end the turn normally.
 						if (!forceFinalize && this.hasRunningAgentTasks()) {
 							this.ctx.log.warn(
-								'LLM ended turn with agent tasks still running — ending run without waiting (orphan tasks have no delivery path)',
+								'LLM ended turn with agent tasks still running — ending turn without waiting (orphan tasks have no delivery path)',
 								{
-									[NAMZU.RUN_ID]: runMgr.id,
+									[NAMZU.TURN_ID]: recorder.turnId,
 									[NAMZU.ITERATION]: iterationNum,
 								},
 							)
@@ -1009,7 +1047,7 @@ export class IterationOrchestrator {
 						// It did not, and the ledger's own contract said it should:
 						// `StepResult` is documented as "what one iteration of the
 						// agent loop did" and `stepNumber` as "1-based, matching
-						// `iteration` on the run events". Every path below emits
+						// `iteration` on the turn events". Every path below emits
 						// `iteration_completed` with this iteration's number, and
 						// none of them recorded a step — so the events said
 						// iteration N happened and `steps` had no entry N. The
@@ -1041,7 +1079,7 @@ export class IterationOrchestrator {
 						// executor, and the empty-completion retry a few lines below
 						// all spend tokens inside an iteration without being one.
 						// Their usage reaches `run.tokenUsage` and no step, so the
-						// ledger reconciles with the run total for a run that makes
+						// ledger reconciles with the turn total for a turn that makes
 						// no side calls and undercounts by exactly those calls for a
 						// run that does. That residual is named rather than fixed
 						// here: attributing a side call needs a record that is not a
@@ -1075,16 +1113,16 @@ export class IterationOrchestrator {
 								)
 							else {
 								this.nativeStructuredAttempts++
-								runMgr.pushMessage(
+								recorder.pushMessage(
 									createRuntimeContextMessage(
 										'Return a complete JSON value matching the supplied response schema. Do not continue a partial JSON fragment.',
 										'structured-output',
 									),
 								)
-								const checkpoint = await this.ctx.checkpointMgr.create(runMgr, iterationNum)
+								const checkpoint = await this.ctx.checkpointMgr.create(recorder, iterationNum)
 								await this.ctx.emitEvent({
 									type: 'checkpoint_created',
-									runId: runMgr.id,
+									turnId: recorder.turnId,
 									checkpointId: checkpoint.id,
 									iteration: iterationNum,
 								})
@@ -1095,14 +1133,14 @@ export class IterationOrchestrator {
 							}
 							await this.ctx.emitEvent({
 								type: 'iteration_completed',
-								runId: runMgr.id,
+								turnId: recorder.turnId,
 								iteration: iterationNum,
 								hasToolCalls: false,
 							})
 							yield* this.ctx.drainPending()
 							if (this.ctx.abortController.signal.aborted || outcome === 'cancelled') {
-								runMgr.setStopReason('cancelled')
-								runMgr.markCancelled()
+								recorder.setStopReason('cancelled')
+								recorder.markCancelled()
 								break
 							}
 							if (outcome === 'accepted') {
@@ -1114,16 +1152,16 @@ export class IterationOrchestrator {
 									if (changed || inbound > 0) continue
 								}
 								if (this.ctx.abortController.signal.aborted) {
-									runMgr.setStopReason('cancelled')
-									runMgr.markCancelled()
+									recorder.setStopReason('cancelled')
+									recorder.markCancelled()
 									break
 								}
 								this.publishStructuredOutput()
-								runMgr.setStopReason('end_turn')
+								recorder.setStopReason('end_turn')
 								break
 							}
 							if (outcome === 'exhausted') {
-								runMgr.setStopReason(
+								recorder.setStopReason(
 									candidate.success ? 'answer_rejected' : 'structured_output_failed',
 								)
 								break
@@ -1155,16 +1193,16 @@ export class IterationOrchestrator {
 						//   - max_iterations bounds the loop in any case.
 						if (!forceFinalize && response.finishReason === 'length' && hasContent) {
 							this.ctx.log.info('LLM hit max_tokens mid-text — auto-continuing', {
-								[NAMZU.RUN_ID]: runMgr.id,
+								[NAMZU.TURN_ID]: recorder.turnId,
 								[NAMZU.ITERATION]: iterationNum,
 								[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
 							})
-							runMgr.pushMessage(
+							recorder.pushMessage(
 								createRuntimeContextMessage(AUTO_CONTINUATION_USER_MESSAGE, 'auto-continuation'),
 							)
 							await this.ctx.emitEvent({
 								type: 'iteration_completed',
-								runId: runMgr.id,
+								turnId: recorder.turnId,
 								iteration: iterationNum,
 								hasToolCalls: false,
 							})
@@ -1182,23 +1220,23 @@ export class IterationOrchestrator {
 							const limit = this.structuredOutputRetryLimit()
 							if (attempt > limit) {
 								this.ctx.log.warn('Structured output not produced within its retries', {
-									[NAMZU.RUN_ID]: runMgr.id,
+									[NAMZU.TURN_ID]: recorder.turnId,
 									'namzu.runtime.attempts': attempt - 1,
 								})
-								runMgr.setStopReason('structured_output_failed')
+								recorder.setStopReason('structured_output_failed')
 								break
 							}
 							this.ctx.log.info('Re-prompting for structured output', {
-								[NAMZU.RUN_ID]: runMgr.id,
+								[NAMZU.TURN_ID]: recorder.turnId,
 								'namzu.retry.attempt': attempt,
 								'namzu.runtime.limit': limit,
 							})
-							runMgr.pushMessage(
+							recorder.pushMessage(
 								createRuntimeContextMessage(STRUCTURED_OUTPUT_REPROMPT, 'structured-output'),
 							)
 							await this.ctx.emitEvent({
 								type: 'iteration_completed',
-								runId: runMgr.id,
+								turnId: recorder.turnId,
 								iteration: iterationNum,
 								hasToolCalls: false,
 							})
@@ -1210,10 +1248,10 @@ export class IterationOrchestrator {
 						//
 						// The stop predicate is only consulted after tools ran, so
 						// there was no seam here at all: the moment the model
-						// stopped calling tools the run finalized, whatever it had
+						// stopped calling tools the turn finalized, whatever it had
 						// produced. Verify-then-fix — run the build, feed the
 						// failure back, let it try again — meant starting a whole
-						// new run and re-supplying the context the first one had.
+						// new turn and re-supplying the context the first one had.
 						//
 						// Shaped after the structured-output re-prompt directly
 						// above, which solves the same problem for one specific
@@ -1226,45 +1264,45 @@ export class IterationOrchestrator {
 								stepModel,
 							)
 							if (this.ctx.abortController.signal.aborted) {
-								runMgr.setStopReason('cancelled')
-								runMgr.markCancelled()
+								recorder.setStopReason('cancelled')
+								recorder.markCancelled()
 								break
 							}
 							if (review && !review.accept) {
 								const attempt = ++this.answerReviewAttempts
-								runMgr.pushMessage(createRuntimeContextMessage(review.feedback, 'answer-review'))
+								recorder.pushMessage(createRuntimeContextMessage(review.feedback, 'answer-review'))
 								// Commit the consumed allowance with its feedback before another
 								// request, including exhaustion. Compaction cannot reset this quota.
-								const checkpoint = await this.ctx.checkpointMgr.create(runMgr, iterationNum)
+								const checkpoint = await this.ctx.checkpointMgr.create(recorder, iterationNum)
 								await this.ctx.emitEvent({
 									type: 'checkpoint_created',
-									runId: runMgr.id,
+									turnId: recorder.turnId,
 									checkpointId: checkpoint.id,
 									iteration: iterationNum,
 								})
 								if (this.ctx.abortController.signal.aborted) {
-									runMgr.setStopReason('cancelled')
-									runMgr.markCancelled()
+									recorder.setStopReason('cancelled')
+									recorder.markCancelled()
 									break
 								}
 								const limit = this.ctx.maxAnswerReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT
 								if (attempt > limit) {
-									this.ctx.log.warn('Answer rejected more times than the run allows', {
-										[NAMZU.RUN_ID]: runMgr.id,
+									this.ctx.log.warn('Answer rejected more times than the turn allows', {
+										[NAMZU.TURN_ID]: recorder.turnId,
 										'namzu.runtime.attempts': attempt - 1,
 										'namzu.runtime.limit': limit,
 									})
-									runMgr.setStopReason('answer_rejected')
+									recorder.setStopReason('answer_rejected')
 									break
 								}
 								this.ctx.log.info('Answer rejected — returning it to the model', {
-									[NAMZU.RUN_ID]: runMgr.id,
+									[NAMZU.TURN_ID]: recorder.turnId,
 									'namzu.retry.attempt': attempt,
 									'namzu.runtime.limit': limit,
 								})
 								await this.ctx.emitEvent({
 									type: 'iteration_completed',
-									runId: runMgr.id,
+									turnId: recorder.turnId,
 									iteration: iterationNum,
 									hasToolCalls: false,
 								})
@@ -1274,11 +1312,11 @@ export class IterationOrchestrator {
 						}
 
 						// A background worker is still out there, and this turn was
-						// about to end the run.
+						// about to end the turn.
 						//
 						// Settling here would throw away the very thing the launch
 						// existed to produce: the supervisor said "launched", the
-						// worker had not finished, and the run closed over it.
+						// worker had not finished, and the turn closed over it.
 						if (
 							!forceFinalize &&
 							(yield* holdForOutstandingWork(this.ctx, iterationNum, false, () =>
@@ -1300,7 +1338,7 @@ export class IterationOrchestrator {
 						if (!forceFinalize && this.deliverInbound() > 0) {
 							await this.ctx.emitEvent({
 								type: 'iteration_completed',
-								runId: runMgr.id,
+								turnId: recorder.turnId,
 								iteration: iterationNum,
 								hasToolCalls: false,
 							})
@@ -1325,18 +1363,18 @@ export class IterationOrchestrator {
 
 						await this.ctx.emitEvent({
 							type: 'iteration_completed',
-							runId: runMgr.id,
+							turnId: recorder.turnId,
 							iteration: iterationNum,
 							hasToolCalls: false,
 						})
 						yield* this.ctx.drainPending()
 						// A Stop that lands AFTER the final turn streamed but before
-						// this break must settle the run as cancelled, not end_turn —
+						// this break must settle the turn as cancelled, not end_turn —
 						// otherwise the just-produced answer is recorded as a clean
 						// completion. Mirrors the between-iteration cancel at :511.
 						if (this.ctx.abortController.signal.aborted) {
-							runMgr.setStopReason('cancelled')
-							runMgr.markCancelled()
+							recorder.setStopReason('cancelled')
+							recorder.markCancelled()
 							break
 						}
 						// The host's stop predicate, if the previous turn deferred it
@@ -1344,13 +1382,13 @@ export class IterationOrchestrator {
 						// is prose, and `stopWhen` is consulted only after a tool
 						// batch, so the predicate is never asked again — reporting
 						// `end_turn` would name the shape of the last message rather
-						// than the reason the run is over.
+						// than the reason the turn is over.
 						//
 						// Only here. A terminal tool and a captured structured output
 						// also settle as `end_turn`, and there the deferred predicate
-						// is not why the run ended: those decided the answer
+						// is not why the turn ended: those decided the answer
 						// themselves.
-						runMgr.setStopReason(
+						recorder.setStopReason(
 							closingStopReason ??
 								(stopWasDeferredForOutstandingWork ? 'stop_condition' : 'end_turn'),
 						)
@@ -1359,7 +1397,7 @@ export class IterationOrchestrator {
 
 					const reviewOutcome = yield* runToolReview(this.ctx, response, iterationNum)
 
-					// The step record is built even for a rejected batch: a run that
+					// The step record is built even for a rejected batch: a turn that
 					// spent a turn getting its tools refused still spent the tokens,
 					// and a caller reconstructing cost per step must see it.
 					this.recordStep({
@@ -1404,34 +1442,34 @@ export class IterationOrchestrator {
 					) {
 						await this.ctx.emitEvent({
 							type: 'iteration_completed',
-							runId: runMgr.id,
+							turnId: recorder.turnId,
 							iteration: iterationNum,
 							hasToolCalls: true,
 						})
 						yield* this.ctx.drainPending()
 						if (this.ctx.abortController.signal.aborted) {
-							runMgr.setStopReason('cancelled')
-							runMgr.markCancelled()
+							recorder.setStopReason('cancelled')
+							recorder.markCancelled()
 							break
 						}
 						if (structuredOutcome === 'retry') continue
-						runMgr.setStopReason(
+						recorder.setStopReason(
 							structuredOutcome === 'cancelled' ? 'cancelled' : 'answer_rejected',
 						)
-						if (structuredOutcome === 'cancelled') runMgr.markCancelled()
+						if (structuredOutcome === 'cancelled') recorder.markCancelled()
 						break
 					}
 					if (structuredOutcome === 'accepted') {
 						await this.ctx.emitEvent({
 							type: 'iteration_completed',
-							runId: runMgr.id,
+							turnId: recorder.turnId,
 							iteration: iterationNum,
 							hasToolCalls: true,
 						})
 						yield* this.ctx.drainPending()
 						if (this.ctx.abortController.signal.aborted) {
-							runMgr.setStopReason('cancelled')
-							runMgr.markCancelled()
+							recorder.setStopReason('cancelled')
+							recorder.markCancelled()
 							break
 						}
 						if (!forceFinalize) {
@@ -1441,20 +1479,20 @@ export class IterationOrchestrator {
 							if (inbound > 0 || this.latestUserMessage !== operatorInputAtDispatch) continue
 						}
 						if (this.ctx.abortController.signal.aborted) {
-							runMgr.setStopReason('cancelled')
-							runMgr.markCancelled()
+							recorder.setStopReason('cancelled')
+							recorder.markCancelled()
 							break
 						}
-						this.ctx.log.info('Structured output produced — ending run', {
-							[NAMZU.RUN_ID]: runMgr.id,
+						this.ctx.log.info('Structured output produced — ending turn', {
+							[NAMZU.TURN_ID]: recorder.turnId,
 							[NAMZU.ITERATION]: iterationNum,
 						})
 						this.publishStructuredOutput()
-						runMgr.setStopReason('end_turn')
+						recorder.setStopReason('end_turn')
 						break
 					}
 
-					// A tool the author declared terminal settles the run with its
+					// A tool the author declared terminal settles the turn with its
 					// own output, the same rule `structured_output` has always
 					// had. Without it a delegation cost the parent one more model
 					// call at full context whose only job was to restate what the
@@ -1463,16 +1501,16 @@ export class IterationOrchestrator {
 					// worker's words.
 					const settled = this.terminalToolOutput(reviewOutcome.results, response)
 					if (settled !== undefined) {
-						this.ctx.log.info('Terminal tool produced the answer — ending run', {
-							[NAMZU.RUN_ID]: runMgr.id,
+						this.ctx.log.info('Terminal tool produced the answer — ending turn', {
+							[NAMZU.TURN_ID]: recorder.turnId,
 							[NAMZU.ITERATION]: iterationNum,
 							[GENAI.TOOL_NAME]: settled.toolName,
 						})
-						runMgr.setResult(settled.output)
-						runMgr.setStopReason('end_turn')
+						recorder.setResult(settled.output, 'review')
+						recorder.setStopReason('end_turn')
 						await this.ctx.emitEvent({
 							type: 'iteration_completed',
-							runId: runMgr.id,
+							turnId: recorder.turnId,
 							iteration: iterationNum,
 							hasToolCalls: true,
 						})
@@ -1507,7 +1545,7 @@ export class IterationOrchestrator {
 						// outstanding. One task deferred it once; two awaited
 						// jobs exiting a minute apart defer it twice, each time
 						// for a turn the model spends on news it has not read.
-						// `maxIterations` and the run's own deadline bound all of
+						// `maxIterations` and the turn's own deadline bound all of
 						// it regardless, and a leg with nothing pending never
 						// opens a hold at all.
 						if (
@@ -1516,20 +1554,20 @@ export class IterationOrchestrator {
 							)
 						) {
 							// Remember WHY the next turn exists, so the turn that
-							// ends the run can name the host's decision instead of
+							// ends the turn can name the host's decision instead of
 							// reporting the shape of the last message.
 							this.stopDeferredForOutstandingWork = true
 							continue
 						}
 
 						this.ctx.log.info('Stop condition met', {
-							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.TURN_ID]: recorder.turnId,
 							[NAMZU.ITERATION]: iterationNum,
 						})
-						runMgr.setStopReason('stop_condition')
+						recorder.setStopReason('stop_condition')
 						await this.ctx.emitEvent({
 							type: 'iteration_completed',
-							runId: runMgr.id,
+							turnId: recorder.turnId,
 							iteration: iterationNum,
 							hasToolCalls: true,
 						})
@@ -1564,11 +1602,11 @@ export class IterationOrchestrator {
 					const unheard = this.ctx.completionInbox?.drain() ?? []
 					if (unheard.length > 0) {
 						this.ctx.log.info('Delivering unawaited task completions', {
-							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.TURN_ID]: recorder.turnId,
 							[NAMZU.ITERATION]: iterationNum,
 							'namzu.runtime.tasks': unheard.map((h) => h.taskId),
 						})
-						runMgr.pushMessage(
+						recorder.pushMessage(
 							createRuntimeContextMessage(formatCompletionNotification(unheard), 'task-completion'),
 						)
 					}
@@ -1585,7 +1623,8 @@ export class IterationOrchestrator {
 						const hookResults = await this.ctx.pluginManager.executeHooks(
 							'iteration_end',
 							{
-								runId: runMgr.id,
+								sessionId: recorder.sessionId,
+								turnId: recorder.turnId,
 								iteration: iterationNum,
 								signal: this.ctx.abortController.signal,
 							},
@@ -1597,7 +1636,7 @@ export class IterationOrchestrator {
 
 					await this.ctx.emitEvent({
 						type: 'iteration_completed',
-						runId: runMgr.id,
+						turnId: recorder.turnId,
 						iteration: iterationNum,
 						hasToolCalls: true,
 					})
@@ -1623,7 +1662,7 @@ export class IterationOrchestrator {
 					// wrote down for itself. All three exits spend a turn: the
 					// cancellation breaks, the overflow-relief retry continues
 					// under a NEW iteration number (so its tokens belong to no
-					// later step), and the re-throw ends the run.
+					// later step), and the re-throw ends the turn.
 					//
 					// What it carries is what the iteration got as far as knowing.
 					// `usage` is the same subtraction a successful step makes, so
@@ -1640,10 +1679,10 @@ export class IterationOrchestrator {
 					// class of wrong as dropping them and harder to notice, since
 					// the ledger would look fuller rather than emptier. That turn's
 					// own verdict is already written down; the failure that
-					// followed it reaches the caller as the run's error.
+					// followed it reaches the caller as the turn's error.
 					if (this.steps.at(-1)?.stepNumber === iterationNum) {
 						this.ctx.log.warn('Iteration failed after its step was already recorded', {
-							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.TURN_ID]: recorder.turnId,
 							[NAMZU.ITERATION]: iterationNum,
 							'exception.message': toErrorMessage(err),
 						})
@@ -1674,15 +1713,15 @@ export class IterationOrchestrator {
 					}
 
 					// A Stop that aborted the in-flight turn surfaces here as a
-					// thrown abort (the provider stream was raced against the run
+					// thrown abort (the provider stream was raced against the turn
 					// signal). Settle it as a CANCELLATION — mirroring the
 					// between-iteration cancel at the top of the loop — rather than
 					// recording it as an SDK failure (error span + failed activity)
-					// and re-throwing. The run then returns cleanly with a
+					// and re-throwing. The turn then returns cleanly with a
 					// 'cancelled' stop reason instead of propagating an error.
 					if (cancelled) {
-						runMgr.setStopReason('cancelled')
-						runMgr.markCancelled()
+						recorder.setStopReason('cancelled')
+						recorder.markCancelled()
 						break
 					}
 
@@ -1690,8 +1729,8 @@ export class IterationOrchestrator {
 					// about. `context_length_exceeded` is correctly non-retryable —
 					// resending the identical prompt cannot help — but the kernel
 					// owns a compaction subsystem that can make the prompt smaller.
-					// Without this the run died holding the remedy: the threshold
-					// path had simply guessed low, which a run carrying images or a
+					// Without this the turn died holding the remedy: the threshold
+					// path had simply guessed low, which a turn carrying images or a
 					// language the chars-per-token ratio does not fit will do.
 					//
 					// Relief is attempted ONCE per iteration and only when it
@@ -1707,7 +1746,7 @@ export class IterationOrchestrator {
 						const shed = await relieveOverflow(this.ctx)
 						if (shed) {
 							this.ctx.log.info('Retrying the turn after relieving a context overflow', {
-								[NAMZU.RUN_ID]: runMgr.id,
+								[NAMZU.TURN_ID]: recorder.turnId,
 								[NAMZU.ITERATION]: iterationNum,
 							})
 							if (iterationActivity) {
@@ -1756,7 +1795,7 @@ export class IterationOrchestrator {
 		}
 	}
 
-	/** Steps completed so far, exposed on the returned `Run`. */
+	/** Steps completed so far, exposed on the returned `Turn`. */
 	private readonly steps: StepResult[] = []
 
 	getSteps(): readonly StepResult[] {
@@ -1768,17 +1807,17 @@ export class IterationOrchestrator {
 	 *
 	 * Every field here was already computed somewhere in the loop; the only
 	 * new work is subtracting the cumulative counters so the step carries
-	 * ITS usage rather than the run's running total, which is the number a
+	 * ITS usage rather than the turn's running total, which is the number a
 	 * caller asking "what did this step cost" actually wants.
 	 */
 	/**
-	 * Take everything queued for this run since the last turn.
+	 * Take everything queued for this turn since the last turn.
 	 *
 	 * Both channels drain here. `inboundMessages` is the manager's queue —
 	 * what `continueTask` and `queueMessage` push onto and nothing ever
 	 * collected. `steering` is the host's, and it could only ride on a tool
 	 * result, so guidance queued during a turn that called no tools stayed
-	 * pending until the run ended.
+	 * pending until the turn ended.
 	 *
 	 * Returns the count so a caller can decide whether a turn is owed. An
 	 * empty drain must change nothing at all: a `continue` on nothing queued
@@ -1799,7 +1838,7 @@ export class IterationOrchestrator {
 	private deliverInbound(): number {
 		const queued = this.ctx.inboundMessages?.() ?? []
 		for (const message of queued) {
-			this.ctx.runMgr.pushMessage(message)
+			this.ctx.recorder.pushMessage(message)
 			this.rememberUserMessage(message)
 		}
 
@@ -1809,7 +1848,7 @@ export class IterationOrchestrator {
 		const stranded = this.ctx.steering?.drain()
 		if (stranded) {
 			const message = createRuntimeContextMessage(formatSteeringNote(stranded), 'steering')
-			this.ctx.runMgr.pushMessage(message)
+			this.ctx.recorder.pushMessage(message)
 			this.rememberUserMessage(createRuntimeContextMessage(stranded, 'steering'))
 		}
 
@@ -1841,7 +1880,7 @@ export class IterationOrchestrator {
 		 */
 		unfinished?: { finishReason: 'error' | 'cancelled'; failure?: StepFailure }
 	}): void {
-		const { runMgr } = this.ctx
+		const { recorder } = this.ctx
 		const toolCalls = input.response?.message.toolCalls ?? []
 		const byId = new Map(input.toolResults.map((r) => [r.toolCallId, r]))
 
@@ -1882,10 +1921,10 @@ export class IterationOrchestrator {
 			// tool execution did not end in `tool_calls`.
 			finishReason: input.unfinished?.finishReason ?? input.response?.finishReason ?? 'error',
 			...(input.unfinished?.failure ? { failure: input.unfinished.failure } : {}),
-			usage: subtractUsage(runMgr.tokenUsage, input.usageBefore),
+			usage: subtractUsage(recorder.tokenUsage, input.usageBefore),
 			costDelta: {
-				...runMgr.costInfo,
-				totalCost: round6(runMgr.costInfo.totalCost - input.costBefore.totalCost),
+				...recorder.costInfo,
+				totalCost: round6(recorder.costInfo.totalCost - input.costBefore.totalCost),
 			},
 			startedAt: input.startedAt,
 			durationMs: Date.now() - input.startedAt,
@@ -1902,13 +1941,13 @@ export class IterationOrchestrator {
 		// Nothing here is allowed to throw over the failure that is already
 		// unwinding — the same rule `settleCancelledTurn` states for the
 		// cancellation path. A host callback that throws while being told a
-		// turn failed would REPLACE the reason the turn failed, so the run
+		// turn failed would REPLACE the reason the turn failed, so the turn
 		// would report the observer's bug and lose the original.
 		try {
 			this.ctx.onStepFinish?.(step)
 		} catch (err) {
 			this.ctx.log.warn('onStepFinish threw while recording a failed step', {
-				[NAMZU.RUN_ID]: runMgr.id,
+				[NAMZU.TURN_ID]: recorder.turnId,
 				'namzu.runtime.step': input.stepNumber,
 				'exception.message': toErrorMessage(err),
 			})
@@ -1934,7 +1973,7 @@ export class IterationOrchestrator {
 	/**
 	 * The answer a terminal tool produced, or `undefined` to keep looping.
 	 *
-	 * Deliberately narrow. A terminal call decides the run only when it is
+	 * Deliberately narrow. A terminal call decides the turn only when it is
 	 * the ONLY call the model made in that turn: a model that asked for
 	 * other work meant to see those results, and settling here would throw
 	 * away answers it requested. Same for a failed terminal call — an
@@ -1954,7 +1993,7 @@ export class IterationOrchestrator {
 		const callCount = response.message.toolCalls?.length ?? 0
 		if (callCount > 1) {
 			this.ctx.log.info('Terminal tool shared its turn — relaying instead of settling', {
-				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+				[NAMZU.TURN_ID]: this.ctx.recorder.turnId,
 				[GENAI.TOOL_NAME]: terminal[0]?.toolName,
 				'namzu.runtime.calls_in_turn': callCount,
 			})
@@ -1964,7 +2003,7 @@ export class IterationOrchestrator {
 		const hit = terminal[0]
 		if (!hit || hit.isError) {
 			this.ctx.log.info('Terminal tool failed — returning the error to the model', {
-				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+				[NAMZU.TURN_ID]: this.ctx.recorder.turnId,
 				[GENAI.TOOL_NAME]: hit?.toolName,
 			})
 			return undefined
@@ -1987,7 +2026,7 @@ export class IterationOrchestrator {
 	 * by the time this runs — `runToolReview` settles it, side effects
 	 * included, before either of these is consulted — so settling here is
 	 * worse than discarding an answer the model wanted: the work happened,
-	 * its results went into the transcript, and the run ended before any
+	 * its results went into the transcript, and the turn ended before any
 	 * model turn could read them. Nothing consumed what was spent, and
 	 * nothing said so.
 	 *
@@ -2009,7 +2048,7 @@ export class IterationOrchestrator {
 	 * avoids it by not pairing.
 	 *
 	 * NOT charged to `maxRetries`. That budget bounds a model that cannot
-	 * satisfy the SCHEMA, and this one did. A run reading two files a turn
+	 * satisfy the SCHEMA, and this one did. A turn reading two files a turn
 	 * while optimistically attaching its answer is making progress, and it
 	 * must not die reported as `structured_output_failed` — a failure that
 	 * did not happen. `maxIterations` is the bound for a model that keeps
@@ -2030,7 +2069,7 @@ export class IterationOrchestrator {
 		const callCount = response.message.toolCalls?.length ?? 0
 		if (callCount > 1) {
 			this.ctx.log.info('Structured output shared its turn — relaying instead of settling', {
-				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+				[NAMZU.TURN_ID]: this.ctx.recorder.turnId,
 				'namzu.runtime.calls_in_turn': callCount,
 			})
 			return 'absent'
@@ -2052,7 +2091,7 @@ export class IterationOrchestrator {
 	}
 
 	private publishStructuredOutput(): void {
-		this.ctx.runMgr.setStructuredOutput(this.pendingStructuredOutput)
+		this.ctx.recorder.setStructuredOutput(this.pendingStructuredOutput)
 		this.structuredOutputDone = true
 	}
 
@@ -2078,10 +2117,11 @@ export class IterationOrchestrator {
 					Promise.resolve().then(() => {
 						signal.throwIfAborted()
 						return reviewer(structuredClone(parsed), {
-							runId: this.ctx.runMgr.id,
-							iteration: this.ctx.runMgr.currentIteration,
+							sessionId: this.ctx.recorder.sessionId,
+							turnId: this.ctx.recorder.turnId,
+							iteration: this.ctx.recorder.currentIteration,
 							signal,
-							messages: this.ctx.runMgr.messages,
+							messages: this.ctx.recorder.messages,
 							...reviewRequest,
 							generateText: inference.generateText,
 						})
@@ -2102,18 +2142,20 @@ export class IterationOrchestrator {
 				if (typeof verdict.feedback !== 'string' || verdict.feedback.trim().length === 0)
 					throw new Error('Structured reviewer rejection requires feedback')
 				this.structuredReviewAttempts++
-				this.ctx.runMgr.pushMessage(createRuntimeContextMessage(verdict.feedback, 'answer-review'))
+				this.ctx.recorder.pushMessage(
+					createRuntimeContextMessage(verdict.feedback, 'answer-review'),
+				)
 				// Persist both the feedback and its consumed allowance before the
 				// next request. This checkpoint is not an approval/park boundary.
 				const checkpoint = await this.ctx.checkpointMgr.create(
-					this.ctx.runMgr,
-					this.ctx.runMgr.currentIteration,
+					this.ctx.recorder,
+					this.ctx.recorder.currentIteration,
 				)
 				await this.ctx.emitEvent({
 					type: 'checkpoint_created',
-					runId: this.ctx.runMgr.id,
+					turnId: this.ctx.recorder.turnId,
 					checkpointId: checkpoint.id,
-					iteration: this.ctx.runMgr.currentIteration,
+					iteration: this.ctx.recorder.currentIteration,
 				})
 				if (signal.aborted) return 'cancelled'
 				return this.structuredReviewAttempts >
@@ -2146,10 +2188,11 @@ export class IterationOrchestrator {
 				Promise.resolve().then(() => {
 					signal.throwIfAborted()
 					return reviewer(answer, {
-						runId: this.ctx.runMgr.id,
-						iteration: this.ctx.runMgr.currentIteration,
+						sessionId: this.ctx.recorder.sessionId,
+						turnId: this.ctx.recorder.turnId,
+						iteration: this.ctx.recorder.currentIteration,
 						signal,
-						messages: this.ctx.runMgr.messages,
+						messages: this.ctx.recorder.messages,
 						...reviewRequest,
 						generateText: inference.generateText,
 					})
@@ -2180,14 +2223,14 @@ export class IterationOrchestrator {
 			return await stopWhen({
 				steps: this.steps,
 				latestStep,
-				totalUsage: this.ctx.runMgr.tokenUsage,
-				totalCost: this.ctx.runMgr.costInfo,
+				totalUsage: this.ctx.recorder.tokenUsage,
+				totalCost: this.ctx.recorder.costInfo,
 			})
 		} catch (err) {
-			// A throwing predicate must not kill a run that is otherwise
+			// A throwing predicate must not kill a turn that is otherwise
 			// healthy; failing open keeps the existing budgets in charge.
-			this.ctx.log.error('Stop condition threw — continuing the run', {
-				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+			this.ctx.log.error('Stop condition threw — continuing the turn', {
+				[NAMZU.TURN_ID]: this.ctx.recorder.turnId,
 				'exception.message': toErrorMessage(err),
 			})
 			return false
@@ -2202,14 +2245,14 @@ export class IterationOrchestrator {
 	}
 
 	private async acceptProviderRejectedImage(identity: RequestImageIdentity): Promise<void> {
-		const repaired = markProviderRejectedImage(this.ctx.runMgr.messages, identity)
+		const repaired = markProviderRejectedImage(this.ctx.recorder.messages, identity)
 		if (repaired.count === 0) {
 			throw new Error('Provider-rejected image recovery could not find its durable source image')
 		}
-		this.ctx.runMgr.replaceMessages(repaired.messages)
+		this.ctx.recorder.replaceMessages(repaired.messages)
 		await this.ctx.emitEvent?.({
 			type: 'message_history_repaired',
-			runId: this.ctx.runMgr.id,
+			turnId: this.ctx.recorder.turnId,
 			source: 'provider-rejected-image',
 			duplicateToolResultsRemoved: 0,
 			orphanedToolResultsRemoved: 0,
@@ -2224,7 +2267,7 @@ export class IterationOrchestrator {
 	): Promise<StopReason | undefined> {
 		if (this.ctx.structuredOutput?.mode === 'native') return 'structured_output_failed'
 
-		const lastAssistant = [...this.ctx.runMgr.messages]
+		const lastAssistant = [...this.ctx.recorder.messages]
 			.reverse()
 			.find((m) => m.role === 'assistant')
 
@@ -2234,11 +2277,11 @@ export class IterationOrchestrator {
 			lastAssistant.content.length > 0
 
 		if (hasResult) return
-		// An empty completion may itself have exhausted the run. This fallback
+		// An empty completion may itself have exhausted the turn. This fallback
 		// is another billed request, so it must pass the same hard limits as
 		// the next normal iteration and preserve their unfinished stop reason.
 		const guardResult = this.ctx.guard.beforeIteration(
-			this.ctx.runMgr,
+			this.ctx.recorder,
 			this.ctx.abortController.signal,
 		)
 		if (guardResult.shouldStop) return guardResult.stopReason
@@ -2248,18 +2291,26 @@ export class IterationOrchestrator {
 		})
 
 		try {
+			// The working-memory slot leaves the system run exactly as it does
+			// for a normal step, and for the same cache reason.
+			const workingMemory = splitWorkingMemoryForRequest(this.ctx.recorder.messages)
 			const finalHistory = [
-				...this.ctx.runMgr.messages,
-				createRuntimeContextMessage(
-					`[SYSTEM] Run is ending due to ${reason}. ${CLOSING_RESPONSE_GUIDANCE}`,
-					'limit-finalization',
-				),
+				...workingMemory.history,
+				...(workingMemory.context ? [workingMemory.context] : []),
 			]
 			const finalMessages = projectRequestRichContent(
 				this.projectObservations(finalHistory),
-				this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
+				this.ctx.turnConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 			)
 			appendWorkContext(this.stepShaping(), finalMessages, this.steps.length + 1, { model })
+			// The closing directive is the last thing the model reads: after
+			// the working memory and any work context above.
+			finalMessages.push(
+				createRuntimeContextMessage(
+					`[SYSTEM] Turn is ending due to ${reason}. ${CLOSING_RESPONSE_GUIDANCE}`,
+					'limit-finalization',
+				),
+			)
 			await this.reportUnsupportedToolResults(finalMessages)
 
 			// Same cache discipline as the forced-final iteration: keep the
@@ -2283,14 +2334,14 @@ export class IterationOrchestrator {
 				tools: finalTools.length > 0 ? finalTools : undefined,
 				...(finalEnforced ? { enforceToolInputSchema: finalEnforced } : {}),
 				toolChoice: finalTools.length > 0 ? 'none' : undefined,
-				temperature: this.ctx.runConfig.temperature,
-				maxTokens: this.ctx.runConfig.maxResponseTokens,
+				temperature: this.ctx.turnConfig.temperature,
+				maxTokens: this.ctx.turnConfig.maxResponseTokens,
 				cacheControl: { type: 'auto' },
-				...(this.ctx.runConfig.thinking ? { thinking: this.ctx.runConfig.thinking } : {}),
+				...(this.ctx.turnConfig.thinking ? { thinking: this.ctx.turnConfig.thinking } : {}),
 				// This turn is a hand-maintained duplicate of the one above, which
 				// is exactly the shape a field goes missing from — so it is tested
 				// separately rather than assumed to have been kept in step.
-				...(this.ctx.runConfig.effort ? { effort: this.ctx.runConfig.effort } : {}),
+				...(this.ctx.turnConfig.effort ? { effort: this.ctx.turnConfig.effort } : {}),
 				// Cancellable too: a Stop during the closing summary must not
 				// stream to completion.
 				signal: this.ctx.abortController.signal,
@@ -2307,7 +2358,7 @@ export class IterationOrchestrator {
 				model: servingMember.model ?? model,
 				chainIndex: servingMember.index,
 			}
-			this.ctx.runMgr.accumulateUsage(response.usage, {
+			this.ctx.recorder.accumulateUsage(response.usage, {
 				providerId: servedBy.providerId,
 				model: servedBy.model,
 			})
@@ -2326,19 +2377,19 @@ export class IterationOrchestrator {
 				},
 				response.message.textParts,
 			)
-			this.ctx.runMgr.pushMessage(assistantMsg)
+			this.ctx.recorder.pushMessage(assistantMsg)
 
 			const finalMessageId = generateMessageId()
 			await this.ctx.emitEvent({
 				type: 'message_started',
-				runId: this.ctx.runMgr.id,
-				iteration: this.ctx.runMgr.currentIteration,
+				turnId: this.ctx.recorder.turnId,
+				iteration: this.ctx.recorder.currentIteration,
 				messageId: finalMessageId,
 			})
 			await this.ctx.emitEvent({
 				type: 'message_completed',
-				runId: this.ctx.runMgr.id,
-				iteration: this.ctx.runMgr.currentIteration,
+				turnId: this.ctx.recorder.turnId,
+				iteration: this.ctx.recorder.currentIteration,
 				messageId: finalMessageId,
 				stopReason: 'forced_finalize',
 				usage: response.usage,