@namzu/sdk 34.2.0 → 36.0.0

package/src/runtime/query/index.ts

@@ -8,6 +8,7 @@ import {
 } from '../../advisory/index.js'
 import { drainQueuedMessages } from '../../agents/handle.js'
 import { AuthorizationGate } from '../../authorization/gate.js'
+import { consolidationEntry } from '../../compaction/consolidation.js'
 import {
 	type ToolHistoryRepairReport,
 	repairToolMessageHistory,
@@ -18,12 +19,12 @@ import { WorkingStateManager } from '../../compaction/manager.js'
 import type { ContextReducer } from '../../compaction/reducer.js'
 import { serializeState as serializeWorkingState } from '../../compaction/serializer.js'
 import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire.js'
-import type { CompactionConfig } from '../../config/runtime.js'
-import { BOOT_EVENT_NAMES } from '../../constants/telemetry/index.js'
+import { type CompactionConfig, CompactionConfigSchema } from '../../config/runtime.js'
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
 import { EmergencySaveManager } from '../../manager/run/emergency.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
 import { resolveModelPricing } from '../../pricing/index.js'
+import { PromptContributionRegistry } from '../../prompt/contributions.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
 import { isCallerAbortError } from '../../provider/errors.js'
 import {
@@ -33,7 +34,8 @@ import {
 } from '../../provider/fallback.js'
 import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../../provider/idle-timeout.js'
 import { type ProviderRetryConfig, withProviderRetry } from '../../provider/retry.js'
-import { DefaultFilesystemMigrator, loggingMigrationSink } from '../../session/migration/index.js'
+import { withTokenBudget } from '../../provider/token-budget.js'
+import type { TokenBudget } from '../../run/token-budget.js'
 import type { PathBuilder } from '../../session/workspace/path-builder.js'
 import { resolveAttachments } from '../../store/attachment/index.js'
 import {
@@ -61,13 +63,13 @@ import type { AuthorizationGateConfig } from '../../types/authorization/index.js
 import { NamzuError } from '../../types/errors/index.js'
 import type { InputGuardrailSpec, OutputGuardrailSpec } from '../../types/guardrail/index.js'
 import {
-	type CheckpointId,
 	type HITLResumeDecision,
 	type ResumeHandler,
 	autoApproveHandler,
 } from '../../types/hitl/index.js'
-import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
+import type { CheckpointId, PlanId, RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
+import type { MemoryStore } from '../../types/memory/index.js'
 import {
 	type AssistantMessage,
 	type Message,
@@ -96,6 +98,7 @@ import type { PromoteMemory } from '../../types/run/memory-promotion.js'
 import { memoryCandidateFor } from '../../types/run/memory-promotion.js'
 import type { RunState } from '../../types/run/state.js'
 import type { RunStore } from '../../types/run/store.js'
+import type { TokenBudgetStore } from '../../types/run/token-budget-store.js'
 import type { Sandbox, SandboxProvider } from '../../types/sandbox/index.js'
 import type { ProjectId, TopicId } from '../../types/session/ids.js'
 import type { Skill } from '../../types/skills/index.js'
@@ -106,9 +109,8 @@ import type { RepairToolCall } from '../../types/tool/repair.js'
 import type { BackoffPolicy } from '../../utils/backoff.js'
 import type { ModelPricing } from '../../utils/cost.js'
 import { toErrorMessage } from '../../utils/error.js'
-import { generateRunId } from '../../utils/id.js'
+import { generateCheckpointId, generateRunId } from '../../utils/id.js'
 import { errorAttributes } from '../../utils/log/exception.js'
-import { EVENT_NAME_ATTRIBUTE } from '../../utils/log/types.js'
 import type { Logger } from '../../utils/logger.js'
 import type { BackgroundJobRegistry } from '../jobs/registry.js'
 import { AUTO_APPROVE_POLICY_NAME, createRunApprovalPolicy } from './approval-policy.js'
@@ -147,12 +149,17 @@ import {
 	resolveSandboxTeardownTimeoutMs,
 	teardownSandbox,
 } from './sandbox-lifecycle.js'
-import type { SteeringChannel } from './steering.js'
+import { SteeringBinding, type SteeringChannel } from './steering.js'
+import { resolveQueryBudget } from './token-budget.js'
 import { ToolGrantSet } from './tool-grants.js'
 import { createToolPause } from './tool-pause.js'
 import { ToolingBootstrap } from './tooling.js'
 
 export interface QueryParams {
+	/** One account shared with the task scheduler and descendant runs. */
+	budget?: TokenBudget
+	/** Canonical tree ledger; defaults to disk beside the root run. */
+	tokenBudgetStore?: TokenBudgetStore
 	/**
 	 * Notice when the model issues the identical tool call repeatedly, and
 	 * say so on the next `tool_result`. Defaults on.
@@ -274,6 +281,16 @@ export interface QueryParams {
 	 * background execution is refused rather than silently bypassing the sandbox.
 	 */
 	backgroundJobs?: BackgroundJobRegistry
+	/**
+	 * Which owner the run's background jobs belong to. Absent, the run id:
+	 * jobs are stopped when the run ends. A host that wants a job to
+	 * outlive the turn that started it — a dev server started in one turn
+	 * and read in the next — passes its session id here and calls
+	 * `backgroundJobs.killOwner(sessionId)` when the session ends; the run
+	 * then stops nothing at its end and still tells the model when a job
+	 * finishes.
+	 */
+	backgroundJobOwner?: string
 
 	/**
 	 * What else goes in this run's prompt.
@@ -469,6 +486,12 @@ export interface QueryParams {
 	agentId: string
 	agentName: string
 	workingDirectory?: string
+	/**
+	 * Directories besides the working directory the file tools may reach,
+	 * absolute; a sandboxed run binds each read-write. See
+	 * `ToolContext.additionalDirectories`.
+	 */
+	additionalDirectories?: readonly string[]
 	pricing?: ModelPricing
 	enableActivityTracking?: boolean
 	messages: Message[]
@@ -648,6 +671,13 @@ export interface QueryParams {
 	 * started. See `BaseAgentConfig.inboundMessages` for what it closes.
 	 */
 	inboundMessages?: () => import('../../types/message/index.js').Message[]
+	/**
+	 * Wake a background-task hold when operator input is available, without draining it.
+	 * Resolve immediately if input is already pending. Otherwise wait for its arrival;
+	 * the supplied signal ends the wait and must release any listeners. Messages are
+	 * still consumed only through `inboundMessages` at a provider-valid boundary.
+	 */
+	waitForInbound?: (signal: AbortSignal) => Promise<void>
 
 	/**
 	 * Live project policy for this run. Unlike `inboundMessages`, snapshot
@@ -715,6 +745,15 @@ export interface QueryParams {
 
 	compactionConfig?: CompactionConfig
 
+	/**
+	 * Where what the run learned is written when it ends: its decisions,
+	 * discoveries and failures, as one entry tagged `learning`. Episodic
+	 * memory (the working state) dies with the run; this is the bridge to
+	 * the semantic store a later run searches. Absent means nothing is
+	 * written. A store that fails is logged and never fails the run.
+	 */
+	consolidateInto?: MemoryStore
+
 	/**
 	 * Optional neutral working-memory seam. When set, the iteration loop
 	 * re-renders the provider's string into a single pinned leading system
@@ -1022,6 +1061,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// generating it twice would silently hand the log and the run two
 	// different ids.
 	const runId = params.runId ?? generateRunId()
+	const budget = await resolveQueryBudget(params, runId, selectedResumeState)
 	const log = RunContextFactory.buildLogger({
 		agentName: params.agentName,
 		runConfig,
@@ -1033,44 +1073,6 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		tenantId: params.tenantId,
 	})
 
-	// Boot-time filesystem migration (session-hierarchy.md §13.4.1). First
-	// call per process per root actually runs; subsequent calls short-circuit
-	// via the in-memory guard in `context.ts`. Kept here rather than inside
-	// the synchronous `RunContextFactory.build` so the factory signature stays
-	// sync for tests / non-async call sites.
-	//
-	// The migrator built here — not `ensureMigrated`'s own default — is what
-	// turns the migration facts `DefaultFilesystemMigrator` already computes
-	// into a `namzu.migration.completed` record instead of discarding them.
-	// `ensureMigrated`'s default parameter stays
-	// `NOOP_FILESYSTEM_MIGRATION_SINK` (see `context.ts`), so any other path
-	// that reaches `ensureMigrated` keeps today's silent behaviour.
-	const cwdForMigration = params.workingDirectory ?? process.cwd()
-	const migrationRoot = params.pathBuilder?.rootDir() ?? join(cwdForMigration, '.namzu')
-	const migrationResult = await RunContextFactory.ensureMigrated(
-		migrationRoot,
-		new DefaultFilesystemMigrator(loggingMigrationSink(log)),
-	)
-	// `loggingMigrationSink` only ever hears about `kind: 'migrated'` — the
-	// only outcome `DefaultFilesystemMigrator` ever hands its sink (see the
-	// module doc on `FilesystemMigrationSink`). The other two are logged
-	// here, straight off the resolved result, rather than by widening
-	// `FilesystemMigrationEvent` to carry them: a wider union would need a
-	// new arm in every exhaustive switch already written over it — a major —
-	// for two outcomes `migrationResult.kind` already fully describes.
-	if (migrationResult.kind !== 'migrated') {
-		log.debug('filesystem migration: nothing to do', {
-			[EVENT_NAME_ATTRIBUTE]: BOOT_EVENT_NAMES.MIGRATION_COMPLETED,
-			// `namzu.migration.*`, matching `loggingMigrationSink` — the OTHER
-			// emitter of this same event name. Two emitters of one event writing
-			// two namespaces for the same fact is precisely the collision the
-			// namespaced-key rule exists to stop, and a per-module derivation is
-			// how it would be reintroduced.
-			'namzu.migration.kind': migrationResult.kind,
-			'namzu.migration.marker_path': migrationResult.markerPath,
-		})
-	}
-
 	// Every model call in the run — the loop's turns, the forced-final
 	// summary, advisory and compaction side calls — goes through this one
 	// wrapped provider, so the retry policy cannot be bypassed by a code
@@ -1102,9 +1104,14 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			idleTimeoutMs: streamIdleTimeoutMs,
 			log,
 		})
+		const metered = withTokenBudget(withIdleBound, budget)
 		return params.retry === false
-			? withIdleBound
-			: withProviderRetry(withIdleBound, { config: params.retry, log })
+			? metered
+			: withProviderRetry(metered, {
+					config: params.retry,
+					log,
+					canRetry: () => budget.remaining > 0,
+				})
 	}
 	// Who is serving right now, for the run RECORD rather than for the request.
 	//
@@ -1123,6 +1130,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		})),
 		{
 			log,
+			canFallback: () => budget.remaining > 0,
 			onSwap: (to) => {
 				serving.current = to
 				// `ctx` is declared below and is initialized before anything can
@@ -1278,6 +1286,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	}
 
 	const ctx = RunContextFactory.build({
+		budget,
 		...(topicState ? { topicPermissionMode: topicState.permissionMode } : {}),
 		...(params.permissionModeRef ? { permissionModeRef: params.permissionModeRef } : {}),
 		agentId: params.agentId,
@@ -1329,13 +1338,19 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		emit: (event) => eventTranslator.emitEvent(event),
 	})
 
+	const planApprovalIds = new Map<PlanId, CheckpointId>()
 	ctx.planManager.setApprovalHandler(async (request) => {
+		let checkpointId = planApprovalIds.get(request.planId)
+		if (!checkpointId) {
+			checkpointId = generateCheckpointId()
+			planApprovalIds.set(request.planId, checkpointId)
+		}
 		// `.current.handler`, never a captured `params.resumeHandler`. That
 		// capture is what made changing the policy mean ending the run.
 		const decision = await approvalPolicy.current.handler({
 			type: 'plan_approval',
 			runId: ctx.runId,
-			checkpointId: `cp_plan_${request.planId}` as import('../../types/ids/index.js').CheckpointId,
+			checkpointId,
 			plan: {
 				planId: request.planId,
 				title: request.title,
@@ -1683,6 +1698,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			tools: params.tools,
 			runId: ctx.runId,
 			workingDirectory: ctx.cwd,
+			...(params.additionalDirectories?.length
+				? { additionalDirectories: params.additionalDirectories }
+				: {}),
 			permissionMode: () => ctx.permissionMode.current,
 			env: runConfig.env ?? {},
 			abortSignal: ctx.abortController.signal,
@@ -1690,6 +1708,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			invocationState: params.invocationState,
 			pluginManager: params.pluginManager,
 			...(params.backgroundJobs ? { backgroundJobs: params.backgroundJobs } : {}),
+			...(params.backgroundJobOwner ? { backgroundJobOwner: params.backgroundJobOwner } : {}),
 			// 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.
@@ -1734,12 +1753,52 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		ctx.log,
 	)
 
+	// A background job's exit reaches the model as a notice on its next tool
+	// 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 =
+			job.status === 'killed'
+				? 'was stopped'
+				: `exited with code ${job.exitCode ?? 'unknown'}${job.signal ? ` (${job.signal})` : ''}`
+		jobNotices?.steer(
+			`Background job ${job.id} (${job.command}) ${outcome}. Read its output with the job tool if you need it.`,
+		)
+		void eventTranslator
+			.emitEvent({
+				type: 'background_job_exited',
+				runId: ctx.runId,
+				jobId: job.id,
+				command: job.command,
+				status: job.status === 'killed' ? 'killed' : 'exited',
+				...(job.exitCode !== undefined ? { exitCode: job.exitCode } : {}),
+				...(job.signal ? { signal: job.signal } : {}),
+			})
+			.catch(() => {})
+	})
 	let workingStateManager: WorkingStateManager | undefined
-	if (params.compactionConfig && params.compactionConfig.strategy !== 'disabled') {
-		workingStateManager = new WorkingStateManager(params.compactionConfig)
+	// Normalised once, defaults applied. A host that passes a partial
+	// object — a strategy and a window, nothing else — used to reach the
+	// phase with `triggerThreshold` undefined, and `usage < undefined` is
+	// false: the pass ran on every iteration and the salience strategy fell
+	// through to the stale-result clearing it exists to replace. The eval
+	// suite that passed exactly that object found it.
+	const compactionConfig = params.compactionConfig
+		? CompactionConfigSchema.parse(params.compactionConfig)
+		: undefined
+	if (compactionConfig && compactionConfig.strategy !== 'disabled') {
+		workingStateManager = new WorkingStateManager(compactionConfig)
 		toolExecutor.setWorkingStateManager(workingStateManager)
 	}
 
+	// The run's own registry when the host passed none, so a hook's
+	// annotation has somewhere to land.
+	const promptContributions = params.promptContributions ?? new PromptContributionRegistry()
+
 	const promptBuilder = new PromptBuilder({
 		systemPrompt: params.systemPrompt,
 		persona: params.persona,
@@ -1748,7 +1807,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		tools: params.tools,
 		allowedTools: effectiveAllowedTools,
 		runtimeContext: params.runtimeContext,
-		...(params.promptContributions ? { contributions: params.promptContributions } : {}),
+		contributions: promptContributions,
 	})
 
 	const guard = new GuardCoordinator({
@@ -1800,10 +1859,13 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// explicitly chosen provider/cancellation policy.
 		const boundedAdvisors = params.advisory.advisors.map((advisor) => ({
 			...advisor,
-			provider: withStreamIdleTimeout(advisor.provider, {
-				idleTimeoutMs: streamIdleTimeoutMs,
-				log: ctx.log,
-			}),
+			provider: withTokenBudget(
+				withStreamIdleTimeout(advisor.provider, {
+					idleTimeoutMs: streamIdleTimeoutMs,
+					log: ctx.log,
+				}),
+				budget,
+			),
 		}))
 		const advisorRegistry = new AdvisorRegistry(boundedAdvisors, params.advisory.defaultAdvisorId)
 		// A budget the runtime cannot measure is refused here rather than
@@ -1891,8 +1953,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// question rather than the next run.
 		resumeHandler: (request) => approvalPolicy.current.handler(request),
 		takeApprovalPolicyChange: () => approvalPolicy.takeUnannouncedChange(),
-		...(params.promptContributions ? { promptContributions: params.promptContributions } : {}),
+		promptContributions,
 		...(params.steering ? { steering: params.steering } : {}),
+		...(jobNotices ? { jobNotices } : {}),
 		checkpointMgr,
 		planManager: ctx.planManager,
 		taskGateway: taskScheduler,
@@ -1905,8 +1968,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// run is a claim about work nobody repeated, and a module-level map
 		// would leak exactly that way.
 		...(params.repeatCallAdvisory === false ? {} : { repeatCalls: new RepeatCallTracker() }),
-		compactionConfig: params.compactionConfig,
+		compactionConfig,
 		...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
+		...(params.waitForInbound ? { waitForInbound: params.waitForInbound } : {}),
 		...(params.projectInstructionContext
 			? { projectInstructionContext: params.projectInstructionContext }
 			: {}),
@@ -2069,6 +2133,32 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				'namzu.runtime.resume_from_checkpoint': params.resumeFromCheckpoint ?? null,
 			})
 
+			// The operator's prompt, before the model sees it. A hook may
+			// refuse it — the run ends here, before a prompt is built — or add
+			// to what the model is told; the addition rides the prompt as a
+			// dynamic contribution so every iteration of the run carries it.
+			if (params.pluginManager) {
+				const hookResults = await params.pluginManager.executeHooks(
+					'user_prompt_submit',
+					{
+						runId: ctx.runId,
+						sessionId: params.sessionId,
+						prompt: lastUserPrompt(initialMessages),
+						signal: ctx.abortController.signal,
+					},
+					eventTranslator.emitEvent,
+				)
+				const annotations = applyLifecycleHookResults('user_prompt_submit', hookResults)
+				if (annotations.length > 0) {
+					promptContributions.replace({
+						id: 'hooks:user_prompt_submit',
+						placement: 'dynamic',
+						render: () => `Context from the operator's hooks:\n\n${annotations.join('\n\n')}`,
+					})
+				}
+				yield* eventTranslator.drainPending()
+			}
+
 			const contextLevel = params.contextLevel ?? 'full'
 			const cacheInput = {
 				systemPrompt: params.systemPrompt,
@@ -2078,7 +2168,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				tools: params.tools,
 				allowedTools: effectiveAllowedTools,
 				runtimeContext: params.runtimeContext,
-				...(params.promptContributions ? { contributions: params.promptContributions } : {}),
+				contributions: promptContributions,
 			}
 
 			const segments: PromptSegments = promptCache
@@ -2132,8 +2222,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				// would drop it and replace it with a summary covering only
 				// what happened after the resume, silently losing the run's
 				// first hour.
-				if (workingStateManager && checkpoint.workingState && params.compactionConfig) {
-					const revived = restoreWorkingState(checkpoint.workingState, params.compactionConfig)
+				if (workingStateManager && checkpoint.workingState && compactionConfig) {
+					const revived = restoreWorkingState(checkpoint.workingState, compactionConfig)
 					workingStateManager.replaceState(revived.getState())
 					ctx.log.info('Restored compaction working state from checkpoint', {
 						[NAMZU.RUN_ID]: ctx.runMgr.id,
@@ -2412,6 +2502,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					provider: params.sandboxProvider,
 					config: {
 						...(rootAtCwd ? { workingDirectory: ctx.cwd } : {}),
+						...(rootAtCwd && params.additionalDirectories?.length
+							? { additionalDirectories: params.additionalDirectories }
+							: {}),
 						timeoutMs: runConfig.sandbox?.timeoutMs,
 						memoryLimitMb: runConfig.sandbox?.memoryLimitMb,
 						maxProcesses: runConfig.sandbox?.maxProcesses,
@@ -2580,6 +2673,22 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				)
 				applyLifecycleHookResults('run_end', hookResults)
 				yield* eventTranslator.drainPending()
+				// A delegated run says so once more, by name, so a hook that
+				// only cares when a subagent finishes need not read parent ids
+				// off every run_end.
+				if (params.parentRunId !== undefined) {
+					const stopResults = await params.pluginManager.executeHooks(
+						'subagent_stop',
+						{
+							runId: ctx.runId,
+							parentRunId: params.parentRunId,
+							signal: ctx.abortController.signal,
+						},
+						eventTranslator.emitEvent,
+					)
+					applyLifecycleHookResults('subagent_stop', stopResults)
+					yield* eventTranslator.drainPending()
+				}
 			}
 
 			// Hand the step record to the run before it settles, so the
@@ -2638,6 +2747,32 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				}
 			}
 
+			if (params.consolidateInto && workingStateManager) {
+				const entry = consolidationEntry(workingStateManager.getState(), {
+					runId: ctx.runId,
+					at: Date.now(),
+				})
+				if (entry) {
+					try {
+						const { entry: saved } = await params.consolidateInto.create(entry)
+						await eventTranslator.emitEvent({
+							type: 'memory_consolidated',
+							runId: ctx.runId,
+							memoryId: saved.id,
+							title: entry.title,
+							decisions: workingStateManager.getState().decisions.length,
+							discoveries: workingStateManager.getState().discoveries.length,
+							failures: workingStateManager.getState().failures.length,
+						})
+						yield* eventTranslator.drainPending()
+					} catch (error) {
+						ctx.log.warn('consolidation into the memory store failed', {
+							[NAMZU.RUN_ID]: ctx.runId,
+							'namzu.memory.error': toErrorMessage(error),
+						})
+					}
+				}
+			}
 			yield* resultAssembler.completeRun(rootSpan)
 		} catch (err) {
 			// A failed run still spent its steps; report them.
@@ -2659,7 +2794,10 @@ 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.
-			if (params.backgroundJobs) {
+			unsubscribeJobExits?.()
+			// Only jobs bound to this run. Jobs a host bound to its session are
+			// the host's to stop, when the session ends.
+			if (params.backgroundJobs && (params.backgroundJobOwner ?? ctx.runId) === ctx.runId) {
 				try {
 					const stopped = await params.backgroundJobs.killOwner(ctx.runId)
 					if (stopped.length > 0) {
@@ -2743,6 +2881,15 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
  * either way — a stale cursor belongs to the client, and must not be able to
  * stop the work.
  */
+/** The text of the newest user turn, which is what a prompt hook is asked about. */
+function lastUserPrompt(messages: readonly Message[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i]
+		if (m?.role === 'user' && typeof m.content === 'string') return m.content
+	}
+	return ''
+}
+
 async function* catchUpFromCursor(
 	runMgr: RunPersistence,
 	cursor: RunEventCursor,

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

@@ -312,8 +312,9 @@ export class IterationOrchestrator {
 						'namzu.runtime.input_tokens': runMgr.tokenUsage.promptTokens,
 						'namzu.runtime.output_tokens': runMgr.tokenUsage.completionTokens,
 					})
-					await this.requestFinalResponse(model, stopReason)
-					yield* this.ctx.drainPending()
+					// A hard stop has no budget left for another model request.
+					// Closing prose is requested at the warning threshold while
+					// headroom remains; the completed work is already in history.
 					runMgr.setStopReason(stopReason)
 					break
 				}
@@ -788,6 +789,7 @@ export class IterationOrchestrator {
 						type: 'token_usage_updated',
 						runId: runMgr.id,
 						usage: runMgr.tokenUsage,
+						budget: runMgr.budget?.summary(),
 						cost: runMgr.costInfo,
 						...contextFigures,
 					})
@@ -1079,12 +1081,13 @@ export class IterationOrchestrator {
 							continue
 						}
 
+						let closingStopReason: StopReason | undefined
 						if (!hasContent && !forceFinalize) {
 							this.ctx.log.warn('Empty completion detected — requesting final summary', {
 								[NAMZU.ITERATION]: iterationNum,
 								'namzu.runtime.finish_reason': response.finishReason,
 							})
-							await this.requestFinalResponse(model, 'end_turn')
+							closingStopReason = await this.requestFinalResponse(model, 'end_turn')
 							yield* this.ctx.drainPending()
 						}
 
@@ -1115,7 +1118,10 @@ export class IterationOrchestrator {
 						// also settle as `end_turn`, and there the deferred predicate
 						// is not why the run ended: those decided the answer
 						// themselves.
-						runMgr.setStopReason(stopWasDeferredForOutstandingWork ? 'stop_condition' : 'end_turn')
+						runMgr.setStopReason(
+							closingStopReason ??
+								(stopWasDeferredForOutstandingWork ? 'stop_condition' : 'end_turn'),
+						)
 						break
 					}
 
@@ -1444,9 +1450,9 @@ export class IterationOrchestrator {
 	/**
 	 * Hold the run open for a worker that has not finished, and deliver it.
 	 *
-	 * Returns whether a completion arrived and was put in the transcript — the
-	 * caller continues the loop on `true`, so the model gets a turn in which to
-	 * USE the result. That turn is the entire justification for waiting, which
+	 * 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
 	 * is why only the exits that can still take one call this.
 	 *
 	 * Bounded by `settleGraceMs` and by `maxIterations`, so a worker that never
@@ -1467,14 +1473,34 @@ export class IterationOrchestrator {
 			[NAMZU.ITERATION]: iterationNum,
 			'namzu.runtime.grace_ms': graceMs,
 		})
-		await this.ctx.completionInbox.waitForArrival(graceMs)
+		// 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([
+				this.ctx.completionInbox.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) return false
-
-		this.ctx.runMgr.pushMessage(
-			createRuntimeContextMessage(formatCompletionNotification(arrived), 'task-completion'),
-		)
+		if (arrived.length > 0) {
+			this.ctx.runMgr.pushMessage(
+				createRuntimeContextMessage(formatCompletionNotification(arrived), 'task-completion'),
+			)
+		}
+		const inbound = this.deliverInbound()
+		if (arrived.length === 0 && inbound === 0) return false
 		await this.ctx.emitEvent({
 			type: 'iteration_completed',
 			runId: this.ctx.runMgr.id,
@@ -2029,7 +2055,10 @@ export class IterationOrchestrator {
 		})
 	}
 
-	private async requestFinalResponse(model: string, reason: StopReason): Promise<void> {
+	private async requestFinalResponse(
+		model: string,
+		reason: StopReason,
+	): Promise<StopReason | undefined> {
 		const lastAssistant = [...this.ctx.runMgr.messages]
 			.reverse()
 			.find((m) => m.role === 'assistant')
@@ -2040,8 +2069,16 @@ export class IterationOrchestrator {
 			lastAssistant.content.length > 0
 
 		if (hasResult) return
+		// An empty completion may itself have exhausted the run. This fallback
+		// is another billed request, so it must pass the same hard limits as
+		// the next normal iteration and preserve their unfinished stop reason.
+		const guardResult = this.ctx.guard.beforeIteration(
+			this.ctx.runMgr,
+			this.ctx.abortController.signal,
+		)
+		if (guardResult.shouldStop) return guardResult.stopReason
 
-		this.ctx.log.info('Requesting final response before limit enforcement', {
+		this.ctx.log.info('Requesting final response after empty completion', {
 			'namzu.runtime.reason': reason,
 		})
 
@@ -2145,6 +2182,7 @@ export class IterationOrchestrator {
 				'exception.message': toErrorMessage(err),
 			})
 		}
+		return undefined
 	}
 }