@namzu/sdk 38.2.1 → 40.0.0

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

@@ -14,6 +14,7 @@ import { renderSkillsSection } from '../../../persona/assembler.js'
 import { resolveProviderCapabilities } from '../../../provider/capabilities.js'
 import { collectChatCompletion } from '../../../provider/collect-chat-completion.js'
 import { renderToolSchema } from '../../../registry/tool/schema.js'
+import { PreparationContextError } from '../../../run/preparation-context-error.js'
 import { formatCompletionNotification } from '../../../scheduler/completion-inbox.js'
 import {
 	GENAI,
@@ -37,7 +38,7 @@ import {
 import type { ToolChoice } from '../../../types/provider/chat.js'
 import { classifyProviderError } from '../../../types/provider/errors.js'
 import type { ChatCompletionResponse } from '../../../types/provider/index.js'
-import type { AnswerReview } from '../../../types/run/answer-review.js'
+import type { AnswerReview, AnswerReviewContext } from '../../../types/run/answer-review.js'
 import type {
 	PrepareStepContext,
 	PrepareStepResult,
@@ -50,9 +51,11 @@ import type {
 } from '../../../types/run/index.js'
 import type { Skill } from '../../../types/skills/index.js'
 import type { LLMToolSchema, ToolRegistryContract } from '../../../types/tool/index.js'
+import { readPositiveIntEnv } from '../../../utils/env.js'
 import { toErrorMessage } from '../../../utils/error.js'
 import { stableDigest } from '../../../utils/hash.js'
 import { generateMessageId } from '../../../utils/id.js'
+import { createCallbackInference } from '../callback-inference.js'
 import type { ToolCallOutcome } from '../executor.js'
 import { projectObservationContext } from '../observation-context.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
@@ -67,7 +70,7 @@ import {
 	markProviderRejectedImage,
 	projectRequestRichContent,
 } from '../request-rich-content.js'
-import { formatSteeringNote, isOperatorUserMessage } from '../steering.js'
+import { formatJobNote, formatSteeringNote, isOperatorUserMessage } from '../steering.js'
 import { parseNativeCandidate } from './native-output.js'
 import { runAdvisoryPhase } from './phases/advisory.js'
 import { runIterationCheckpoint } from './phases/checkpoint.js'
@@ -84,6 +87,20 @@ import { refreshWorkingMemory } from './phases/working-memory.js'
 import { streamWithProviderRejectedImageRecovery } from './provider-rejected-image.js'
 import { streamProviderTurn } from './stream-turn.js'
 
+type ReviewRequest = Pick<AnswerReviewContext, 'requestMessages' | 'latestUserMessage'>
+
+/** A host reviewer is not the model transport, even when its cause is an HTTP failure. */
+class AnswerReviewFailure extends NamzuError {
+	constructor(cause: unknown) {
+		super({
+			code: 'unknown',
+			message: `Answer review failed: ${toErrorMessage(cause)}`,
+			retryable: false,
+			details: { phase: 'answer-review' },
+			cause,
+		})
+	}
+}
 export type { IterationContext } from './phases/index.js'
 export type { PhaseSignal } from './phases/index.js'
 export type { ToolReviewOutcome } from './phases/index.js'
@@ -98,6 +115,11 @@ export type { ToolReviewOutcome } from './phases/index.js'
  */
 const DEFAULT_ANSWER_REVIEW_LIMIT = 3
 
+// Ending a run 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.'
+
 /**
  * The share of a run's REMAINING time a settle-hold may take.
  *
@@ -160,8 +182,68 @@ export function settleGraceMs(remainingBeforeFinalizeMs: number): number {
 	)
 }
 
+/**
+ * The ceiling on the job half of that grace, in milliseconds.
+ *
+ * `DELEGATION_TIMEOUT_MS` is the wrong ceiling for a shell job, and the gap
+ * only opens where it matters most: a run with no `timeoutMs` — the CLI's
+ * shipping default, `No run deadline by default` — has infinite time before
+ * it must start finishing, so `settleGraceMs` returns the ceiling flat. For a
+ * delegated task that is sound, because the hour is the longest the task
+ * itself may live: the hold cannot outlast the work. A background job has no
+ * such bound. `tail -f`, a watcher and a dev server all outlive any hold, so
+ * the same arithmetic parks an interactive session for an hour on a job that
+ * was never going to exit.
+ *
+ * So the job leg gets its own bound, and it is sized to what the wait buys
+ * rather than to how long a job may live: a turn in which to use the exit.
+ * A model that already waited its `wait_for_job` bound out and saw nothing is
+ * not usually two minutes from an exit, and the run ending is not the news
+ * being lost — with no run in flight the session announces the exit itself
+ * (`docs/cli/background-jobs.md`, *Learning that it ended*), which is the
+ * cheaper of the two places to hear it.
+ */
+const DEFAULT_JOB_HOLD_MAX_MS = 2 * 60 * 1000
+
+/**
+ * The same share of the run, under {@link DEFAULT_JOB_HOLD_MAX_MS}.
+ *
+ * `NAMZU_JOB_HOLD_MAX_MS` overrides the ceiling for a host that wants a
+ * longer or shorter park, the way `NAMZU_JOB_WAIT_TIMEOUT_MS` overrides
+ * `wait_for_job`'s own bound — and it is the same parse, so a value that is
+ * not a positive whole number of milliseconds leaves the default standing
+ * rather than holding a run for `NaN`. Called here rather than at module
+ * load, because a host that sets it after import is not ignored.
+ */
+export function awaitedJobGraceMs(remainingBeforeFinalizeMs: number): number {
+	const ceiling = readPositiveIntEnv('NAMZU_JOB_HOLD_MAX_MS', DEFAULT_JOB_HOLD_MAX_MS)
+	return Math.min(settleGraceMs(remainingBeforeFinalizeMs), ceiling)
+}
+
 export class IterationOrchestrator {
 	private ctx: IterationContext
+	private advisoryTurn:
+		| {
+				readonly iteration: number
+				readonly requestMessages: readonly Message[]
+				readonly response: Message
+		  }
+		| undefined
+
+	/** Live only within its iteration; never joined by a guessed array offset. */
+	getAdvisoryTurnContext():
+		| 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 (start < 0) return undefined
+		return {
+			iteration: turn.iteration,
+			requestMessages: turn.requestMessages,
+			subsequentMessages: this.ctx.runMgr.messages.slice(start),
+		}
+	}
 	/** Rejections so far. See {@link DEFAULT_ANSWER_REVIEW_LIMIT}. */
 	private answerReviewAttempts = 0
 	/**
@@ -206,6 +288,7 @@ export class IterationOrchestrator {
 			},
 		}
 		ctx.checkpointMgr.setLatestUserMessageSource(() => this.latestUserMessage)
+		ctx.checkpointMgr.setAnswerReviewAttemptsSource?.(() => this.answerReviewAttempts)
 		ctx.checkpointMgr.setStructuredReviewAttemptsSource?.(() => this.structuredReviewAttempts)
 		ctx.checkpointMgr.setNativeStructuredAttemptsSource?.(() => this.nativeStructuredAttempts)
 		if (ctx.structuredOutput?.mode === 'native') {
@@ -223,6 +306,11 @@ export class IterationOrchestrator {
 		const maxReviews = ctx.structuredOutput?.maxReviews
 		if (maxReviews !== undefined && (!Number.isSafeInteger(maxReviews) || maxReviews < 0))
 			throw new RangeError('structuredOutput.maxReviews must be a nonnegative safe integer')
+		if (
+			ctx.maxAnswerReviews !== undefined &&
+			(!Number.isSafeInteger(ctx.maxAnswerReviews) || ctx.maxAnswerReviews < 0)
+		)
+			throw new RangeError('maxAnswerReviews must be a nonnegative safe integer')
 	}
 
 	/**
@@ -306,6 +394,7 @@ export class IterationOrchestrator {
 		const tracer = getTracer()
 		// Resume hydration happens after construction, before the loop starts.
 		this.latestUserMessage = this.ctx.checkpointMgr.restoredLatestUserMessage
+		this.answerReviewAttempts = this.ctx.checkpointMgr.restoredAnswerReviewAttempts ?? 0
 		this.structuredReviewAttempts = this.ctx.checkpointMgr.restoredStructuredReviewAttempts ?? 0
 		this.nativeStructuredAttempts = this.ctx.checkpointMgr.restoredNativeStructuredAttempts ?? 0
 		if (!this.latestUserMessage) {
@@ -353,6 +442,13 @@ export class IterationOrchestrator {
 					runMgr.setStopReason('structured_output_failed')
 					break
 				}
+				if (
+					this.ctx.reviewAnswer &&
+					this.answerReviewAttempts > (this.ctx.maxAnswerReviews ?? DEFAULT_ANSWER_REVIEW_LIMIT)
+				) {
+					runMgr.setStopReason('answer_rejected')
+					break
+				}
 				if (
 					this.ctx.structuredOutput?.review &&
 					this.structuredReviewAttempts >
@@ -533,14 +629,15 @@ export class IterationOrchestrator {
 					// Snapshot the cumulative counters so the step can report ITS
 					// own usage rather than the run total.
 					stepStartedAt = Date.now()
-					usageBefore = { ...runMgr.tokenUsage }
-					costBefore = { ...runMgr.costInfo }
 
 					// Shape this step before calling the model. `stopWhen` decides
 					// whether to keep going; this decides HOW. No-op when the host
 					// supplied no hook.
 					const contextModelBeforePreparation = this.ctx.contextModel ?? model
 					const step = await this.prepareStep(iterationNum)
+					// Preparation inference belongs to the run, not the main-model step.
+					usageBefore = { ...runMgr.tokenUsage }
+					costBefore = { ...runMgr.costInfo }
 					stepModel = step.model ?? model
 					await this.selectContextModel(stepModel)
 					// Preserve post-compaction preparation/recall semantics. A changed
@@ -570,7 +667,7 @@ export class IterationOrchestrator {
 						? [
 								...runMgr.messages,
 								createRuntimeContextMessage(
-									'[SYSTEM] You are approaching your resource limits. Provide your final, comprehensive response now based on everything you have gathered so far. Do not request any more tool calls.',
+									`[SYSTEM] You are approaching your resource limits. ${CLOSING_RESPONSE_GUIDANCE}`,
 									'limit-finalization',
 								),
 							]
@@ -589,9 +686,9 @@ export class IterationOrchestrator {
 					// mutation, and per-iteration this is trivial next to the model
 					// call it precedes.
 					// A step's skills and its guidance ride the same ephemeral
-					// trailing system message. Appending leaves the cached prefix
-					// intact; rewriting the run's own prompt to carry a phase's
-					// skills would invalidate it on every iteration.
+					// system message. A driver may move it before history; changing
+					// system guidance can therefore affect prefix caching. Observations
+					// that need no system authority use step.context below.
 					// `renderSkillsSection` already answers null for an empty list, so
 					// there is no length check here — a second guard for the same
 					// case is one more thing to keep in agreement with the first.
@@ -612,10 +709,9 @@ export class IterationOrchestrator {
 						? `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.
-					// `turn` contributions land HERE and nowhere else: in the
-					// system prompt they would be cached for the run or read as
-					// a standing instruction, and either way the state they
-					// exist to report goes stale silently.
+					// `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.
 					const turnSections =
 						this.ctx.promptContributions?.render('turn', {
 							iteration: iterationNum,
@@ -627,10 +723,12 @@ export class IterationOrchestrator {
 					const requestHistory = stepPreamble
 						? [...baseMessages, createSystemMessage(stepPreamble)]
 						: [...baseMessages]
+					if (step.context) requestHistory.push(this.stepContextMessage(step.context))
 					const messages = projectRequestRichContent(
 						this.projectObservations(requestHistory),
 						this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
+					this.appendWorkContext(messages, iterationNum, step)
 					await this.reportUnsupportedToolResults(messages)
 					yield* this.ctx.drainPending()
 
@@ -741,7 +839,12 @@ export class IterationOrchestrator {
 						model: requestedMember.model ?? stepModel,
 						chainIndex: requestedMember.index,
 					}
-					const { response, messageId } = yield* streamProviderTurn(
+					const operatorInputAtDispatch = this.latestUserMessage
+					const latestReviewUserMessage =
+						(this.ctx.reviewAnswer || this.ctx.structuredOutput?.review) && operatorInputAtDispatch
+							? structuredClone(operatorInputAtDispatch)
+							: undefined
+					const { response, messageId, requestMessages } = yield* streamProviderTurn(
 						this.ctx.provider,
 						{
 							model: stepModel,
@@ -794,8 +897,15 @@ export class IterationOrchestrator {
 						{
 							onAccepted: (identity) => this.acceptProviderRejectedImage(identity),
 						},
+						Boolean(
+							this.ctx.reviewAnswer || this.ctx.structuredOutput?.review || this.ctx.advisoryCtx,
+						),
 					)
 					stepResponse = response
+					const reviewRequest: ReviewRequest = {
+						...(requestMessages ? { requestMessages } : {}),
+						...(latestReviewUserMessage ? { latestUserMessage: latestReviewUserMessage } : {}),
+					}
 
 					// Who answered THIS turn.
 					//
@@ -804,18 +914,9 @@ export class IterationOrchestrator {
 					// request, so the member at the cursor when the stream ends is
 					// the one whose bytes are in `response`.
 					//
-					// It is taken here rather than at `recordStep` several hundred
-					// lines below, and the honest account of that is defence in
-					// depth, not a defect it currently prevents. Moving it down
-					// fails no test, because nothing between the two asks this
-					// provider for anything: compaction and working memory run
-					// BEFORE the turn, the advisory phase runs after the step is
-					// already recorded, and the only thing in between is tool
-					// execution. That is a fact about today's phase order, which a
-					// later phase inserted here would change silently — and the
-					// symptom would be a step attributed to a member that first
-					// served the turn after it, which is the class of wrongness
-					// this whole field exists to end.
+					// Capture before host review: its auxiliary inference can move
+					// the fallback cursor. Main-step usage and provenance must keep
+					// naming the provider that produced this candidate.
 					const servedBy: StepProvenance = ((): StepProvenance => {
 						const member = this.ctx.servingMember?.() ?? {
 							index: 0,
@@ -935,8 +1036,12 @@ export class IterationOrchestrator {
 								? { replayState: response.message.replayState }
 								: {}),
 						},
+						response.message.textParts,
 					)
 					runMgr.pushMessage(assistantMsg)
+					if (this.ctx.advisoryCtx && requestMessages) {
+						this.advisoryTurn = { iteration: iterationNum, requestMessages, response: assistantMsg }
+					}
 
 					if (this.ctx.workingStateManager && this.ctx.compactionConfig && assistantMsg.content) {
 						extractFromAssistantMessage(
@@ -1061,7 +1166,12 @@ export class IterationOrchestrator {
 								this.ctx.abortController.signal,
 							)
 							let outcome: 'accepted' | 'retry' | 'exhausted' | 'cancelled'
-							if (candidate.success) outcome = await this.reviewStructuredOutput(candidate.value)
+							if (candidate.success)
+								outcome = await this.reviewStructuredOutput(
+									candidate.value,
+									reviewRequest,
+									stepModel,
+								)
 							else {
 								this.nativeStructuredAttempts++
 								runMgr.pushMessage(
@@ -1207,7 +1317,11 @@ export class IterationOrchestrator {
 						// judge: bounded attempts, feedback as a user message, and
 						// a loud stop rather than a loop.
 						if (!forceFinalize && this.ctx.reviewAnswer) {
-							const review = await this.reviewAnswer(response.message.content ?? '')
+							const review = await this.reviewAnswer(
+								response.message.content ?? '',
+								reviewRequest,
+								stepModel,
+							)
 							if (this.ctx.abortController.signal.aborted) {
 								runMgr.setStopReason('cancelled')
 								runMgr.markCancelled()
@@ -1215,6 +1329,21 @@ export class IterationOrchestrator {
 							}
 							if (review && !review.accept) {
 								const attempt = ++this.answerReviewAttempts
+								runMgr.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)
+								await this.ctx.emitEvent({
+									type: 'checkpoint_created',
+									runId: runMgr.id,
+									checkpointId: checkpoint.id,
+									iteration: iterationNum,
+								})
+								if (this.ctx.abortController.signal.aborted) {
+									runMgr.setStopReason('cancelled')
+									runMgr.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', {
@@ -1230,7 +1359,6 @@ export class IterationOrchestrator {
 									'namzu.retry.attempt': attempt,
 									'namzu.runtime.limit': limit,
 								})
-								runMgr.pushMessage(createRuntimeContextMessage(review.feedback, 'answer-review'))
 								await this.ctx.emitEvent({
 									type: 'iteration_completed',
 									runId: runMgr.id,
@@ -1272,7 +1400,12 @@ export class IterationOrchestrator {
 							continue
 						}
 
-						let closingStopReason: StopReason | undefined
+						// A limit-requested summary bypasses prose review and further
+						// work. Preserve that limit on settlement, even if the provider
+						// reports a normal text completion and headroom still remains.
+						let closingStopReason: StopReason | undefined = forceFinalize
+							? guardResult.stopReason
+							: undefined
 						if (!hasContent && !forceFinalize) {
 							this.ctx.log.warn('Empty completion detected — requesting final summary', {
 								[NAMZU.ITERATION]: iterationNum,
@@ -1353,6 +1486,8 @@ export class IterationOrchestrator {
 					const structuredOutcome = await this.captureStructuredOutput(
 						reviewOutcome.results,
 						response,
+						reviewRequest,
+						stepModel,
 					)
 					if (
 						structuredOutcome === 'retry' ||
@@ -1379,10 +1514,6 @@ export class IterationOrchestrator {
 						break
 					}
 					if (structuredOutcome === 'accepted') {
-						this.ctx.log.info('Structured output produced — ending run', {
-							[NAMZU.RUN_ID]: runMgr.id,
-							[NAMZU.ITERATION]: iterationNum,
-						})
 						await this.ctx.emitEvent({
 							type: 'iteration_completed',
 							runId: runMgr.id,
@@ -1395,6 +1526,21 @@ export class IterationOrchestrator {
 							runMgr.markCancelled()
 							break
 						}
+						if (!forceFinalize) {
+							const inbound = this.deliverInbound()
+							// Tool-result steering may already have been delivered by
+							// runToolReview. Its candidate still answers the older input.
+							if (inbound > 0 || this.latestUserMessage !== operatorInputAtDispatch) continue
+						}
+						if (this.ctx.abortController.signal.aborted) {
+							runMgr.setStopReason('cancelled')
+							runMgr.markCancelled()
+							break
+						}
+						this.ctx.log.info('Structured output produced — ending run', {
+							[NAMZU.RUN_ID]: runMgr.id,
+							[NAMZU.ITERATION]: iterationNum,
+						})
 						this.publishStructuredOutput()
 						runMgr.setStopReason('end_turn')
 						break
@@ -1430,8 +1576,10 @@ export class IterationOrchestrator {
 					// returned — which is what makes a terminal submit_answer tool
 					// usable without discarding its output.
 					if (await this.shouldStop()) {
-						// Outstanding delegated work outranks the host's stop
-						// predicate, exactly once.
+						// Outstanding work outranks the host's stop predicate —
+						// a delegated task the completion inbox is expecting, or
+						// a background job the model told `wait_for_job` it is
+						// waiting on.
 						//
 						// This is a precedence rule chosen here, not something
 						// `stopWhen` implies — a stop predicate is a programmable
@@ -1440,13 +1588,20 @@ export class IterationOrchestrator {
 						// tool or a captured structured output. Those decide the
 						// result, so no turn follows and a hold would buy nothing.
 						// This one only says "stop", and stopping one turn later
-						// with the worker's result in hand is a better reading of
-						// the host's intent than stopping now and discarding it.
+						// with the result in hand is a better reading of the
+						// host's intent than stopping now and discarding it.
 						//
-						// Bounded: after the notification is delivered the inbox
-						// is drained, so the predicate fires again next turn with
-						// nothing pending and the run stops. Exactly one extra
-						// turn, and `maxIterations` bounds it regardless.
+						// Bounded by what is left to deliver, not by a count.
+						// Each delivery consumes what it delivered — the inbox is
+						// drained, and a job exit's notice is taken with the
+						// record of the exits it accounts for — so the predicate
+						// is asked again next turn against whatever is still
+						// 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
+						// it regardless, and a leg with nothing pending never
+						// opens a hold at all.
 						if (yield* this.holdForOutstandingWork(iterationNum, true)) {
 							// Remember WHY the next turn exists, so the turn that
 							// ends the run can name the host's decision instead of
@@ -1512,7 +1667,7 @@ export class IterationOrchestrator {
 					// in the history the next request is built from.
 					this.deliverInbound()
 
-					await runAdvisoryPhase(this.ctx, iterationNum, response)
+					await runAdvisoryPhase(this.ctx, iterationNum, response, this.getAdvisoryTurnContext())
 
 					if (this.ctx.pluginManager) {
 						const hookResults = await this.ctx.pluginManager.executeHooks(
@@ -1633,6 +1788,7 @@ export class IterationOrchestrator {
 					// would burn the budget to arrive at the same error.
 					if (
 						!overflowRelieved &&
+						!(err instanceof AnswerReviewFailure) &&
 						classifyProviderError(err, this.ctx.provider.id).code === 'context_length_exceeded'
 					) {
 						overflowRelieved = true
@@ -1660,6 +1816,7 @@ export class IterationOrchestrator {
 					iterSpan.recordException(err instanceof Error ? err : new Error(String(err)))
 					throw err
 				} finally {
+					this.advisoryTurn = undefined
 					// The only place the iteration span ends. It used to be ended at each of
 					// seventeen exits, which is a rule every future edit has to
 					// remember; a generator abandoned by its consumer never reached
@@ -1673,30 +1830,63 @@ export class IterationOrchestrator {
 	}
 
 	/**
-	 * Hold the run open for a worker that has not finished, and deliver it.
+	 * Hold the run open for work that has not finished, and deliver it.
 	 *
-	 * Returns whether a completion or operator message entered the transcript —
-	 * the caller continues on `true`, so the model gets a turn to respond.
-	 * That turn is the entire justification for waiting, which
+	 * Returns whether a completion, a job exit or an operator message entered
+	 * the transcript — the caller continues on `true`, so the model gets a turn
+	 * to respond. That turn is the entire justification for waiting, which
 	 * is why only the exits that can still take one call this.
 	 *
-	 * Bounded by `settleGraceMs` and by `maxIterations`, so a worker that never
-	 * finishes cannot keep the run open.
+	 * Two kinds of work qualify and they are raced together, because a run has
+	 * one settle point and one grace period to spend at it:
+	 *
+	 *  - a delegated task the `CompletionInbox` is still expecting;
+	 *  - a background job the model told `wait_for_job` it is waiting on.
+	 *
+	 * The job half is deliberately narrow. Intent comes from the wait and from
+	 * nothing else — a dev server the model started and never waited on is
+	 * running because somebody wanted it running, and a hold for it would add
+	 * the grace period to the end of every turn for the rest of the session.
+	 *
+	 * Each leg is opened only when it has something pending: both
+	 * `waitForArrival` implementations resolve immediately when their own side
+	 * is idle, so racing an idle one would end the hold before it began.
+	 *
+	 * Bounded by `settleGraceMs` and by `maxIterations`, so work that never
+	 * finishes cannot keep the run open. On a run with a deadline the grace is
+	 * a share of what is LEFT of it rather than a fresh allowance, so a
+	 * `wait_for_job` call that already spent minutes has shortened this hold
+	 * by the same minutes. On a run without one — the CLI's default — there is
+	 * no remainder to take a share of, and the job leg's own ceiling
+	 * (`awaitedJobGraceMs`) is what keeps a timed-out wait from being followed
+	 * by an hour of silence.
 	 */
 	private async *holdForOutstandingWork(
 		iterationNum: number,
 		hasToolCalls: boolean,
 	): AsyncGenerator<RunEvent, boolean> {
-		if (!this.ctx.completionInbox?.hasPendingWork) return false
+		const inbox = this.ctx.completionInbox?.hasPendingWork ? this.ctx.completionInbox : undefined
+		const jobs = this.ctx.awaitedJobs?.hasPendingWork ? this.ctx.awaitedJobs : undefined
+		if (!inbox && !jobs) return false
 
 		// Read HERE rather than from `forceFinalize`, which was sampled at the
 		// top of the iteration: one that has since crossed the finalize point
 		// must not open a wait against a reserve it has already entered.
-		const graceMs = settleGraceMs(this.ctx.guard.remainingBeforeFinalizeMs())
-		this.ctx.log.info('Holding the run open for a background task', {
+		const remainingMs = this.ctx.guard.remainingBeforeFinalizeMs()
+		// One deadline for the race, and it is the LONGEST ceiling any pending
+		// leg justifies. A leg resolving on its own timer ends the whole race,
+		// so handing the job leg its shorter ceiling while a task was also
+		// outstanding would cut the task's hold down to the job's — a run
+		// walking away from a worker it had time for, because a job happened
+		// to be running. A job therefore never shortens a wait, and it never
+		// lengthens one either: where a task is outstanding too, that is how
+		// long this run was waiting anyway.
+		const graceMs = inbox ? settleGraceMs(remainingMs) : awaitedJobGraceMs(remainingMs)
+		this.ctx.log.info('Holding the run open for outstanding work', {
 			[NAMZU.RUN_ID]: this.ctx.runMgr.id,
 			[NAMZU.ITERATION]: iterationNum,
 			'namzu.runtime.grace_ms': graceMs,
+			'namzu.runtime.awaited_jobs': jobs?.outstandingJobIds ?? [],
 		})
 		// User input releases this wait without cancelling any child. Both waits
 		// share a disposable signal so the losing arrival listener cannot leak.
@@ -1707,7 +1897,8 @@ export class IterationOrchestrator {
 		if (runSignal.aborted) cancelWait()
 		try {
 			await Promise.race([
-				this.ctx.completionInbox.waitForArrival(graceMs, waiting.signal),
+				...(inbox ? [inbox.waitForArrival(graceMs, waiting.signal)] : []),
+				...(jobs ? [jobs.waitForArrival(graceMs, waiting.signal)] : []),
 				...(this.ctx.waitForInbound ? [this.ctx.waitForInbound(waiting.signal)] : []),
 			])
 		} catch (error) {
@@ -1718,14 +1909,15 @@ export class IterationOrchestrator {
 		}
 		runSignal.throwIfAborted()
 
-		const arrived = this.ctx.completionInbox.drain()
+		const arrived = this.ctx.completionInbox?.drain() ?? []
 		if (arrived.length > 0) {
 			this.ctx.runMgr.pushMessage(
 				createRuntimeContextMessage(formatCompletionNotification(arrived), 'task-completion'),
 			)
 		}
+		const exited = this.deliverAwaitedJobExits()
 		const inbound = this.deliverInbound()
-		if (arrived.length === 0 && inbound === 0) return false
+		if (arrived.length === 0 && !exited && inbound === 0) return false
 		await this.ctx.emitEvent({
 			type: 'iteration_completed',
 			runId: this.ctx.runMgr.id,
@@ -1737,8 +1929,48 @@ export class IterationOrchestrator {
 	}
 
 	/**
-	 * Account for delegated work on the way out: deliver what arrived, and say
-	 * what did not.
+	 * Put the job exits this hold was waiting for in front of the model.
+	 *
+	 * Through `jobNotices`, which is the channel a job exit already travels on
+	 * — `attachNotice` rides it out on the next tool result — rather than a
+	 * second one built for this path. A turn that called no tools has no such
+	 * result, so the queued text becomes a `runtime-context` message instead,
+	 * exactly as `deliverInbound` does for steering that found no tool result
+	 * to attach to.
+	 *
+	 * That drain is also what keeps one exit from being delivered twice: the
+	 * channel hands its text over once, so an exit already attached to a tool
+	 * result earlier in the turn leaves nothing here — and the record of it
+	 * went with that delivery, so this returns `false` rather than buying a
+	 * turn to re-read what the model has read.
+	 *
+	 * `takeDelivery` is what pairs the two. Taking the exits first and then
+	 * finding no notice would discard them, which is the one way this path
+	 * can lose an exit outright; neither is taken unless both are there.
+	 *
+	 * The channel is not per-job, so the text taken here can include a notice
+	 * for a job nobody awaited that ended while the hold was open. Delivering
+	 * it is right — it is unread either way, and the alternative is stranding
+	 * it — but it is not a reason to WAIT, which is why what opens this hold
+	 * is `AwaitedJobs`, and the two are asked separately.
+	 */
+	private deliverAwaitedJobExits(): boolean {
+		const delivered = this.ctx.awaitedJobs?.takeDelivery(() => this.ctx.jobNotices?.drain())
+		if (!delivered) return false
+
+		this.ctx.log.info('Delivering a background job exit the run held open for', {
+			[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+			'namzu.runtime.jobs': delivered.exits.map((job) => job.id),
+		})
+		this.ctx.runMgr.pushMessage(
+			createRuntimeContextMessage(formatJobNote(delivered.text), 'job-exit'),
+		)
+		return true
+	}
+
+	/**
+	 * Account for outstanding work on the way out: deliver what arrived, and
+	 * say what did not.
 	 *
 	 * A run that ends with a worker outstanding must not leave the impression
 	 * that the worker's result was delivered. There are exactly two honest
@@ -1762,19 +1994,33 @@ export class IterationOrchestrator {
 	 */
 	private settleOutstandingWork(): void {
 		this.deliverArrivedCompletions()
+		this.deliverArrivedJobExits()
 		this.recordAbandonedWork()
 	}
 
-	/** Delegated work this run walked away from. See {@link settleOutstandingWork}. */
+	/** Work this run walked away from. See {@link settleOutstandingWork}. */
 	private recordAbandonedWork(): void {
 		const abandoned = this.ctx.completionInbox?.outstandingTaskIds ?? []
-		if (abandoned.length === 0) return
+		if (abandoned.length > 0) {
+			this.ctx.log.warn('Run ended with delegated work still running', {
+				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+				'namzu.runtime.tasks': abandoned,
+			})
+			this.ctx.runMgr.setAbandonedTaskIds(abandoned)
+		}
 
-		this.ctx.log.warn('Run ended with delegated work still running', {
+		// The same statement for a job the model was waiting on when the grace
+		// ran out. Only awaited ones: a job nobody waited for was never work
+		// this run was holding, so naming it would report an abandonment that
+		// did not happen.
+		const abandonedJobs = this.ctx.awaitedJobs?.outstandingJobIds ?? []
+		if (abandonedJobs.length === 0) return
+
+		this.ctx.log.warn('Run ended with an awaited background job still running', {
 			[NAMZU.RUN_ID]: this.ctx.runMgr.id,
-			'namzu.runtime.tasks': abandoned,
+			'namzu.runtime.jobs': abandonedJobs,
 		})
-		this.ctx.runMgr.setAbandonedTaskIds(abandoned)
+		this.ctx.runMgr.setAbandonedJobIds(abandonedJobs)
 	}
 
 	private deliverArrivedCompletions(): void {
@@ -1810,24 +2056,73 @@ export class IterationOrchestrator {
 	}
 
 	/**
-	 * Ask the host how to shape this step.
+	 * The job half of {@link deliverArrivedCompletions}: an exit that arrived
+	 * too late to earn a turn is still delivered on the way out.
 	 *
-	 * Fails OPEN on a throw — same reasoning as `stopWhen` and deliberately
-	 * opposite to a guardrail: a broken step-shaping hook should not kill an
-	 * otherwise healthy run, and unlike a safety check, nothing unsafe gets
-	 * through when it is skipped.
-	 */
-	/**
-	 * A host's chance to refuse the next model call.
+	 * The window this closes is one tick wide and it is nobody else's. An
+	 * awaited job that exits between the hold's grace expiring and the run
+	 * settling was never delivered — the hold had already looked — and is no
+	 * longer named either, because the exit took it off the outstanding list
+	 * on its way past, so `abandonedJobIds` would be lying to claim it. The
+	 * host's own listener is no help: the CLI queues an exit for the next
+	 * turn only when no run is in flight, and this one is still in flight.
+	 * Delivered here it reaches `Run.messages`, so the transcript has it and
+	 * a continued thread opens with it.
 	 *
-	 * Fails CLOSED, which is the opposite of `prepareStep` below and the
-	 * reason they are separate hooks rather than one with two return
-	 * shapes. A broken step-SHAPER skipped costs a run its per-step tuning;
-	 * a broken step-REFUSER skipped is a refusal that did not happen, which
-	 * is precisely what the hook exists to prevent. The thrown error's
-	 * message becomes the reason, so an operator is not left with a run
-	 * that stopped and no account of it.
+	 * Before `recordAbandonedWork`, which then reports only what is still
+	 * running, and after `deliverArrivedCompletions`, so the two appended
+	 * messages land in the order the work finished in.
 	 */
+	private deliverArrivedJobExits(): void {
+		const delivered = this.ctx.awaitedJobs?.takeDelivery(() => this.ctx.jobNotices?.drain())
+		if (!delivered) return
+
+		// Fix the run's answer BEFORE appending anything after it — the same
+		// `resolveResult` tail walk `deliverArrivedCompletions` explains just
+		// above, and the same guard against pinning an empty one.
+		const answer = this.ctx.runMgr.materializeResult()
+		if (answer.length > 0) this.ctx.runMgr.setResult(answer)
+
+		this.ctx.log.info('Delivering a background job exit the run would have settled over', {
+			[NAMZU.RUN_ID]: this.ctx.runMgr.id,
+			'namzu.runtime.jobs': delivered.exits.map((job) => job.id),
+		})
+		this.ctx.runMgr.pushMessage(
+			createRuntimeContextMessage(formatJobNote(delivered.text), 'job-exit'),
+		)
+	}
+
+	private stepContextMessage(content: string) {
+		return createRuntimeContextMessage(
+			`Current step context (runtime-generated; not a new user request):\n${content}`,
+			'step-context',
+		)
+	}
+
+	/** Derived after request projection; never accumulates in canonical history or replaces operator intent. */
+	private appendWorkContext(
+		messages: Message[],
+		stepNumber: number,
+		prepared: PrepareStepResult,
+	): void {
+		const contributions = [
+			this.ctx.completionInbox?.describeOwnedWork(),
+			this.ctx.toolExecutor.describeFileEvidence(messages),
+		].filter((content): content is string => Boolean(content))
+		if (contributions.length === 0) return
+		let room = this.stepContext(stepNumber, prepared).contextBudget?.remainingTokens ?? 0
+		// Leave room for the actual task; admit whole contributions, never dangling partial references.
+		if (room < 1_500) return
+		for (const content of contributions) {
+			if (!content || content.length > 8_000) continue
+			const message = this.stepContextMessage(content)
+			const tokens = estimateMessageTokens(message)
+			if (tokens > Math.min(2_000, room - 1_000)) continue
+			messages.push(message)
+			room -= tokens
+		}
+	}
+
 	private stepContext(stepNumber: number, prepared: PrepareStepResult): PrepareStepContext {
 		const model = prepared.model ?? this.ctx.runConfig.model
 		const window = resolveContextWindow(
@@ -1841,7 +2136,9 @@ export class IterationOrchestrator {
 		)
 		const skills = prepared.skills ? renderSkillsSection([...prepared.skills]) : null
 		const preamble = [prepared.system, skills].filter(Boolean).join('\n\n')
-		const preparedTokens = preamble ? estimateMessageTokens(createSystemMessage(preamble)) : 0
+		const preparedTokens =
+			(preamble ? estimateMessageTokens(createSystemMessage(preamble)) : 0) +
+			(prepared.context ? estimateMessageTokens(this.stepContextMessage(prepared.context)) : 0)
 		const responseReserve = Math.min(
 			prepared.maxResponseTokens ??
 				this.ctx.runConfig.maxResponseTokens ??
@@ -1852,6 +2149,7 @@ export class IterationOrchestrator {
 			runId: this.ctx.runMgr.id,
 			stepNumber,
 			messages: this.ctx.runMgr.messages,
+			...(this.ctx.captureRunEvidence ? { captureRunEvidence: this.ctx.captureRunEvidence } : {}),
 			...(this.latestUserMessage ? { latestUserMessage: this.latestUserMessage } : {}),
 			signal: this.ctx.abortController.signal,
 			contextBudget: {
@@ -1868,6 +2166,7 @@ export class IterationOrchestrator {
 		}
 	}
 
+	/** Refuse the next call on a veto or hook error; do not skip a failed admission check. */
 	private async beforeStep(stepNumber: number): Promise<StepVeto | undefined> {
 		const configured = this.ctx.beforeStep
 		if (!configured) return undefined
@@ -1878,11 +2177,13 @@ export class IterationOrchestrator {
 		}
 	}
 
+	/** Shape the next request. A failed tuning stage is skipped; admission belongs to beforeStep. */
 	private async prepareStep(stepNumber: number): Promise<{
 		allowedTools?: string[]
 		toolChoice?: ToolChoice
 		model?: string
 		system?: string
+		context?: string
 		skills?: readonly Skill[]
 		temperature?: number
 		maxResponseTokens?: number
@@ -1897,8 +2198,16 @@ export class IterationOrchestrator {
 		// rather than an accident of install history.
 		let result: PrepareStepResult = {}
 		for (const stage of stages) {
+			const inference = createCallbackInference(
+				this.ctx,
+				result.model ?? this.ctx.runConfig.model,
+				'preparation',
+			)
 			try {
-				const decided = await stage(this.stepContext(stepNumber, result))
+				const decided = await stage({
+					...this.stepContext(stepNumber, result),
+					generateText: inference.generateText,
+				})
 				if (decided) result = { ...result, ...decided }
 				await this.selectContextModel(result.model ?? this.ctx.runConfig.model)
 			} catch (err) {
@@ -1909,6 +2218,23 @@ export class IterationOrchestrator {
 					'namzu.runtime.step_number': stepNumber,
 					'exception.message': toErrorMessage(err),
 				})
+				// An SDK stage may report availability and validated fallback evidence
+				// without exposing its error. Preserve prior decisions and the context budget;
+				// ordinary exceptions still contribute nothing to the model request.
+				if (err instanceof PreparationContextError && !this.ctx.abortController.signal.aborted) {
+					const room = this.stepContext(stepNumber, result).contextBudget?.remainingTokens ?? 0
+					if (
+						typeof err.context === 'string' &&
+						err.context.length > 0 &&
+						err.context.length + (result.context ? 2 : 0) <= Math.min(12_000, Math.floor(room))
+					)
+						result = {
+							...result,
+							context: [result.context, err.context].filter(Boolean).join('\n\n'),
+						}
+				}
+			} finally {
+				inference.close()
 			}
 		}
 
@@ -1917,6 +2243,7 @@ export class IterationOrchestrator {
 			toolChoice?: ToolChoice
 			model?: string
 			system?: string
+			context?: string
 			skills?: readonly Skill[]
 			temperature?: number
 			maxResponseTokens?: number
@@ -1953,6 +2280,7 @@ export class IterationOrchestrator {
 		if (result.toolChoice !== undefined) prepared.toolChoice = result.toolChoice
 		if (result.model !== undefined) prepared.model = result.model
 		if (result.system !== undefined) prepared.system = result.system
+		if (result.context !== undefined) prepared.context = result.context
 		if (result.skills !== undefined) prepared.skills = result.skills
 		if (result.temperature !== undefined) prepared.temperature = result.temperature
 		if (result.maxResponseTokens !== undefined) {
@@ -2237,6 +2565,8 @@ export class IterationOrchestrator {
 	private async captureStructuredOutput(
 		results: readonly ToolCallOutcome[],
 		response: ChatCompletionResponse,
+		reviewRequest: ReviewRequest,
+		model: string,
 	): Promise<'absent' | 'accepted' | 'retry' | 'exhausted' | 'cancelled'> {
 		if (!this.needsStructuredOutput() || this.ctx.structuredOutput?.mode === 'native')
 			return 'absent'
@@ -2264,7 +2594,7 @@ export class IterationOrchestrator {
 				)
 			parsed = hit.output
 		}
-		return this.reviewStructuredOutput(parsed)
+		return this.reviewStructuredOutput(parsed, reviewRequest, model)
 	}
 
 	private publishStructuredOutput(): void {
@@ -2274,6 +2604,8 @@ export class IterationOrchestrator {
 
 	private async reviewStructuredOutput(
 		parsed: unknown,
+		reviewRequest: ReviewRequest,
+		model: string,
 	): Promise<'accepted' | 'retry' | 'exhausted' | 'cancelled'> {
 		if (this.ctx.abortController.signal.aborted) return 'cancelled'
 		const reviewer = this.ctx.structuredOutput?.review
@@ -2286,22 +2618,27 @@ export class IterationOrchestrator {
 				signal.addEventListener('abort', onAbort, { once: true })
 			})
 			let verdict: AnswerReview
+			const inference = createCallbackInference(this.ctx, model, 'review')
 			try {
 				verdict = await Promise.race([
-					Promise.resolve().then(() =>
-						reviewer(structuredClone(parsed), {
+					Promise.resolve().then(() => {
+						signal.throwIfAborted()
+						return reviewer(structuredClone(parsed), {
 							runId: this.ctx.runMgr.id,
 							iteration: this.ctx.runMgr.currentIteration,
 							signal,
 							messages: this.ctx.runMgr.messages,
-						}),
-					),
+							...reviewRequest,
+							generateText: inference.generateText,
+						})
+					}),
 					aborted,
 				])
 			} catch (error) {
 				if (signal.aborted) return 'cancelled'
 				throw error
 			} finally {
+				inference.close()
 				signal.removeEventListener('abort', onAbort)
 			}
 			if (signal.aborted) return 'cancelled'
@@ -2335,33 +2672,48 @@ export class IterationOrchestrator {
 		return 'accepted'
 	}
 
-	/**
-	 * Ask the host whether this answer is good enough.
-	 *
-	 * A hook that throws **accepts**, which is the opposite of what the
-	 * safety gates do, and deliberately so. Those are asked "is this
-	 * dangerous", where the cost of failing closed is one refused
-	 * operation. This is asked "is this good enough", where failing closed
-	 * means handing the answer back forever — so a broken judge would turn
-	 * every run into a loop that ends on a budget error naming nothing. One
-	 * unreviewed answer is the cheaper failure, and the throw is logged at
-	 * `error` so it is not mistaken for approval.
-	 */
-	private async reviewAnswer(answer: string): Promise<AnswerReview | undefined> {
-		if (!this.ctx.reviewAnswer) return undefined
+	/** A reviewer failure aborts settlement; only an explicit rejection requests correction. */
+	private async reviewAnswer(
+		answer: string,
+		reviewRequest: ReviewRequest,
+		model: string,
+	): Promise<AnswerReview | undefined> {
+		const reviewer = this.ctx.reviewAnswer
+		const signal = this.ctx.abortController.signal
+		if (!reviewer || signal.aborted) return undefined
+		let onAbort = () => {}
+		const aborted = new Promise<never>((_resolve, reject) => {
+			onAbort = () => reject(signal.reason ?? new Error('Answer review cancelled'))
+			signal.addEventListener('abort', onAbort, { once: true })
+		})
+		const inference = createCallbackInference(this.ctx, model, 'review')
 		try {
-			return await this.ctx.reviewAnswer(answer, {
-				runId: this.ctx.runMgr.id,
-				iteration: this.ctx.runMgr.currentIteration,
-				signal: this.ctx.abortController.signal,
-				messages: this.ctx.runMgr.messages,
-			})
-		} catch (err) {
-			this.ctx.log.error('Answer review threw — accepting the answer unreviewed', {
-				[NAMZU.RUN_ID]: this.ctx.runMgr.id,
-				'exception.message': toErrorMessage(err),
-			})
-			return { accept: true }
+			const verdict = await Promise.race([
+				Promise.resolve().then(() => {
+					signal.throwIfAborted()
+					return reviewer(answer, {
+						runId: this.ctx.runMgr.id,
+						iteration: this.ctx.runMgr.currentIteration,
+						signal,
+						messages: this.ctx.runMgr.messages,
+						...reviewRequest,
+						generateText: inference.generateText,
+					})
+				}),
+				aborted,
+			])
+			if (signal.aborted) return undefined
+			if (!verdict || typeof verdict.accept !== 'boolean')
+				throw new Error('Answer reviewer returned an invalid verdict')
+			if (!verdict.accept && (typeof verdict.feedback !== 'string' || !verdict.feedback.trim()))
+				throw new Error('Answer reviewer rejection requires feedback')
+			return verdict
+		} catch (error) {
+			if (signal.aborted) return undefined
+			throw new AnswerReviewFailure(error)
+		} finally {
+			inference.close()
+			signal.removeEventListener('abort', onAbort)
 		}
 	}
 
@@ -2445,7 +2797,7 @@ export class IterationOrchestrator {
 			const finalHistory = [
 				...this.ctx.runMgr.messages,
 				createRuntimeContextMessage(
-					`[SYSTEM] Run is ending due to ${reason}. You MUST provide a final response now summarizing all your findings and work so far. Do not use any tools.`,
+					`[SYSTEM] Run is ending due to ${reason}. ${CLOSING_RESPONSE_GUIDANCE}`,
 					'limit-finalization',
 				),
 			]
@@ -2453,6 +2805,7 @@ export class IterationOrchestrator {
 				this.projectObservations(finalHistory),
 				this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 			)
+			this.appendWorkContext(finalMessages, this.steps.length + 1, { model })
 			await this.reportUnsupportedToolResults(finalMessages)
 
 			// Same cache discipline as the forced-final iteration: keep the
@@ -2517,6 +2870,7 @@ export class IterationOrchestrator {
 						? { replayState: response.message.replayState }
 						: {}),
 				},
+				response.message.textParts,
 			)
 			this.ctx.runMgr.pushMessage(assistantMsg)
 
@@ -2535,6 +2889,7 @@ export class IterationOrchestrator {
 				stopReason: 'forced_finalize',
 				usage: response.usage,
 				content: response.message.content ?? undefined,
+				...(response.message.textParts ? { textParts: response.message.textParts } : {}),
 			})
 		} catch (err) {
 			this.ctx.log.error('Failed to get final response', {
@@ -2556,6 +2911,8 @@ export class IterationOrchestrator {
  * threw and is left saying so rather than dressed up as something specific.
  */
 function describeStepFailure(err: unknown, providerId: string): StepFailure {
+	if (err instanceof AnswerReviewFailure)
+		return { message: err.message, code: 'unknown', retryable: false }
 	const classified = classifyProviderError(err, providerId)
 	return {
 		message: toErrorMessage(err),