@namzu/sdk 1.0.0 → 1.1.0

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

@@ -9,6 +9,8 @@ import { collect } from '../../../provider/collect.js'
 import type { ActivityStore } from '../../../store/activity/memory.js'
 import { GENAI, NAMZU, agentIterationSpanName } from '../../../telemetry/attributes.js'
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
+import type { WorkingMemoryProvider } from '../../../types/agent/working-memory.js'
+import { mergeTokenUsage } from '../../../types/common/index.js'
 import type { ResumeHandler } from '../../../types/hitl/index.js'
 import type { ToolUseId } from '../../../types/ids/index.js'
 import { createAssistantMessage, createUserMessage } from '../../../types/message/index.js'
@@ -35,6 +37,7 @@ import { runCompactionCheck } from './phases/compaction.js'
 import type { IterationContext } from './phases/index.js'
 import { runPlanGate } from './phases/plan.js'
 import { runToolReview } from './phases/tool-review.js'
+import { refreshWorkingMemory } from './phases/working-memory.js'
 
 export type { IterationContext } from './phases/index.js'
 export type { PhaseSignal } from './phases/index.js'
@@ -53,6 +56,7 @@ export interface IterationConfig {
 	>
 	compactionConfig?: CompactionConfig
 	workingStateManager?: WorkingStateManager
+	workingMemoryProvider?: WorkingMemoryProvider
 	advisoryCtx?: AdvisoryContext
 	agentBus?: import('../../../bus/index.js').AgentBus
 	verificationGate?: import('../../../verification/gate.js').VerificationGate
@@ -192,8 +196,35 @@ async function* streamProviderTurn(
 
 	const stream = provider.chatStream({ ...params, stream: true }) as AsyncIterable<StreamChunk>
 
+	// Drive the stream manually so each `.next()` can be RACED against the run
+	// abort: a Stop tears the in-flight model request down (the provider got
+	// `params.signal`), and we ALSO stop pulling within a tick even if a
+	// transport buffers or ignores the signal. The abort rejection propagates
+	// out of this generator so the run loop settles the turn as cancelled.
+	// `{ once: true }` keeps a multi-iteration run from leaking a listener/turn.
+	const it = stream[Symbol.asyncIterator]()
+	const signal = params.signal
+	let onAbort: (() => void) | undefined
+	const aborted: Promise<never> | undefined = signal
+		? new Promise<never>((_resolve, reject) => {
+				if (signal.aborted) {
+					reject(signal.reason)
+					return
+				}
+				onAbort = () => reject(signal.reason)
+				signal.addEventListener('abort', onAbort, { once: true })
+			})
+		: undefined
+
 	try {
-		for await (const chunk of stream) {
+		for (;;) {
+			const next = it.next()
+			// Neutralize the dangling loser so an eventual rejection of the
+			// un-awaited `next` is never an unhandled rejection.
+			if (aborted) next.catch(() => {})
+			const res = await (aborted ? Promise.race([next, aborted]) : next)
+			if (res.done) break
+			const chunk = res.value
 			if (chunk.error) {
 				streamError = chunk.error
 				break
@@ -292,10 +323,24 @@ async function* streamProviderTurn(
 			}
 
 			if (chunk.finishReason) finishReason = chunk.finishReason
-			if (chunk.usage) usage = chunk.usage
+			// Merge (per-field max), not last-write-wins: a late usage frame that
+			// omits input/cache tokens must not zero the counts seen earlier in the
+			// stream, which would under-report this turn's accumulated usage.
+			if (chunk.usage) usage = mergeTokenUsage(usage, chunk.usage)
 		}
 	} catch (err) {
+		// An abort tears the turn down: propagate it so the run loop settles the
+		// run as cancelled rather than recording a normal (errored) turn. Any
+		// other stream error is captured into the synthesized response as before.
+		if (signal?.aborted) throw err
 		streamError = err instanceof Error ? err.message : String(err)
+	} finally {
+		if (onAbort) signal?.removeEventListener('abort', onAbort)
+		// Release the underlying connection on every exit (natural end, error,
+		// or abort). `for await` did this implicitly on natural completion; the
+		// manual drive must do it explicitly. `.return()` on an already-finished
+		// provider generator is a no-op.
+		await it.return?.().catch(() => {})
 	}
 
 	// Flush any tool buckets the provider failed to close (no toolCallEnd
@@ -470,6 +515,7 @@ export class IterationOrchestrator {
 			launchedTasks: config.launchedTasks ?? new Map(),
 			compactionConfig: config.compactionConfig,
 			workingStateManager: config.workingStateManager,
+			workingMemoryProvider: config.workingMemoryProvider,
 			advisoryCtx: config.advisoryCtx,
 			agentBus: config.agentBus,
 			verificationGate: config.verificationGate,
@@ -572,11 +618,19 @@ export class IterationOrchestrator {
 						await this.injectOneTaskNotification()
 					}
 
+					// Re-pin the working-memory block from ground truth at the primacy
+					// edge BEFORE compaction runs (so the refreshed slot is what
+					// compaction preserves). No-op when no provider is configured.
+					await refreshWorkingMemory(this.ctx)
 					await runCompactionCheck(this.ctx)
 
-					const openAITools = forceFinalize
-						? undefined
-						: this.ctx.tools.toLLMTools(this.ctx.allowedTools)
+					// Cache discipline: keep the tools param byte-stable even on the
+					// forced-final iteration and forbid tool use via tool_choice
+					// 'none' instead. Dropping the tools array would invalidate the
+					// entire prompt-cache prefix (tools render at position 0) and
+					// risks a 400 because the history still carries
+					// tool_use/tool_result blocks.
+					const openAITools = this.ctx.tools.toLLMTools(this.ctx.allowedTools)
 
 					const messages = forceFinalize
 						? [
@@ -610,10 +664,15 @@ export class IterationOrchestrator {
 						{
 							model,
 							messages,
-							tools: openAITools && openAITools.length > 0 ? openAITools : undefined,
+							tools: openAITools.length > 0 ? openAITools : undefined,
+							toolChoice: forceFinalize && openAITools.length > 0 ? 'none' : undefined,
 							temperature: runConfig.temperature,
 							maxTokens: runConfig.maxResponseTokens,
 							cacheControl: { type: 'auto' },
+							// Thread the run abort into the model call so a Stop tears the
+							// in-flight turn down (provider passes it to fetch; the consumer
+							// also races it). Inert when never aborted.
+							signal: this.ctx.abortController.signal,
 						},
 						this.ctx.emitEvent,
 						this.ctx.drainPending,
@@ -771,6 +830,16 @@ export class IterationOrchestrator {
 							hasToolCalls: false,
 						})
 						yield* this.ctx.drainPending()
+						// A Stop that lands AFTER the final turn streamed but before
+						// this break must settle the run as cancelled, not end_turn —
+						// otherwise the just-produced answer is recorded as a clean
+						// completion. Mirrors the between-iteration cancel at :511.
+						if (this.ctx.abortController.signal.aborted) {
+							runMgr.setStopReason('cancelled')
+							runMgr.markCancelled()
+							iterSpan.end()
+							break
+						}
 						runMgr.setStopReason('end_turn')
 						iterSpan.end()
 						break
@@ -815,6 +884,20 @@ export class IterationOrchestrator {
 					yield* this.ctx.drainPending()
 					iterSpan.end()
 				} catch (err) {
+					// A Stop that aborted the in-flight turn surfaces here as a
+					// thrown abort (the provider stream was raced against the run
+					// signal). Settle it as a CANCELLATION — mirroring the
+					// between-iteration cancel at the top of the loop — rather than
+					// recording it as an SDK failure (error span + failed activity)
+					// and re-throwing. The run then returns cleanly with a
+					// 'cancelled' stop reason instead of propagating an error.
+					if (this.ctx.abortController.signal.aborted) {
+						runMgr.setStopReason('cancelled')
+						runMgr.markCancelled()
+						iterSpan.end()
+						break
+					}
+
 					if (iterationActivity) {
 						this.ctx.activityStore.fail(iterationActivity.id, toErrorMessage(err))
 					}
@@ -948,13 +1031,22 @@ export class IterationOrchestrator {
 				),
 			]
 
+			// Same cache discipline as the forced-final iteration: keep the
+			// tools param identical to prior iterations (cache prefix intact,
+			// no 400 on tool blocks in history) and forbid use via tool_choice.
+			const finalTools = this.ctx.tools.toLLMTools(this.ctx.allowedTools)
 			const response = await collect(
 				this.ctx.provider.chatStream({
 					model,
 					messages: finalMessages,
+					tools: finalTools.length > 0 ? finalTools : undefined,
+					toolChoice: finalTools.length > 0 ? 'none' : undefined,
 					temperature: this.ctx.runConfig.temperature,
 					maxTokens: this.ctx.runConfig.maxResponseTokens,
 					cacheControl: { type: 'auto' },
+					// Cancellable too: a Stop during the closing summary must not
+					// stream to completion.
+					signal: this.ctx.abortController.signal,
 				}),
 			)
 

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

@@ -1,6 +1,11 @@
 import type { RunEvent } from '../../../../types/run/index.js'
 import { CheckpointManager } from '../../checkpoint.js'
-import { type IterationContext, type PhaseSignal, handleHITLDecision } from './context.js'
+import {
+	type IterationContext,
+	type PhaseSignal,
+	awaitDecisionOrAbort,
+	handleHITLDecision,
+} from './context.js'
 
 export async function* runIterationCheckpoint(
 	ctx: IterationContext,
@@ -17,7 +22,7 @@ export async function* runIterationCheckpoint(
 	yield* ctx.drainPending()
 
 	const summary = CheckpointManager.buildSummary(ctx.runMgr, iterationNum)
-	const iterDecision = await ctx.resumeHandler({
+	const iterDecision = await awaitDecisionOrAbort(ctx, {
 		type: 'iteration_checkpoint',
 		runId: ctx.runMgr.id,
 		checkpointId: iterCheckpoint.id,

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

@@ -1,12 +1,37 @@
+import { findSafeTrimIndex } from '../../../../compaction/dangling.js'
 import { serializeState } from '../../../../compaction/serializer.js'
 import { buildVerifiedSummary } from '../../../../compaction/verifier.js'
 import { CHARS_PER_TOKEN } from '../../../../constants/limits.js'
 import { createSystemMessage } from '../../../../types/message/index.js'
 import type { IterationContext } from './context.js'
+import { isWorkingMemoryMessage } from './working-memory.js'
 
 const COMPACTION_HEADER =
 	'[COMPACTED CONTEXT] The following is a structured summary of the conversation so far.'
 
+/**
+ * Identity check for a prior compaction summary in the leading floor. Used to
+ * REPLACE one in place on the per-iteration (contextWindowTokens) path so at
+ * most one `[COMPACTED CONTEXT]` block ever lives in the never-trimmed floor,
+ * and by the checkpoint-restore path to PRESERVE the summary across a resume
+ * (it is the only surviving record of the older history the run compacted away).
+ */
+export function isCompactionMessage(content: string | null | undefined): boolean {
+	return typeof content === 'string' && content.startsWith(COMPACTION_HEADER)
+}
+
+/**
+ * Minimum number of compactable (older) messages required before a compaction
+ * pass is worth running. When there is NOTHING between the never-trimmed
+ * leading floor and the recent window, a pass would only replace nothing with a
+ * `[COMPACTED CONTEXT]` summary that joins the floor — pure overhead that fires
+ * again next iteration (the permanent-floor thrash, ses_055 D7). Set to the
+ * literal EMPTY guard so any existing compaction consumer with ≥1 older message
+ * stays byte-identical; the per-iteration Vandal path additionally defangs the
+ * cost with `llmVerification:false`.
+ */
+const MIN_OLDER_MESSAGES_TO_COMPACT = 1
+
 function estimateTokens(ctx: IterationContext): number {
 	let chars = 0
 	for (const msg of ctx.runMgr.messages) {
@@ -31,7 +56,13 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 	if (!manager) return
 
 	const estimatedTokens = estimateTokens(ctx)
-	const budget = ctx.runConfig.tokenBudget
+	// F1: measure the CURRENT window against the model context window when the
+	// host supplies one, falling back to the run-level cumulative `tokenBudget`
+	// otherwise. Repointing the SINGLE `budget` assignment moves BOTH the
+	// `<= 0` guard AND the divisor at once — so "compaction on + tokenBudget=0"
+	// is no longer a silent no-op. Existing consumers (no contextWindowTokens)
+	// stay byte-identical.
+	const budget = config.contextWindowTokens ?? ctx.runConfig.tokenBudget
 	if (budget <= 0) return
 
 	const usage = estimatedTokens / budget
@@ -63,10 +94,34 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 	}
 	if (systemMessages.length === 0) return
 
-	const keepStart = messages.length - config.keepRecentMessages
+	// Tool-pair atomicity guard. A naive cut at `length - keepRecentMessages`
+	// can land BETWEEN an assistant-with-toolCalls (which would be dropped into
+	// `olderMessages`) and its `tool` results (kept in `recentMessages`),
+	// leaving orphaned `tool_result` blocks at the head of the recent window.
+	// The Anthropic provider then emits a `tool_result` with no matching
+	// `tool_use` and the API rejects the next turn with a 400 — so compaction,
+	// whose whole job is to keep a long run alive, instead kills it. Snap the
+	// boundary FORWARD to a safe point (existing `findSafeTrimIndex`, previously
+	// only wired to the unused ConversationManager strategy classes) so no pair
+	// is split. Any message this moves out of the recent window is already
+	// represented in the extracted WorkingState the summary is built from.
+	const keepStart = findSafeTrimIndex(messages, messages.length - config.keepRecentMessages)
 	const recentMessages = messages.slice(keepStart)
 	const olderMessages = messages.slice(systemMessages.length, keepStart)
 
+	// D7: nothing meaningful to compact — skip instead of thrashing the
+	// permanent leading floor every iteration (and avoid an LLM verification
+	// call when there is no older history to summarize). Scoped to the new
+	// contextWindowTokens path so any existing consumer (tokenBudget-only) keeps
+	// its exact prior behavior — byte-identical (ses_055 verify).
+	if (config.contextWindowTokens != null && olderMessages.length < MIN_OLDER_MESSAGES_TO_COMPACT) {
+		ctx.log.debug('Skipping compaction — too few older messages', {
+			runId: ctx.runMgr.id,
+			olderMessages: olderMessages.length,
+		})
+		return
+	}
+
 	let compactedContent: string
 
 	if (config.llmVerification && manager.slotCount() < config.richStateThreshold) {
@@ -77,7 +132,38 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 
 	const compactionMessage = createSystemMessage(`${COMPACTION_HEADER}\n\n${compactedContent}`)
 
-	const newMessages = [...systemMessages, compactionMessage, ...recentMessages]
+	// On the new per-iteration (contextWindowTokens) path, drop any PRIOR
+	// `[COMPACTED CONTEXT]` summary from the leading floor — `serializeState` is
+	// cumulative, so the new summary supersedes it. Without this the never-trimmed
+	// floor accumulates one redundant summary per pass and the frequent
+	// per-iteration trigger makes that bloat unbounded (ses_055 verify, MEDIUM).
+	// Legacy consumers (no contextWindowTokens) keep their exact prior
+	// accumulation behavior — byte-identical.
+	const preservedSystem =
+		config.contextWindowTokens != null
+			? systemMessages.filter((m) => !isCompactionMessage(m.content))
+			: systemMessages
+	const newMessages = [...preservedSystem, compactionMessage, ...recentMessages]
+
+	// OPAQUE survival guard (ses_055 D1): the pinned working-memory slot is a
+	// leading system message, so it is kept in `preservedSystem` (the compaction
+	// filter only drops prior `[COMPACTED CONTEXT]` summaries, never the WM slot)
+	// and survives for free — this branch is DEFENSIVE-ONLY, exercised only if a
+	// future change drops the slot from the rebuilt set. It re-pins the block
+	// already present in `messages` (the one `refreshWorkingMemory` placed).
+	// Identity is the sentinel HEADER only — no path parsing, no second provider
+	// call, no host format knowledge in the SDK.
+	const survives = newMessages.some((m) => m.role === 'system' && isWorkingMemoryMessage(m.content))
+	if (!survives) {
+		const priorSlot = messages.find((m) => m.role === 'system' && isWorkingMemoryMessage(m.content))
+		if (priorSlot) {
+			// Re-pin as the last leading system message, before the summary.
+			newMessages.splice(preservedSystem.length, 0, priorSlot)
+			ctx.log.warn('Re-pinned working-memory slot dropped by compaction', {
+				runId: ctx.runMgr.id,
+			})
+		}
+	}
 
 	const oldCount = messages.length
 	messages.length = 0

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

@@ -6,6 +6,7 @@ import type { PlanManager } from '../../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../../manager/run/persistence.js'
 import type { ActivityStore } from '../../../../store/activity/memory.js'
 import type { TaskGateway, TaskHandle } from '../../../../types/agent/gateway.js'
+import type { WorkingMemoryProvider } from '../../../../types/agent/working-memory.js'
 import type { HITLResumeDecision, ResumeHandler } from '../../../../types/hitl/index.js'
 import type { TaskId } from '../../../../types/ids/index.js'
 import type { LLMProvider } from '../../../../types/provider/index.js'
@@ -63,6 +64,8 @@ export interface IterationContext {
 
 	readonly workingStateManager?: WorkingStateManager
 
+	readonly workingMemoryProvider?: WorkingMemoryProvider
+
 	readonly advisoryCtx?: AdvisoryContext
 
 	readonly agentBus?: AgentBus
@@ -74,6 +77,57 @@ export interface IterationContext {
 
 export type PhaseSignal = 'continue' | 'stop'
 
+/**
+ * Await a HITL `resumeHandler` decision, but RACE it against the run's abort
+ * signal. A Stop that arrives while the run is parked on a tool-review or
+ * iteration checkpoint used to do nothing until the host eventually answered
+ * (the park await was not cancellable). Racing the signal lets a Stop resolve
+ * the park immediately as an `abort` decision, which `handleHITLDecision`
+ * turns into `setStopReason('cancelled') + markCancelled + stop`. Fails closed:
+ * a resume-handler rejection also resolves to `abort` rather than hanging.
+ */
+export async function awaitDecisionOrAbort(
+	ctx: IterationContext,
+	request: Parameters<ResumeHandler>[0],
+): Promise<HITLResumeDecision> {
+	const signal = ctx.abortController?.signal
+	// No abort signal wired (e.g. a minimal test harness) → behave exactly as a
+	// direct resumeHandler await, no race. In production RunContextFactory always
+	// provides the controller, so the race below is live.
+	if (!signal) return ctx.resumeHandler(request)
+	const abortDecision: HITLResumeDecision = {
+		action: 'abort',
+		reason: 'run aborted while parked for HITL',
+	}
+	if (signal.aborted) return abortDecision
+	return new Promise<HITLResumeDecision>((resolve) => {
+		let settled = false
+		const onAbort = (): void => {
+			if (settled) return
+			settled = true
+			resolve(abortDecision)
+		}
+		signal.addEventListener('abort', onAbort, { once: true })
+		Promise.resolve(ctx.resumeHandler(request)).then(
+			(decision) => {
+				if (settled) return
+				settled = true
+				signal.removeEventListener('abort', onAbort)
+				resolve(decision)
+			},
+			(err) => {
+				if (settled) return
+				settled = true
+				signal.removeEventListener('abort', onAbort)
+				resolve({
+					action: 'abort',
+					reason: err instanceof Error ? err.message : 'resume handler failed',
+				})
+			},
+		)
+	})
+}
+
 export async function* handleHITLDecision(
 	ctx: IterationContext,
 	decision: HITLResumeDecision,
@@ -125,6 +179,10 @@ export async function* handleHITLDecision(
 		case 'approve_tools':
 		case 'modify_tools':
 		case 'reject_tools':
+		// 'answer_question' can only arrive misdirected at an iteration
+		// checkpoint (answers are consumed inside the ask_user_question
+		// tool's own park); treat it as a plain continue.
+		case 'answer_question':
 			return 'continue'
 		default: {
 			const _exhaustive: never = decision

package/src/runtime/query/iteration/phases/hitl-abort-race.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+
+import type { HITLResumeDecision } from '../../../../types/hitl/index.js'
+import type { RunId } from '../../../../types/ids/index.js'
+import { type IterationContext, awaitDecisionOrAbort } from './context.js'
+
+/**
+ * C12: a Stop that arrives while the run is parked on a HITL decision must
+ * interrupt the park (resolve as `abort`) instead of hanging until the host
+ * eventually answers. `awaitDecisionOrAbort` races `resumeHandler` against
+ * `ctx.abortController.signal`.
+ */
+
+function ctxWith(opts: {
+	controller?: AbortController
+	resumeHandler: IterationContext['resumeHandler']
+}): IterationContext {
+	return {
+		abortController: opts.controller,
+		resumeHandler: opts.resumeHandler,
+		runMgr: { id: 'run_abort_test' as RunId },
+	} as unknown as IterationContext
+}
+
+const REVIEW_REQUEST = {
+	type: 'tool_review' as const,
+	runId: 'run_abort_test' as RunId,
+	checkpointId: 'cp_1' as `cp_${string}`,
+	toolCalls: [],
+}
+
+describe('awaitDecisionOrAbort (C12 — cancellable HITL park)', () => {
+	it('returns abort immediately when the signal is already aborted', async () => {
+		const controller = new AbortController()
+		controller.abort()
+		const ctx = ctxWith({
+			controller,
+			// A handler that never resolves — proving we did not wait on it.
+			resumeHandler: () => new Promise<HITLResumeDecision>(() => {}),
+		})
+		const decision = await awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		expect(decision.action).toBe('abort')
+	})
+
+	it('resolves as abort when the signal fires DURING the park', async () => {
+		const controller = new AbortController()
+		const ctx = ctxWith({
+			controller,
+			resumeHandler: () => new Promise<HITLResumeDecision>(() => {}), // never answers
+		})
+		const pending = awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		controller.abort()
+		const decision = await pending
+		expect(decision.action).toBe('abort')
+	})
+
+	it('returns the real decision when the handler answers before any abort', async () => {
+		const controller = new AbortController()
+		const ctx = ctxWith({
+			controller,
+			resumeHandler: async () => ({ action: 'approve_tools' }) as HITLResumeDecision,
+		})
+		const decision = await awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		expect(decision.action).toBe('approve_tools')
+	})
+
+	it('degrades to a direct resumeHandler await when no controller is wired', async () => {
+		const ctx = ctxWith({
+			resumeHandler: async () => ({ action: 'reject_tools' }) as HITLResumeDecision,
+		})
+		const decision = await awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		expect(decision.action).toBe('reject_tools')
+	})
+
+	it('fails closed to abort when the resume handler rejects', async () => {
+		const controller = new AbortController()
+		const ctx = ctxWith({
+			controller,
+			resumeHandler: async () => {
+				throw new Error('handler boom')
+			},
+		})
+		const decision = await awaitDecisionOrAbort(ctx, REVIEW_REQUEST)
+		expect(decision.action).toBe('abort')
+	})
+})

package/src/runtime/query/iteration/phases/hitl-answer-question.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest'
+
+import { type HITLResumeDecision, autoApproveHandler } from '../../../../types/hitl/index.js'
+import type { CheckpointId, RunId } from '../../../../types/ids/index.js'
+import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
+import type { RunEvent } from '../../../../types/run/index.js'
+import { type IterationContext, handleHITLDecision } from './context.js'
+import { runToolReview } from './tool-review.js'
+
+async function drainGenerator<TReturn>(
+	gen: AsyncGenerator<RunEvent, TReturn>,
+): Promise<{ events: RunEvent[]; value: TReturn }> {
+	const events: RunEvent[] = []
+	let next = await gen.next()
+	while (!next.done) {
+		events.push(next.value)
+		next = await gen.next()
+	}
+	return { events, value: next.value }
+}
+
+describe('autoApproveHandler user_question case', () => {
+	it('returns the non-fabricating no-answer sentinel with the questionId echoed', async () => {
+		const decision = await autoApproveHandler({
+			type: 'user_question',
+			runId: 'run_headless_test' as RunId,
+			checkpointId: 'cp_question_toolu_1' as CheckpointId,
+			question: {
+				questionId: 'toolu_1',
+				question: 'Pick one?',
+				options: [
+					{ id: 'opt_1', label: 'A' },
+					{ id: 'opt_2', label: 'B' },
+				],
+				multiSelect: false,
+				allowFreeText: true,
+			},
+		})
+
+		expect(decision).toEqual({
+			action: 'answer_question',
+			selectedOptionIds: [],
+			freeText: 'No user is available to answer. Proceed using your best judgment.',
+			questionId: 'toolu_1',
+		})
+	})
+})
+
+describe('handleHITLDecision answer_question case', () => {
+	it("treats a misdirected 'answer_question' at an iteration checkpoint as continue", async () => {
+		// The branch returns without touching the context — answers are
+		// consumed inside the ask_user_question tool's own park, so an
+		// answer arriving here can only be misdirected.
+		const ctx = {} as IterationContext
+		const { events, value } = await drainGenerator(
+			handleHITLDecision(
+				ctx,
+				{ action: 'answer_question', selectedOptionIds: ['opt_1'] },
+				'cp_checkpoint_1',
+				'iteration checkpoint',
+			),
+		)
+		expect(value).toBe('continue')
+		expect(events).toEqual([])
+	})
+})
+
+describe('runToolReview answer_question case', () => {
+	function reviewContext(decision: HITLResumeDecision) {
+		const warns: string[] = []
+		const pushed: unknown[] = []
+		let batches = 0
+		const ctx = {
+			tools: { get: () => undefined },
+			checkpointMgr: {
+				create: async () => ({ id: 'cp_review_1' as CheckpointId }),
+			},
+			emitEvent: async () => {},
+			drainPending: (): Generator<RunEvent> => [][Symbol.iterator]() as Generator<RunEvent>,
+			resumeHandler: async () => decision,
+			log: {
+				debug: () => {},
+				info: () => {},
+				warn: (message: string) => {
+					warns.push(message)
+				},
+				error: () => {},
+			},
+			runMgr: {
+				id: 'run_tool_review_test' as RunId,
+				pushMessage: (message: unknown) => {
+					pushed.push(message)
+				},
+			},
+			toolExecutor: {
+				executeBatch: async () => {
+					batches += 1
+					return { messages: [], results: [] }
+				},
+			},
+		} as unknown as IterationContext
+		return { ctx, warns, pushed, batchCount: () => batches }
+	}
+
+	const response: ChatCompletionResponse = {
+		id: 'resp_1',
+		model: 'test-model',
+		message: {
+			role: 'assistant',
+			content: null,
+			toolCalls: [
+				{
+					id: 'toolu_review_1',
+					type: 'function',
+					function: { name: 'ask_user_question', arguments: '{}' },
+				},
+			],
+		},
+		finishReason: 'tool_calls',
+		usage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+	}
+
+	it("warns and executes the batch on a misdirected 'answer_question' instead of stalling", async () => {
+		const { ctx, warns, batchCount } = reviewContext({
+			action: 'answer_question',
+			selectedOptionIds: [],
+		})
+		const { value } = await drainGenerator(runToolReview(ctx, response, 1))
+		expect(value).toBe('executed')
+		expect(batchCount()).toBe(1)
+		expect(warns).toHaveLength(1)
+	})
+})