@namzu/sdk 39.0.0 → 40.0.0

package/src/runtime/query/file-evidence-seed.ts

@@ -0,0 +1,126 @@
+import { resolveWithinAnyReal, toolRoots } from '../../tools/paths.js'
+import type { Message } from '../../types/message/index.js'
+import type { FileReadTracker } from '../../types/tool/index.js'
+import {
+	type FileKeyResolver,
+	type LedgerReplayReport,
+	type PathAttributions,
+	collectObservedPaths,
+	createPathAttributions,
+	replayObservationLedger,
+} from './file-evidence-replay.js'
+
+/**
+ * Seeding an observation ledger from history, in the key space the tools use.
+ *
+ * The replay itself is pure and stays that way. What lives here is the one
+ * thing it cannot do for itself: work out which ledger key each path in the
+ * history belongs to. On a host that is not `resolve(cwd, path)` — `write`,
+ * `edit` and `read` all key on `resolveWithinAnyReal`, which canonicalizes
+ * every symlink on the way, because a ledger entry has to identify a FILE and
+ * two spellings of one file must not become two entries.
+ *
+ * Seeding lexically instead is worse than useless. The projection looks up
+ * lexically too, so it would match a fingerprint the seed had just written into
+ * a key space nothing else touches — while every drift refusal, made by a tool,
+ * lands on the canonical key and never withdraws it. The runtime would go on
+ * telling the model a body it can no longer vouch for, with no mechanism left
+ * to take it back. So the resolution happens here, with the tools' own
+ * function, and a path that will not resolve gets no key at all.
+ */
+const NOTHING: LedgerReplayReport = { pathsWitnessed: 0, pathsSeen: 0, unitsReplayed: 0 }
+
+/**
+ * Distinct paths one seeding will canonicalize before it replays anything.
+ *
+ * A ceiling rather than a budget because the work is uniform: each path is a
+ * handful of `realpath` calls, once per conversation. Counted on distinct
+ * SPELLINGS, the ones only `read` names included — a read has to be keyed too
+ * or it cannot contradict a claim — so two spellings of one file count twice.
+ * A history naming more paths than this is not a conversation whose ledger is
+ * worth guessing at, and it seeds nothing rather than resolving a prefix and
+ * abandoning the rest — a partially keyed walk is a walk that cannot say what
+ * a mutation replaced. That is a total loss for the conversation, not a partial
+ * one: it starts from the empty ledger a resume has always started from, and
+ * its first mutation of each path re-establishes it.
+ */
+export const MAX_RESOLVED_PATHS = 1024
+
+/** What a caller needs to key a path the way its tools will. */
+export interface ObservationSeedContext {
+	readonly workingDirectory: string
+	/** See `ToolContext.additionalDirectories`; part of the tools' resolution. */
+	readonly additionalDirectories?: readonly string[]
+	/** True when this run's tools address a sandbox, whose keys are paths as written. */
+	readonly sandboxed?: boolean
+}
+
+/**
+ * Rebuild `tracker` from a conversation's own `messages`.
+ *
+ * For a host that keeps one tracker per conversation and has just restored one:
+ * the ledger is process memory, so a resumed conversation starts with nothing
+ * in it and re-reads files whose whole body is already in the transcript. Call
+ * it once, before the conversation's first request. Reading files is confined
+ * to canonicalizing the paths in the history; no file's CONTENT is read, and
+ * every body restored is one the visible calls reconstruct exactly.
+ *
+ * Content-backed observations, and only those. A path the walk cannot rebuild
+ * is left out of the ledger rather than entered without a fingerprint, so
+ * `write`'s read-before-overwrite refusal stands over it exactly as it does
+ * against the empty ledger a resume gets today. Three things seed nothing at
+ * all, and the report says so: a history naming more than
+ * {@link MAX_RESOLVED_PATHS} distinct path spellings, one whose ids are
+ * ambiguous, and one holding a mutation no path can be recovered from —
+ * whatever the transcript says came back to that mutation, since a key is what
+ * withdrawing one path rather than the whole pass takes. A call whose arguments
+ * are too long to read as JSON at all is one of that last kind; the replay
+ * states the ceiling.
+ */
+export async function seedObservationLedger(
+	messages: readonly Message[],
+	tracker: FileReadTracker,
+	context: ObservationSeedContext,
+): Promise<LedgerReplayReport> {
+	// One attribution cache across both halves. The path collection and the
+	// walk ask the same question of the same calls — which file did this touch
+	// — and answering it means reading a string that, for a `write`, is a whole
+	// file body. Asking once per seeding rather than once per half is why the
+	// replay's own ceiling on that read can be as generous as it is.
+	const attributions = createPathAttributions()
+	const keyOf = await resolveObservedFileKeys(messages, context, attributions)
+	return keyOf ? replayObservationLedger(messages, tracker, keyOf, attributions) : NOTHING
+}
+
+/**
+ * The tools' key for every path this history names, or `undefined` when the
+ * pass should not run at all.
+ *
+ * `undefined` for a history with nothing to reconstruct and for one past the
+ * ceiling. A path the resolver refuses — it escapes the roots this run may
+ * reach, or the working directory itself is gone — is simply left unkeyed;
+ * the replay then treats the mutation that named it as unattributable, which
+ * is the fail-closed answer and the same one it gives a call it cannot parse.
+ */
+async function resolveObservedFileKeys(
+	messages: readonly Message[],
+	context: ObservationSeedContext,
+	attributions: PathAttributions,
+): Promise<FileKeyResolver | undefined> {
+	const paths = collectObservedPaths(messages, attributions)
+	if (paths.length === 0 || paths.length > MAX_RESOLVED_PATHS) return undefined
+	// A sandbox has its own root and its own resolver, and the tools key on the
+	// path as written there. Canonicalizing it against the host filesystem would
+	// ask about the wrong machine.
+	if (context.sandboxed) return (path: string) => path
+	const roots = toolRoots(context)
+	const keys = new Map<string, string>()
+	for (const path of paths) {
+		try {
+			keys.set(path, await resolveWithinAnyReal(roots, path))
+		} catch {
+			// Left unkeyed on purpose; see above.
+		}
+	}
+	return (path: string) => keys.get(path)
+}

package/src/runtime/query/index.ts

@@ -112,6 +112,7 @@ import { toErrorMessage } from '../../utils/error.js'
 import { generateCheckpointId, generateRunId } from '../../utils/id.js'
 import { errorAttributes } from '../../utils/log/exception.js'
 import type { Logger } from '../../utils/logger.js'
+import { AwaitedJobs } from '../jobs/awaited-jobs.js'
 import type { BackgroundJobRegistry } from '../jobs/registry.js'
 import { AUTO_APPROVE_POLICY_NAME, createRunApprovalPolicy } from './approval-policy.js'
 import { CheckpointManager } from './checkpoint.js'
@@ -1034,6 +1035,56 @@ function withoutOwnedResumeTurn(
 	)
 }
 
+/**
+ * The history plus the part of the owned resume turn that already RAN, for the
+ * observation ledger to be seeded from.
+ *
+ * `withoutOwnedResumeTurn` takes that turn out so generic repair cannot answer
+ * it, and the plan re-appends it much later — after the sandbox exists, after
+ * the input guardrails, immediately before the loop. Seeding from the list the
+ * model finally sees would therefore have to happen after `applyPendingResume`,
+ * and that is the wrong seam for a reason that is not about ordering: the plan
+ * does not merely re-append the turn, it EXECUTES the calls in it that never
+ * started. Those tools read the ledger this seeding builds, so a seed placed
+ * after them would refuse the very write the resume exists to carry out — no
+ * `hasRead` for a file the conversation had read three turns earlier.
+ *
+ * So the turn is folded in here instead, and only as far as it actually got.
+ * A call `recoverCompletedCalls` found an outcome for is one that ran: its
+ * receipt goes in beside it, and the walk reads it exactly as it reads any
+ * other — a completed `write` restores the body it put there, and the
+ * unknown-outcome result the recovery writes for an interrupted one withdraws
+ * the path instead. A call ABSENT from that map is absent because a complete
+ * scan proved it has no recorded start, so the file it names is untouched and
+ * the claim history established for it still stands; leaving it out is what
+ * lets it execute in a moment. Without any of this the seed never saw the
+ * turn at all, and an executed write inside it left the pre-write body standing
+ * as a claim until the next mutation's drift check happened to catch it.
+ */
+function withOwnedResumeOutcomes(
+	messages: readonly Message[],
+	assistant: AssistantMessage,
+	recovered: ReadonlyMap<string, { result: string; isError: boolean }>,
+): Message[] {
+	const ran = (assistant.toolCalls ?? []).flatMap((call) => {
+		const outcome = recovered.get(call.id)
+		return outcome ? [{ call, outcome }] : []
+	})
+	if (ran.length === 0) return [...messages]
+	return [
+		...messages,
+		{ ...assistant, toolCalls: ran.map(({ call }) => call) },
+		...ran.map(
+			({ call, outcome }): Message => ({
+				role: 'tool',
+				toolCallId: call.id,
+				content: outcome.result,
+				isError: outcome.isError,
+			}),
+		),
+	]
+}
+
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
 	assertMaxToolCalls(params.maxToolCalls)
 	// Required types do not protect JavaScript callers. Reject missing scope
@@ -1734,6 +1785,23 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		return source
 	}
 
+	// Whose jobs this run speaks for: its own by default, the session's when
+	// the host said so. Resolved before the tools are built, because the
+	// wait-intent recorder below is bound into them.
+	const jobOwner = params.backgroundJobOwner ?? ctx.runId
+	// What the model reads when a job ends. Built up here, ahead of the
+	// subscription that fills it below, because the wait-intent recorder needs
+	// to ask whether its text has been read yet.
+	const jobNotices = params.backgroundJobs ? new SteeringBinding() : undefined
+	// Jobs the model told `wait_for_job` it is waiting on, which is the only
+	// thing that can hold this run open for a job. Built only where there is a
+	// registry, so a host with no background mode carries no recorder and the
+	// bound ref has no `markAwaited` to offer.
+	const awaitedJobs = params.backgroundJobs
+		? new AwaitedJobs(params.backgroundJobs, jobOwner, () => jobNotices?.pending ?? false)
+		: undefined
+	awaitedJobs?.attach()
+
 	const toolExecutor = ToolingBootstrap.init(
 		{
 			tools: params.tools,
@@ -1750,6 +1818,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			pluginManager: params.pluginManager,
 			...(params.backgroundJobs ? { backgroundJobs: params.backgroundJobs } : {}),
 			...(params.backgroundJobOwner ? { backgroundJobOwner: params.backgroundJobOwner } : {}),
+			...(awaitedJobs ? { onJobAwaited: (id: string) => awaitedJobs.expect(id) } : {}),
 			// The `skill` tool's registry. Threaded from the run rather than
 			// held by the tool, because a tool that reached for a module-level
 			// registry would answer about whatever the last run configured.
@@ -1809,8 +1878,6 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// result, and the host as an event — without either polling. Subscribed
 	// for the owner the run's jobs are bound to, so a session-owned job that
 	// ends during this run is reported here too.
-	const jobOwner = params.backgroundJobOwner ?? ctx.runId
-	const jobNotices = params.backgroundJobs ? new SteeringBinding() : undefined
 	const unsubscribeJobExits = params.backgroundJobs?.onExit((job) => {
 		if (job.owner !== jobOwner) return
 		const outcome =
@@ -2010,6 +2077,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		promptContributions,
 		...(params.steering ? { steering: params.steering } : {}),
 		...(jobNotices ? { jobNotices } : {}),
+		...(awaitedJobs ? { awaitedJobs } : {}),
 		checkpointMgr,
 		planManager: ctx.planManager,
 		taskGateway: taskScheduler,
@@ -2368,6 +2436,37 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					})
 				}
 
+				// The ledger is process state and a resumed run starts with an empty
+				// one, so until something reads a file again this run knows nothing
+				// about files the conversation already wrote in full — and re-reads
+				// them. Rebuilt from the REPAIRED history, which is what the model
+				// is about to be shown, rather than from the checkpoint's own
+				// messages — plus whatever of the owned resume turn actually ran,
+				// which the repaired list does not carry; see
+				// `withOwnedResumeOutcomes`. Reads no file's content: every
+				// fingerprint recovered here is still checked against the real one
+				// at mutation time.
+				try {
+					await toolExecutor.seedFileObservations(
+						pendingResume
+							? withOwnedResumeOutcomes(restoredMessages, pendingResume.assistant, recoveredResults)
+							: restoredMessages,
+						params.sandboxProvider !== undefined,
+					)
+				} catch (err: unknown) {
+					// A ledger that could not be rebuilt is the empty one every resume
+					// used to get, so the run continues without its witnesses and the
+					// model reads what it needs. Failing the resume over it would trade
+					// a conversation that works for one that does not, to protect an
+					// optimisation. Said out loud all the same, because a seeding that
+					// failed and one that found nothing are otherwise the same silence.
+					ctx.log.debug('Could not rebuild the file observation ledger on resume', {
+						[NAMZU.RUN_ID]: ctx.runMgr.id,
+						'namzu.checkpoint.id': checkpoint.id,
+						'exception.message': err instanceof Error ? err.message : String(err),
+					})
+				}
+
 				for (const msg of restoredMessages) {
 					if (msg.role === 'system') {
 						// Re-push the FRESH static/dynamic floor (done above) but PRESERVE
@@ -2878,6 +2977,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// Awaited, and its failure swallowed. A job that would not die is
 			// worth a log line, and is not worth retracting a run's answer.
 			unsubscribeJobExits?.()
+			// The wait-intent recorder listens on the same shared registry and
+			// leaks the same way if it is left attached.
+			awaitedJobs?.close()
 			// Only jobs bound to this run. Jobs a host bound to its session are
 			// the host's to stop, when the session ends.
 			if (params.backgroundJobs && (params.backgroundJobOwner ?? ctx.runId) === ctx.runId) {

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

@@ -51,6 +51,7 @@ 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'
@@ -69,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'
@@ -181,6 +182,44 @@ 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:
@@ -1537,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
@@ -1547,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
@@ -1782,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.
@@ -1816,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) {
@@ -1827,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,
@@ -1846,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
@@ -1871,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)
+		}
+
+		// 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 delegated work still running', {
+		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 {
@@ -1918,6 +2055,43 @@ export class IterationOrchestrator {
 		)
 	}
 
+	/**
+	 * The job half of {@link deliverArrivedCompletions}: an exit that arrived
+	 * too late to earn a turn is still delivered on the way out.
+	 *
+	 * 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.
+	 */
+	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}`,

package/src/runtime/query/iteration/phases/context.ts

@@ -35,6 +35,7 @@ import type { StructuredOutputConfig } from '../../../../types/structured-output
 import type { TaskStore } from '../../../../types/task/index.js'
 import type { ToolRegistryContract } from '../../../../types/tool/index.js'
 import type { Logger } from '../../../../utils/logger.js'
+import type { AwaitedJobs } from '../../../jobs/awaited-jobs.js'
 import type { CheckpointManager } from '../../checkpoint.js'
 import type { EmitEvent } from '../../events.js'
 import type { ToolExecutor } from '../../executor.js'
@@ -136,6 +137,15 @@ export interface IterationContext {
 	readonly onSteeringDelivered?: (text: string) => void
 	/** Exit notices for the run's background jobs, drained into the next tool result. */
 	readonly jobNotices?: SteeringChannel
+	/**
+	 * Background jobs the model said it is waiting on, which is the only kind
+	 * the loop holds a finishing run open for.
+	 *
+	 * Absent means the loop behaves exactly as it did before this existed: a
+	 * job's exit still reaches the model as a notice on the next tool result,
+	 * and a run whose model stopped calling tools settles without waiting.
+	 */
+	readonly awaitedJobs?: AwaitedJobs
 	readonly checkpointMgr: CheckpointManager
 	readonly planManager: PlanManager
 

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -150,6 +150,10 @@ export async function* runToolReview(
 				attachSteering(batch.messages, ctx.steering, ctx.onSteeringDelivered),
 				ctx.jobNotices,
 				formatJobNote,
+				// The exits that text accounts for have now been read, so the
+				// record of them stops being pending work. Left standing, it
+				// buys the model a turn the next time any job queues a notice.
+				() => ctx.awaitedJobs?.noticesDelivered(),
 			),
 			notices,
 		)) {