@namzu/sdk 42.0.0 → 42.0.1

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

@@ -1,10 +1,8 @@
 import { type Span, SpanStatusCode } from '@opentelemetry/api'
-import { resolveContextWindow } from '../../../compaction/context-window.js'
 import {
 	extractFromAssistantMessage,
 	extractFromUserMessage,
 } from '../../../compaction/extractor.js'
-import { estimateMessageTokens } from '../../../compaction/token-estimate.js'
 import { AUTO_CONTINUATION_USER_MESSAGE } from '../../../constants/continuation.js'
 import {
 	DEFAULT_STRUCTURED_OUTPUT_RETRIES,
@@ -14,7 +12,6 @@ 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,
@@ -24,7 +21,6 @@ import {
 } from '../../../telemetry/attributes.js'
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js'
-import { DELEGATION_TIMEOUT_MS } from '../../../tools/coordinator/index.js'
 import type { CostInfo, TokenUsage } from '../../../types/common/index.js'
 import { NamzuError } from '../../../types/errors/index.js'
 import type { MessageId } from '../../../types/ids/index.js'
@@ -35,23 +31,17 @@ import {
 	createRuntimeContextMessage,
 	createSystemMessage,
 } from '../../../types/message/index.js'
-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, AnswerReviewContext } from '../../../types/run/answer-review.js'
 import type {
-	PrepareStepContext,
-	PrepareStepResult,
 	RunEvent,
 	StepFailure,
 	StepProvenance,
 	StepResult,
-	StepVeto,
 	StopReason,
 } 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'
@@ -70,8 +60,9 @@ import {
 	markProviderRejectedImage,
 	projectRequestRichContent,
 } from '../request-rich-content.js'
-import { formatJobNote, formatSteeringNote, isOperatorUserMessage } from '../steering.js'
+import { formatSteeringNote, isOperatorUserMessage } from '../steering.js'
 import { parseNativeCandidate } from './native-output.js'
+import { holdForOutstandingWork, settleOutstandingWork } from './outstanding-work.js'
 import { runAdvisoryPhase } from './phases/advisory.js'
 import { runIterationCheckpoint } from './phases/checkpoint.js'
 import {
@@ -85,6 +76,14 @@ import { runPlanGate } from './phases/plan.js'
 import { runToolReview } from './phases/tool-review.js'
 import { refreshWorkingMemory } from './phases/working-memory.js'
 import { streamWithProviderRejectedImageRecovery } from './provider-rejected-image.js'
+import {
+	type StepShaping,
+	appendWorkContext,
+	beforeStep,
+	prepareStep,
+	selectContextModel,
+	stepContextMessage,
+} from './step-shaping.js'
 import { streamProviderTurn } from './stream-turn.js'
 
 type ReviewRequest = Pick<AnswerReviewContext, 'requestMessages' | 'latestUserMessage'>
@@ -120,105 +119,7 @@ const DEFAULT_ANSWER_REVIEW_LIMIT = 3
 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.
- *
- * The rule is borrowed from `AGENT_MANAGER_DEFAULTS.maxBudgetFraction`, which
- * gives a spawned child at most half of what its parent has left: one
- * sub-activity may take a share of the remainder, never the remainder. The
- * value is written out here rather than imported, because that field is a
- * host-tunable knob about TOKEN allocation and coupling the two would let a
- * host lowering one silently change the other.
- *
- * Half, specifically, because the hold is not the last thing the run does.
- * Its whole purpose is to put a worker's result where the model can read it,
- * and reading it costs a turn. A hold that spent everything remaining would
- * deliver a notification into a run with no turn left to act on it — the same
- * "the result exists and the model is never told" failure this mechanism was
- * built to close, wearing a different costume.
- */
-const SETTLE_GRACE_FRACTION = 0.5
-
-/**
- * How long a finishing run waits for a background worker it launched.
- *
- * Derived from the run rather than fixed, because a constant is wrong in both
- * directions at once. The 120 seconds this replaces held a run configured for
- * a twenty-second timeout open for 120,267 ms — six times its own budget, and
- * unreachable by the guard, which only checks between iterations — while on an
- * hour-long run it abandoned workers measured at 4m21s, 5m58s and 8m04s, all
- * of them well inside the hour the delegation tools themselves declare.
- *
- * **Bounded by construction, and against the right boundary.** The input is
- * time-to-FINALIZE, not time-to-deadline (see
- * `GuardCoordinator.remainingBeforeFinalizeMs`). Measuring to the deadline was
- * the first attempt and it was wrong in a way that looked safe: a hold cannot
- * outlive the deadline either way, but half of the time-to-deadline started
- * just under the warning threshold ends at 95% of the budget — so the slice
- * that exists for the run to produce a closing answer is half spent waiting
- * for the result that answer was supposed to use. Against the finalize point
- * the hold cannot reach the reserve at all, which is what makes the guard's
- * inability to interrupt a hold a non-issue rather than a smaller issue.
- *
- * **The floor of zero is a decision, not a clamp artefact.** A run with no
- * time left before it must start finishing has no turn in which to read a
- * notification, so waiting could only delay a stop that is already due.
- * Nothing is lost by it: `CompletionInbox.waitForArrival` returns before it
- * looks at its timer when a completion is already in hand, so a zero grace
- * still delivers everything that has arrived. No minimum is invented on top,
- * because zero is exactly what a run past the threshold should wait — and
- * reading the remainder at hold time rather than trusting `forceFinalize`,
- * which is sampled at the top of the iteration, is what makes a long iteration
- * that crossed the line in between compute it.
- *
- * **The ceiling is the longest anything in this subsystem waits for a
- * delegated worker.** It binds only for a host whose run timeout exceeds
- * roughly two and a quarter hours; below that the fraction is smaller.
- */
-export function settleGraceMs(remainingBeforeFinalizeMs: number): number {
-	return Math.min(
-		Math.floor(remainingBeforeFinalizeMs * SETTLE_GRACE_FRACTION),
-		DELEGATION_TIMEOUT_MS,
-	)
-}
-
-/**
- * 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 { awaitedJobGraceMs, settleGraceMs } from './outstanding-work.js'
 
 export class IterationOrchestrator {
 	private ctx: IterationContext
@@ -503,7 +404,7 @@ 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 this.beforeStep(runMgr.currentIteration + 1)
+				const veto = await beforeStep(this.stepShaping(), runMgr.currentIteration + 1)
 				// The hook may settle because its run signal was aborted. Stop
 				// before interpreting that settlement as a policy refusal or
 				// counting an iteration that will never reach the provider.
@@ -634,12 +535,12 @@ export class IterationOrchestrator {
 					// 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)
+					const step = await prepareStep(this.stepShaping(), 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)
+					await selectContextModel(this.stepShaping(), stepModel)
 					// Preserve post-compaction preparation/recall semantics. A changed
 					// model needs a second check against its own window; never replay
 					// host preparation effects merely to rebuild its request guidance.
@@ -723,12 +624,12 @@ export class IterationOrchestrator {
 					const requestHistory = stepPreamble
 						? [...baseMessages, createSystemMessage(stepPreamble)]
 						: [...baseMessages]
-					if (step.context) requestHistory.push(this.stepContextMessage(step.context))
+					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.appendWorkContext(messages, iterationNum, step)
+					appendWorkContext(this.stepShaping(), messages, iterationNum, step)
 					await this.reportUnsupportedToolResults(messages)
 					yield* this.ctx.drainPending()
 
@@ -1206,7 +1107,9 @@ export class IterationOrchestrator {
 							}
 							if (outcome === 'accepted') {
 								if (!forceFinalize) {
-									const changed = yield* this.holdForOutstandingWork(iterationNum, false)
+									const changed = yield* holdForOutstandingWork(this.ctx, iterationNum, false, () =>
+										this.deliverInbound(),
+									)
 									const inbound = this.deliverInbound()
 									if (changed || inbound > 0) continue
 								}
@@ -1376,7 +1279,12 @@ export class IterationOrchestrator {
 						// 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.
-						if (!forceFinalize && (yield* this.holdForOutstandingWork(iterationNum, false))) {
+						if (
+							!forceFinalize &&
+							(yield* holdForOutstandingWork(this.ctx, iterationNum, false, () =>
+								this.deliverInbound(),
+							))
+						) {
 							continue
 						}
 
@@ -1602,7 +1510,11 @@ export class IterationOrchestrator {
 						// `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)) {
+						if (
+							yield* holdForOutstandingWork(this.ctx, iterationNum, true, () =>
+								this.deliverInbound(),
+							)
+						) {
 							// Remember WHY the next turn exists, so the turn that
 							// ends the run can name the host's decision instead of
 							// reporting the shape of the last message.
@@ -1825,481 +1737,23 @@ export class IterationOrchestrator {
 				}
 			}
 		} finally {
-			this.settleOutstandingWork()
-		}
-	}
-
-	/**
-	 * Hold the run open for work that has not finished, and deliver it.
-	 *
-	 * 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.
-	 *
-	 * 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> {
-		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 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.
-		const waiting = new AbortController()
-		const runSignal = this.ctx.abortController.signal
-		const cancelWait = () => waiting.abort(runSignal.reason)
-		runSignal.addEventListener('abort', cancelWait, { once: true })
-		if (runSignal.aborted) cancelWait()
-		try {
-			await Promise.race([
-				...(inbox ? [inbox.waitForArrival(graceMs, waiting.signal)] : []),
-				...(jobs ? [jobs.waitForArrival(graceMs, waiting.signal)] : []),
-				...(this.ctx.waitForInbound ? [this.ctx.waitForInbound(waiting.signal)] : []),
-			])
-		} catch (error) {
-			if (!runSignal.aborted) throw error
-		} finally {
-			waiting.abort()
-			runSignal.removeEventListener('abort', cancelWait)
-		}
-		runSignal.throwIfAborted()
-
-		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 && !exited && inbound === 0) return false
-		await this.ctx.emitEvent({
-			type: 'iteration_completed',
-			runId: this.ctx.runMgr.id,
-			iteration: iterationNum,
-			hasToolCalls,
-		})
-		yield* this.ctx.drainPending()
-		return true
-	}
-
-	/**
-	 * 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
-	 * outcomes and this does both:
-	 *
-	 *  - **What has already arrived is delivered.** It makes no false claim,
-	 *    and dropping it is pure loss — the message rides out on
-	 *    `Run.messages`, so a host reads it and the next turn of a continued
-	 *    thread starts with it. This does NOT wait: a hold buys the model a
-	 *    turn in which to USE a result, and on an exit whose answer is already
-	 *    decided there is no such turn, so waiting would delay a settled answer
-	 *    to append text this run will not read. The bounded hold stays where it
-	 *    was, on the exits that do have a turn left.
-	 *  - **What is still running is NAMED, not cancelled.** Giving up on a wait
-	 *    is a statement about the waiter, not about the work — the rule
-	 *    `wait-with-idle-bound.ts` already states for the same subsystem — and
-	 *    "the parent answered early" is a weaker warrant for killing a child
-	 *    than "the clock ran out", not a stronger one. Killing a worker that
-	 *    may be mid-write is a policy only the host can judge, and it has
-	 *    `cancel_task` and the run controller to judge it with.
-	 */
-	private settleOutstandingWork(): void {
-		this.deliverArrivedCompletions()
-		this.deliverArrivedJobExits()
-		this.recordAbandonedWork()
-	}
-
-	/** Work this run walked away from. See {@link settleOutstandingWork}. */
-	private recordAbandonedWork(): void {
-		const abandoned = this.ctx.completionInbox?.outstandingTaskIds ?? []
-		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)
+			settleOutstandingWork(this.ctx)
 		}
-
-		// 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.jobs': abandonedJobs,
-		})
-		this.ctx.runMgr.setAbandonedJobIds(abandonedJobs)
-	}
-
-	private deliverArrivedCompletions(): void {
-		const unheard = this.ctx.completionInbox?.drain() ?? []
-		if (unheard.length === 0) return
-
-		// Fix the run's answer BEFORE appending anything after it.
-		//
-		// `RunPersistence.resolveResult` walks the message tail backwards and
-		// stops at the first non-assistant message, and it runs at
-		// `markCompleted` — which is AFTER this. So a notification appended
-		// after the final assistant turn makes the run's own answer
-		// unreachable. Measured, on a run whose model had just said "THIS IS
-		// THE RUN ANSWER.": `run.result` came back `undefined`. That trades a
-		// lost worker result for a lost RUN result, which is strictly worse
-		// than the defect this delivery exists to fix.
-		//
-		// Materialising resolves it while the tail is still the assistant's;
-		// pinning it means the later re-resolution cannot undo the fix. Only
-		// when there is something to pin: on the cancelled and thrown paths
-		// there may be no answer, and pinning an empty string there would
-		// suppress whatever the error path assembles.
-		const answer = this.ctx.runMgr.materializeResult()
-		if (answer.length > 0) this.ctx.runMgr.setResult(answer)
-
-		this.ctx.log.info('Delivering task completions the run would have settled over', {
-			[NAMZU.RUN_ID]: this.ctx.runMgr.id,
-			'namzu.runtime.tasks': unheard.map((h) => h.taskId),
-		})
-		this.ctx.runMgr.pushMessage(
-			createRuntimeContextMessage(formatCompletionNotification(unheard), 'task-completion'),
-		)
 	}
 
 	/**
-	 * The job half of {@link deliverArrivedCompletions}: an exit that arrived
-	 * too late to earn a turn is still delivered on the way out.
+	 * The context and the two live reads the step-shaping helpers share.
 	 *
-	 * 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.
-	 *
-	 * 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.
+	 * Built per call rather than held: `latestUserMessage` is replaced on
+	 * every operator turn and `steps` grows by one per step, so a captured
+	 * value would describe an earlier return.
 	 */
-	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(
-			this.ctx.compactionConfig?.contextWindowTokens,
-			model,
-			model === this.ctx.runConfig.model
-				? this.ctx.providerContextWindow
-				: model === this.ctx.contextModel
-					? this.ctx.activeProviderContextWindow
-					: undefined,
-		)
-		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) +
-			(prepared.context ? estimateMessageTokens(this.stepContextMessage(prepared.context)) : 0)
-		const responseReserve = Math.min(
-			prepared.maxResponseTokens ??
-				this.ctx.runConfig.maxResponseTokens ??
-				Math.floor(window.tokens / 4),
-			Math.floor(window.tokens / 4),
-		)
+	private stepShaping(): StepShaping {
 		return {
-			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: {
-				windowTokens: window.tokens,
-				remainingTokens: Math.max(
-					0,
-					Math.floor(
-						window.tokens - measureContext(this.ctx).tokens - preparedTokens - responseReserve,
-					),
-				),
-			},
-			steps: this.steps,
-			prepared,
-		}
-	}
-
-	/** 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
-		try {
-			return (await configured(this.stepContext(stepNumber, {}))) ?? undefined
-		} catch (err) {
-			return { reason: `beforeStep threw: ${toErrorMessage(err)}` }
-		}
-	}
-
-	/** 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
-	}> {
-		const configured = this.ctx.prepareStep
-		if (!configured) return {}
-		const stages = Array.isArray(configured) ? configured : [configured]
-
-		// Folded in DECLARATION order, each stage seeing what the ones
-		// before it decided. A later stage overriding a field is last-writer
-		// wins — visibly, because the order is a line in the host's code
-		// 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),
-					generateText: inference.generateText,
-				})
-				if (decided) result = { ...result, ...decided }
-				await this.selectContextModel(result.model ?? this.ctx.runConfig.model)
-			} catch (err) {
-				// Skipped, and the rest still run: one broken concern must
-				// not silently disable the others it was declared beside.
-				this.ctx.log.error('a prepareStep stage threw — skipping it', {
-					[NAMZU.RUN_ID]: this.ctx.runMgr.id,
-					'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()
-			}
-		}
-
-		const prepared: {
-			allowedTools?: string[]
-			toolChoice?: ToolChoice
-			model?: string
-			system?: string
-			context?: string
-			skills?: readonly Skill[]
-			temperature?: number
-			maxResponseTokens?: number
-		} = {}
-
-		if (result.activeTools) {
-			const known = result.activeTools.filter((name: string) => this.ctx.tools.has(name))
-			const unknown = result.activeTools.filter((name: string) => !this.ctx.tools.has(name))
-			if (unknown.length > 0) {
-				// The all-unknown case gets its own sentence because it has its
-				// own consequence. Some names dropped narrows the step; ALL of
-				// them dropped leaves it able to call nothing — which is the
-				// honest reading of "only these tools" when none of them exist,
-				// and is not what a reader of "ignoring them" would expect.
-				//
-				// Widening back to the run's list would be worse: it grants
-				// exactly the tools the caller asked to exclude, on the grounds
-				// that their own list failed. A step that can call nothing is
-				// constrained; a step that can call everything is a control
-				// that stopped applying.
-				const message =
-					known.length === 0
-						? 'prepareStep named only tools that are not registered — this step can call nothing'
-						: 'prepareStep named tools that are not registered — ignoring them'
-				this.ctx.log.warn(message, {
-					[NAMZU.RUN_ID]: this.ctx.runMgr.id,
-					'namzu.runtime.step_number': stepNumber,
-					'namzu.runtime.unknown': unknown,
-					'namzu.runtime.remaining': known.length,
-				})
-			}
-			prepared.allowedTools = known
-		}
-		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) {
-			prepared.maxResponseTokens = result.maxResponseTokens
-		}
-
-		return prepared
-	}
-
-	private async selectContextModel(model: string | undefined): Promise<void> {
-		if (model !== (this.ctx.contextModel ?? this.ctx.runConfig.model)) {
-			// A measurement from another tokenizer cannot price the new request.
-			this.ctx.runMgr.clearLastPromptTokens()
+			ctx: this.ctx,
+			latestUserMessage: () => this.latestUserMessage,
+			steps: () => this.steps,
 		}
-		this.ctx.contextModel = model
-		this.ctx.activeProviderContextWindow =
-			model && model !== this.ctx.runConfig.model && !this.ctx.compactionConfig?.contextWindowTokens
-				? await this.ctx.resolveModelContextWindow?.(model)
-				: undefined
 	}
 
 	/** Steps completed so far, exposed on the returned `Run`. */
@@ -2805,7 +2259,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 })
+			appendWorkContext(this.stepShaping(), finalMessages, this.steps.length + 1, { model })
 			await this.reportUnsupportedToolResults(finalMessages)
 
 			// Same cache discipline as the forced-final iteration: keep the