@namzu/sdk 43.0.0 → 44.1.0

package/dist/runtime/query/index.js

@@ -1,4 +1,3 @@
-import { join } from 'node:path';
 import { AdvisorRegistry, AdvisoryContext, AdvisoryExecutor, TriggerEvaluator, assertBudgetEnforceable, } from '../../advisory/index.js';
 import { AuthorizationGate } from '../../authorization/gate.js';
 import { repairToolMessageHistory, toolHistoryRepairChanged } from '../../compaction/dangling.js';
@@ -7,13 +6,13 @@ import { WorkingStateManager } from '../../compaction/manager.js';
 import { serializeState as serializeWorkingState } from '../../compaction/serializer.js';
 import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire.js';
 import { CompactionConfigSchema } from '../../config/runtime.js';
-import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js';
-import { EmergencySaveManager } from '../../manager/run/emergency.js';
+import { childSessionLog } from '../../manager/agent/child-session.js';
+import { recordedTurnStart } from '../../manager/session/turn-recorder.js';
 import { PromptContributionRegistry } from '../../prompt/contributions.js';
 import { resolveProviderCapabilities } from '../../provider/capabilities.js';
 import { withStreamIdleTimeout } from '../../provider/idle-timeout.js';
 import { withTokenBudget } from '../../provider/token-budget.js';
-import { GENAI, NAMZU, agentRunSpanName, parentContext, serializeSpan, } from '../../telemetry/attributes.js';
+import { GENAI, NAMZU, agentTurnSpanName, parentContext, serializeSpan, } from '../../telemetry/attributes.js';
 import { getTracer } from '../../telemetry/runtime-accessors.js';
 import { buildAdvisoryTools } from '../../tools/advisory/index.js';
 import { SearchToolsTool } from '../../tools/builtins/search-tools.js';
@@ -23,22 +22,23 @@ import { isTerminalStatus } from '../../types/common/index.js';
 import { NamzuError } from '../../types/errors/index.js';
 import { autoApproveHandler, } from '../../types/hitl/index.js';
 import { createSystemMessage, } from '../../types/message/index.js';
+import { isTurnInProgressError, } from '../../types/session/index.js';
 import { toErrorMessage } from '../../utils/error.js';
 import { errorAttributes } from '../../utils/log/exception.js';
 import { AwaitedJobs } from '../jobs/awaited-jobs.js';
 import { catchUpFromCursor, settlePreStartCancellation } from './cancelled-before-start.js';
 import { CheckpointManager, findPendingCheckpoint } from './checkpoint.js';
-import { finalizeRun } from './finalize-run.js';
+import { finalizeTurn } from './finalize-turn.js';
 import { GuardCoordinator } from './guard.js';
 import { runInputGuardrails } from './guardrails.js';
 import { IterationOrchestrator } from './iteration/index.js';
 import { isCompactionMessage } from './iteration/phases/compaction.js';
 import { isWorkingMemoryMessage } from './iteration/phases/working-memory.js';
 import { applyLifecycleHookResults } from './plugin-hooks.js';
-import { prepareRun, projectStateBearingHistory, resolveProviderContextWindow, selectedResumeStates, } from './prepare-run.js';
+import { prepareTurn, projectStateBearingHistory, resolveProviderContextWindow, selectedResumeStates, } from './prepare-turn.js';
 import { PromptBuilder } from './prompt.js';
 import { PendingAnswers, QuestionParkBinding } from './question-park.js';
-import { releaseRunResources } from './release-run.js';
+import { releaseTurnResources } from './release-turn.js';
 import { RepeatCallTracker } from './repeat-call.js';
 import { ResultAssembler } from './result.js';
 import { answersParkOf, applyPendingResume, interruptedToolCalls, planCrashResume, planPendingResume, recoverCompletedCalls, supersededByRecovery, } from './resume-pending.js';
@@ -53,7 +53,7 @@ import { ToolingBootstrap } from './tooling.js';
  * The plan re-appends the exact assistant with real/denied/recovered results.
  * Generic history repair must not synthesize a competing result first. Any
  * partial results for that turn are removed too; the executor reconstructs
- * them from the durable run transcript through `recoveredResults`.
+ * them from the durable turn transcript through `recoveredResults`.
  */
 function withoutOwnedResumeTurn(messages, assistant) {
     const ownerIndex = messages.lastIndexOf(assistant);
@@ -112,1328 +112,1363 @@ function withOwnedResumeOutcomes(messages, assistant, recovered) {
     ];
 }
 export async function* query(params) {
-    const prepared = await prepareRun(params);
-    const { runConfig, budget, log, ctx, resilientProvider, serving, providerContextWindow, modelContextWindows, approvalPolicy, eventTranslator, executeUserInterruptHooks, pendingHistoryRepairs, initialMessages, queuedForThisRun, selectedResumeState, attachmentResolutionCancelled, streamIdleTimeoutMs, sandboxTeardownTimeoutMs, promptCache, taskScheduler, } = prepared;
+    const prepared = await prepareTurn(params);
+    const { turnConfig, budget, log, ctx, resilientProvider, serving, providerContextWindow, modelContextWindows, approvalPolicy, eventTranslator, executeUserInterruptHooks, pendingHistoryRepairs, initialMessages, historyIds, queuedForThisRun, selectedResumeState, attachmentResolutionCancelled, streamIdleTimeoutMs, sandboxTeardownTimeoutMs, promptCache, taskScheduler, } = prepared;
     if (attachmentResolutionCancelled) {
-        return yield* settlePreStartCancellation(params, prepared);
-    }
-    const unsubscribeTaskStore = params.taskStore
-        ? eventTranslator.wireTaskStore(params.taskStore, ctx.runId)
-        : undefined;
-    if (params.taskStore) {
-        const taskTools = buildTaskTools(params.taskStore, ctx.runId);
-        const overrides = params.runtimeToolOverrides;
-        for (const tool of taskTools) {
-            const override = overrides?.[tool.name];
-            if (override === 'disabled')
-                continue;
-            params.tools.register(tool, override ?? 'deferred');
+        try {
+            return yield* settlePreStartCancellation(params, prepared);
         }
-    }
-    if (!params.tools.has(SearchToolsTool.name)) {
-        const hasDeferred = params.tools
-            .listNames()
-            .some((n) => params.tools.getAvailability(n) === 'deferred');
-        if (hasDeferred) {
-            params.tools.register(SearchToolsTool);
+        finally {
+            await ctx.recorder.release();
         }
     }
-    // Registered HERE, before the first turn, not when the model is nearly
-    // done. Tools render at prefix position 0, so injecting one late would
-    // invalidate the whole prompt cache for the rest of the run — the same
-    // reason the forced-final turn keeps its tools array and uses
-    // `toolChoice: 'none'` instead of dropping it.
-    if (params.structuredOutput &&
-        params.structuredOutput.mode !== 'native' &&
-        !params.tools.has(STRUCTURED_OUTPUT_TOOL_NAME)) {
-        params.tools.register(createStructuredOutputTool(params.structuredOutput.schema));
-    }
-    // ─── Provider capability negotiation (before tooling bootstrap) ────────
-    // Compare what the request asks for with what the DRIVER declared it
-    // does. Undeclared capabilities resolve permissively (today's behavior
-    // for third-party providers); declared gaps degrade loudly instead of
-    // silently.
-    const capabilities = resolveProviderCapabilities(params.provider);
-    const registeredToolCount = params.tools.listNames().length;
-    const stripToolSurfaces = !capabilities.supportsTools && registeredToolCount > 0;
-    // Counted separately because they are separate wire shapes: a driver can
-    // map images and drop documents, and a vision warning would send the
-    // reader looking at the wrong half.
-    const carries = (m, kind) => m.role === 'user' && (m.attachments ?? []).some((a) => (a.type ?? 'image') === kind);
-    const attachmentMessageCount = capabilities.supportsVision
-        ? 0
-        : params.messages.filter((m) => carries(m, 'image')).length;
-    const documentMessageCount = capabilities.supportsDocuments
-        ? 0
-        : params.messages.filter((m) => carries(m, 'document')).length;
-    if (stripToolSurfaces) {
-        const message = `Provider '${params.provider.id}' declares supportsTools: false but ${registeredToolCount} tool(s) are registered — stripping all tool surfaces from the prompt and request so the model is never told about tools it cannot call. Pass strictCapabilities: true to fail instead, or use a tools-capable provider.`;
-        if (params.strictCapabilities) {
-            throw new NamzuError({
-                code: 'capability_unavailable',
-                message,
-                details: {
-                    providerId: params.provider.id,
-                    capability: 'tools',
-                    registeredToolCount,
-                },
+    // Everything from here to the turn body can refuse (a capability the
+    // provider lacks, a sandbox mode it does not offer); the lease the
+    // prelude took is given back on the way out.
+    let unsubscribeChildSessions;
+    try {
+        const unsubscribeTaskStore = params.taskStore
+            ? eventTranslator.wireTaskStore(params.taskStore, ctx.sessionId)
+            : undefined;
+        // The children this turn delegates to are recorded in this session's
+        // log: `child_session_spawned` when one starts, `child_session_ended`
+        // (read from the child's own log) when it goes idle. That is what lets
+        // the parent list and replay its children once the process is gone.
+        unsubscribeChildSessions = taskScheduler?.onChildSessionEvent?.((event) => {
+            // Looked up now, while the manager still holds the child's spawn record.
+            const childLog = event.type === 'child_session_idled' ? childSessionLog(event.childSessionId) : undefined;
+            void ctx.recorder.recordChildSessionEvent(event, childLog).catch((err) => {
+                ctx.log.warn('A child session record could not be appended', {
+                    [NAMZU.TURN_ID]: ctx.turnId,
+                    'namzu.child_session.id': event.childSessionId,
+                    'exception.message': err instanceof Error ? err.message : String(err),
+                });
             });
-        }
-        ctx.log.warn('Capability mismatch: the provider declares no tool support', {
-            'namzu.capability.detail': message,
-            [GENAI.SYSTEM]: params.provider.id,
-            'namzu.runtime.registered_tool_count': registeredToolCount,
         });
-    }
-    if (attachmentMessageCount > 0) {
-        const message = `Provider '${params.provider.id}' declares supportsVision: false but ${attachmentMessageCount} user message(s) carry image attachments — the driver will not map them, so the model never sees the images. Pass strictCapabilities: true to fail instead, or use a vision-capable provider.`;
-        if (params.strictCapabilities) {
-            throw new NamzuError({
-                code: 'capability_unavailable',
-                message,
-                details: {
-                    providerId: params.provider.id,
-                    capability: 'vision',
-                    attachmentMessageCount,
-                },
+        if (params.taskStore) {
+            const taskTools = buildTaskTools(params.taskStore, {
+                sessionId: ctx.sessionId,
+                turnId: ctx.turnId,
+                // A resumed turn began when its `turn_started` was recorded, maybe
+                // in another process: tasks it closed before the pause are still
+                // "closed in this turn".
+                turnStartedAt: (params.resumeFromCheckpoint
+                    ? await recordedTurnStart(ctx.recorder.log, ctx.turnId)
+                    : undefined) ?? ctx.recorder.getTurn().startedAt,
             });
-        }
-        ctx.log.warn('Capability mismatch: the provider declares no vision support', {
-            'namzu.capability.detail': message,
-            [GENAI.SYSTEM]: params.provider.id,
-            'namzu.runtime.attachment_message_count': attachmentMessageCount,
-        });
-    }
-    if (documentMessageCount > 0) {
-        const message = `Provider '${params.provider.id}' declares supportsDocuments: false but ${documentMessageCount} user message(s) carry document attachments — the driver will not map them, so the model never sees the documents. Pass strictCapabilities: true to fail instead, or use a document-capable provider.`;
-        if (params.strictCapabilities) {
-            throw new NamzuError({
-                code: 'capability_unavailable',
-                message,
-                details: {
-                    providerId: params.provider.id,
-                    capability: 'documents',
-                    documentMessageCount,
-                },
-            });
-        }
-        ctx.log.warn('Capability mismatch: the provider declares no document support', {
-            'namzu.capability.detail': message,
-            [GENAI.SYSTEM]: params.provider.id,
-            'namzu.runtime.document_message_count': documentMessageCount,
-        });
-    }
-    // Denied names are subtracted LAST, after the allow-list is resolved
-    // against the registry — so a deny reaches a run that named no
-    // allow-list at all, which is the ordinary case for a delegated child.
-    // Applied to `effectiveAllowedTools`, which `query()` binds to both the
-    // request tool list AND the `ToolExecutor`: narrowing only the request
-    // shows the model fewer tools and lets it call any of them by name.
-    const allowedBeforeDenial = stripToolSurfaces
-        ? []
-        : withDeferredDiscoveryTool(params.tools, params.allowedTools);
-    const denied = new Set(params.deniedTools ?? []);
-    const effectiveAllowedTools = denied.size === 0
-        ? allowedBeforeDenial
-        : // An absent allow-list means "every registered tool", so a deny
-            // with no allow-list has to be resolved against the registry
-            // here — otherwise the subtraction would be from an empty list
-            // and would deny nothing, which is the shape a delegated child
-            // arrives in.
-            [...(allowedBeforeDenial ?? params.tools.listNames())].filter((name) => !denied.has(name));
-    // The two halves of a durable pause, owned by the RUN when the host
-    // does not own them.
-    //
-    // `SupervisorAgent` builds both before the run exists, because the
-    // tools it builds close over them, and it passes them in. Nothing else
-    // could: neither type is exported from `public-runtime.ts`, so a host
-    // on `ReactiveAgent`, `drainQuery` or `resumeRun` had no way to supply
-    // either — and `ToolContext.requestPause`, which every tool author is
-    // handed, silently wrote no checkpoint and could receive no answer on
-    // those surfaces. Which agent class the host happened to pick is not
-    // visible at the call site, so the degradation was invisible too.
-    //
-    // A run-local pair is enough for the general seam because `query()`
-    // builds its `createToolPause` itself, below, and can hand it the
-    // run's own. Pinned by the "a pause is durable on any surface" cases
-    // in `__tests__/tool-pause-resume.test.ts`.
-    const questionParks = params.questionParks ?? new QuestionParkBinding();
-    const pendingAnswers = params.pendingAnswers ?? new PendingAnswers();
-    // One gate instance owns both model-issued calls and calls dispatched by
-    // another tool. Constructing it only inside the iteration review left the
-    // nested registry path outside the operator's policy entirely.
-    const gateConfig = params.authorizationGate;
-    const verificationGate = gateConfig?.enabled
-        ? new AuthorizationGate(gateConfig, ctx.log)
-        : undefined;
-    // The store is initialized when the async query starts, after tooling is
-    // composed. Resolve lazily at execution time: capturing getRunDir() here
-    // permanently disabled retention for fresh disk-backed invocations.
-    const toolOutputDir = () => {
-        const runDir = ctx.runMgr.getRunDir();
-        return runDir ? join(runDir, TOOL_OUTPUT_DIR_NAME) : undefined;
-    };
-    // The same invocation-owned capability serves tools and optional preparation.
-    // Local cancellation cannot override the run's cancellation or settled state.
-    const captureRunEvidence = async (maxReadBytes, signal) => {
-        const combined = signal
-            ? AbortSignal.any([ctx.abortController.signal, signal])
-            : ctx.abortController.signal;
-        combined.throwIfAborted();
-        const source = await eventTranslator.captureRunEvidence(maxReadBytes, combined);
-        combined.throwIfAborted();
-        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,
-        runId: ctx.runId,
-        workingDirectory: ctx.cwd,
-        ...(params.additionalDirectories?.length
-            ? { additionalDirectories: params.additionalDirectories }
-            : {}),
-        permissionMode: () => ctx.permissionMode.current,
-        env: runConfig.env ?? {},
-        abortSignal: ctx.abortController.signal,
-        allowedTools: effectiveAllowedTools,
-        invocationState: params.invocationState,
-        pluginManager: params.pluginManager,
-        ...(params.backgroundJobs ? { backgroundJobs: params.backgroundJobs } : {}),
-        ...(params.backgroundJobOwner ? { backgroundJobOwner: params.backgroundJobOwner } : {}),
-        ...(awaitedJobs ? { onJobAwaited: (id) => 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.
-        ...(params.skillRegistry ? { skills: params.skillRegistry } : {}),
-        ...(params.web ? { web: params.web } : {}),
-        ...(params.fileReadTracker ? { fileReadTracker: params.fileReadTracker } : {}),
-        ...(params.toolTimeoutMs !== undefined ? { toolTimeoutMs: params.toolTimeoutMs } : {}),
-        ...(params.toolRetryBackoff !== undefined
-            ? { toolRetryBackoff: params.toolRetryBackoff }
-            : {}),
-        ...(params.maxToolCalls !== undefined
-            ? {
-                maxToolCalls: params.maxToolCalls,
-                readToolCallBudgetEvents: () => eventTranslator.readEvents({ integrity: 'strict' }),
-            }
-            : {}),
-        ...(params.maxToolConcurrency !== undefined
-            ? { maxToolConcurrency: params.maxToolConcurrency }
-            : {}),
-        ...(params.maxToolOutputChars !== undefined
-            ? { maxToolOutputChars: params.maxToolOutputChars }
-            : {}),
-        ...(params.toolResultGuardrails !== undefined
-            ? { toolResultGuardrails: params.toolResultGuardrails }
-            : {}),
-        ...(params.retainedToolPreviewChars !== undefined
-            ? { retainedToolPreviewChars: params.retainedToolPreviewChars }
-            : {}),
-        ...(params.maxToolContentBytes !== undefined
-            ? { maxToolContentBytes: params.maxToolContentBytes }
-            : {}),
-        // Overflow lands beside the run's other artifacts, so it is
-        // cleaned up with the run and reachable by the model's own
-        // `read`/`grep` without a new affordance.
-        toolOutputDir,
-        captureRunEvidence,
-        ...(params.repairToolCall ? { repairToolCall: params.repairToolCall } : {}),
-        ...(verificationGate ? { authorizationGate: verificationGate } : {}),
-        recordAudit: (input) => ctx.runMgr.recordAudit(input),
-        // The durable pause, reachable from any tool rather than from the
-        // four kernel-owned points that used to own it. Built here from
-        // the machinery the run already holds; the recorder binds a few
-        // lines below, and until it does a pause is in-process only —
-        // the same degradation the built-in question tool has.
-        toolPause: (toolUseId) => createToolPause({
-            runId: ctx.runId,
-            toolUseId,
-            parkHandler: (request) => approvalPolicy.current.handler(request),
-            recorder: questionParks,
-            pendingAnswers,
-        }),
-    }, ctx.activityStore, eventTranslator.emitEvent, 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 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;
-    // 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,
-        skills: params.skills,
-        basePrompt: params.basePrompt,
-        tools: params.tools,
-        allowedTools: effectiveAllowedTools,
-        runtimeContext: params.runtimeContext,
-        contributions: promptContributions,
-    });
-    const guard = new GuardCoordinator({
-        tokenBudget: runConfig.tokenBudget,
-        timeoutMs: runConfig.timeoutMs,
-        costLimitUsd: runConfig.costLimitUsd,
-        maxIterations: runConfig.maxIterations,
-    });
-    const checkpointMgr = new CheckpointManager(ctx.runMgr.getCheckpointStore(), ctx.runMgr.getRunScope());
-    // Every checkpoint carries compaction's accumulated state, so a run that
-    // comes back in a new process can adopt it (see the restore block).
-    // Without it, compaction's own justification for dropping the prior
-    // `[COMPACTED CONTEXT]` block — that `serializeState` is cumulative —
-    // holds within one process and fails across a resume.
-    if (workingStateManager) {
-        const manager = workingStateManager;
-        checkpointMgr.setWorkingStateSource(() => snapshotWorkingState(manager));
-    }
-    const resultAssembler = new ResultAssembler({
-        runMgr: ctx.runMgr,
-        planManager: ctx.planManager,
-        activityStore: ctx.activityStore,
-        log: ctx.log,
-        emitEvent: eventTranslator.emitEvent,
-        drainPending: () => eventTranslator.drainPending(),
-        // Read at settle time, not now: checkpoints are written per
-        // iteration, so the answer changes as the run proceeds.
-        resumeCheckpointId: () => checkpointMgr.lastCheckpointId,
-        // Read only to recover WHY a cancellation happened. The run loop
-        // already knows THAT it was cancelled; the origin lives on the abort
-        // reason and nothing else carries it this far.
-        signal: ctx.abortController.signal,
-    });
-    let advisoryCtx;
-    if (params.advisory && params.advisory.advisors.length > 0) {
-        // Advisors are model calls owned by this run even when they use a
-        // different provider. Sending the raw definitions into the registry
-        // lets a triggered or model-requested consultation bypass both the
-        // finite stream-silence bound and Stop. Bind every advisor provider at
-        // the query boundary, where the effective timeout and run signal are
-        // already known; standalone AdvisoryExecutor callers retain their
-        // explicitly chosen provider/cancellation policy.
-        const boundedAdvisors = params.advisory.advisors.map((advisor) => ({
-            ...advisor,
-            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
-        // silently ignored for the length of the run.
-        assertBudgetEnforceable(params.advisory);
-        const advisoryExecutor = new AdvisoryExecutor(ctx.log, params.advisory.budget, ctx.abortController.signal);
-        const triggerEvaluator = new TriggerEvaluator(params.advisory.triggers ?? [], params.advisory.budget);
-        advisoryCtx = new AdvisoryContext(advisorRegistry, advisoryExecutor, triggerEvaluator, params.advisory.budget);
-        // What the run looks like when the MODEL consults an advisor, as
-        // opposed to when a trigger does. The trigger path has always passed
-        // this; the tool path passed an empty context, so an advisor the model
-        // asked for help saw the question and nothing else.
-        //
-        // `includeToolCatalog` and `useCompactedContext` are read here and
-        // nowhere else. Both were declared on `AdvisoryConfig` /
-        // `AdvisorDefinition` and consulted by nothing, so a host who turned
-        // the catalogue off still paid for it in every advisory prompt.
-        const advisoryConfig = params.advisory;
-        advisoryCtx.setCallContextProvider(() => {
-            const summary = workingStateManager && advisoryConfig.advisors.some((a) => a.useCompactedContext)
-                ? serializeWorkingState(workingStateManager.getState())
-                : undefined;
-            return {
-                messages: ctx.runMgr.messages,
-                turn: iterationOrchestrator.getAdvisoryTurnContext(),
-                ...(summary !== undefined ? { workingStateSummary: summary } : {}),
-                ...(advisoryConfig.includeToolCatalog
-                    ? { toolCatalog: params.tools.toLLMTools(effectiveAllowedTools) }
-                    : {}),
-                iteration: ctx.runMgr.currentIteration,
-            };
-        });
-        if (params.advisory.enableAgentTool) {
-            const advisoryTools = buildAdvisoryTools({ advisoryCtx });
             const overrides = params.runtimeToolOverrides;
-            for (const tool of advisoryTools) {
+            for (const tool of taskTools) {
                 const override = overrides?.[tool.name];
                 if (override === 'disabled')
                     continue;
-                params.tools.register(tool, override ?? 'active');
+                params.tools.register(tool, override ?? 'deferred');
             }
         }
-    }
-    const iterationOrchestrator = new IterationOrchestrator({
-        captureRunEvidence,
-        provider: resilientProvider,
-        providerCapabilities: capabilities,
-        strictCapabilities: params.strictCapabilities === true,
-        servingMember: () => serving.current,
-        runConfig,
-        ...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),
-        ...(params.prepareStep ? { prepareStep: params.prepareStep } : {}),
-        ...(params.beforeStep ? { beforeStep: params.beforeStep } : {}),
-        ...(params.onStepFinish ? { onStepFinish: params.onStepFinish } : {}),
-        ...(params.reviewAnswer ? { reviewAnswer: params.reviewAnswer } : {}),
-        ...(params.maxAnswerReviews !== undefined ? { maxAnswerReviews: params.maxAnswerReviews } : {}),
-        ...(params.structuredOutput ? { structuredOutput: params.structuredOutput } : {}),
-        ...(params.parkRecordDelayMs !== undefined
-            ? { parkRecordDelayMs: params.parkRecordDelayMs }
-            : {}),
-        tools: params.tools,
-        allowedTools: effectiveAllowedTools,
-        runMgr: ctx.runMgr,
-        toolExecutor,
-        guard,
-        activityStore: ctx.activityStore,
-        emitEvent: eventTranslator.emitEvent,
-        drainPending: () => eventTranslator.drainPending(),
-        abortController: ctx.abortController,
-        log: ctx.log,
-        // Read through the box on every call, so a swap lands on the next
-        // question rather than the next run.
-        resumeHandler: (request) => approvalPolicy.current.handler(request),
-        takeApprovalPolicyChange: () => approvalPolicy.takeUnannouncedChange(),
-        promptContributions,
-        ...(params.steering ? { steering: params.steering } : {}),
-        ...(jobNotices ? { jobNotices } : {}),
-        ...(awaitedJobs ? { awaitedJobs } : {}),
-        checkpointMgr,
-        planManager: ctx.planManager,
-        taskGateway: taskScheduler,
-        completionInbox: params.completionInbox,
-        taskStore: params.taskStore,
-        // Run-scoped. An approval is a statement about this run's work;
-        // carrying one into a later run would be reuse nobody agreed to.
-        toolGrants: new ToolGrantSet(),
-        // Run-scoped for the same reason. A repeat count carried into a later
-        // 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.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
-        ...(params.resumeFromCheckpoint ? { resumedInput: queuedForThisRun } : {}),
-        ...(params.waitForInbound ? { waitForInbound: params.waitForInbound } : {}),
-        ...(params.projectInstructionContext
-            ? { projectInstructionContext: params.projectInstructionContext }
-            : {}),
-        ...(providerContextWindow !== undefined ? { providerContextWindow } : {}),
-        resolveModelContextWindow: async (model) => {
-            if (!modelContextWindows.has(model)) {
-                modelContextWindows.set(model, await resolveProviderContextWindow(resilientProvider, model, ctx.abortController.signal, runConfig.timeoutMs, log));
+        if (!params.tools.has(SearchToolsTool.name)) {
+            const hasDeferred = params.tools
+                .listNames()
+                .some((n) => params.tools.getAvailability(n) === 'deferred');
+            if (hasDeferred) {
+                params.tools.register(SearchToolsTool);
             }
-            return modelContextWindows.get(model);
-        },
-        workingStateManager,
-        taskRouter: params.taskRouter,
-        contextReducer: params.contextReducer,
-        workingMemoryProvider: params.workingMemoryProvider,
-        advisoryCtx,
-        agentBus: params.agentBus,
-        verificationGate,
-        pluginManager: params.pluginManager,
-    });
-    const tracer = getTracer();
-    // Whether the run reached its settle. Read by the `finally` below, and
-    // the only thing that distinguishes a run that finished from one whose
-    // consumer walked away — see `settleAbandonedRun`.
-    let settled = false;
-    const runBody = (async function* () {
-        // Parent explicitly when a caller supplied one. Without this every
-        // run starts its OWN root trace, so a supervisor delegating to three
-        // children produced four disconnected traces instead of one tree —
-        // the same defect that made a 20-turn run show up as 21 roots before
-        // iterations were parented, except across the spawn boundary, where
-        // it is worse: the delegation structure is the thing you most want
-        // to see.
-        const runStartedAt = Date.now();
-        // Read before the span is minted, because a parent can only be set
-        // at creation. A resumed run used to start a brand-new trace with no
-        // link to the one that crashed, so the failure and its recovery
-        // could not be put on one timeline — the run id correlated them well
-        // enough to find both by query and not well enough to see a single
-        // waterfall, and for a replay fork (which mints a new run id) not
-        // even that. An explicit caller-supplied parent still wins: it is
-        // the more specific statement about where this run belongs.
-        const resumedTrace = selectedResumeState
-            ? selectedResumeState.traceContext
-            : params.resumeFromCheckpoint
-                ? await checkpointMgr.readTraceContext(params.resumeFromCheckpoint)
-                : undefined;
-        const rootSpan = tracer.startSpan(agentRunSpanName(params.agentName), {}, parentContext(params.parentSpan ?? resumedTrace));
-        // Hand the run span to the loop so every iteration parents to it.
-        iterationOrchestrator.setRootSpan(rootSpan);
-        // Every checkpoint from here on records the trace it was taken
-        // inside, so the next resume can join this one.
-        checkpointMgr.setTraceSource(() => serializeSpan(rootSpan));
-        // And every park it records carries an absolute deadline, so an
-        // unanswered approval cannot outlive the worker that asked for it.
-        checkpointMgr.setParkTtl(runConfig.hitlParkTtlMs);
-        // The claim this worker holds, if it took one. Without this hop the
-        // fence exists, the refusal exists, and no checkpoint a RUN writes ever
-        // carries a number — so a stalled worker is refused nowhere.
-        checkpointMgr.setClaimFence(params.claimFence);
-        // A question raised from inside a tool becomes a real checkpoint
-        // here. It used to park under a synthetic id nothing ever wrote, so
-        // the checkpoint did not exist: nothing on disk said a human owed
-        // this run an answer, and a remote host could not observe the
-        // question at all.
-        questionParks.bind({
-            record: async (question) => {
-                try {
-                    const checkpoint = await checkpointMgr.create(ctx.runMgr, ctx.runMgr.currentIteration);
-                    const parked = await checkpointMgr.park(checkpoint, {
-                        type: 'user_question',
-                        runId: ctx.runMgr.id,
-                        checkpointId: checkpoint.id,
-                        question,
-                    });
-                    await eventTranslator.emitEvent({
-                        type: 'user_question_asked',
-                        runId: ctx.runMgr.id,
-                        checkpointId: parked.id,
-                        questionId: question.questionId,
-                        question: question.question,
-                    });
-                    return parked.id;
-                }
-                catch (err) {
-                    // A store that cannot record the park must not take the
-                    // tool down with it: the in-process await is still valid
-                    // and only the cross-process handoff is lost. Loudly,
-                    // because a host building an approval queue from durable
-                    // state will not see this question.
-                    ctx.log.error('Failed to record a question park — it is not resumable', {
-                        [NAMZU.RUN_ID]: ctx.runMgr.id,
-                        'namzu.runtime.question_id': question.questionId,
-                        'exception.message': err instanceof Error ? err.message : String(err),
-                    });
-                    return null;
-                }
-            },
-            resolve: async (checkpointId, decision) => {
-                await checkpointMgr.unpark(checkpointId, decision).catch((err) => {
-                    ctx.log.error('Failed to clear a recorded question park', {
-                        [NAMZU.RUN_ID]: ctx.runMgr.id,
-                        'namzu.checkpoint.id': checkpointId,
-                        'exception.message': err instanceof Error ? err.message : String(err),
-                    });
-                    return null;
-                });
-                await eventTranslator.emitEvent({
-                    type: 'user_question_answered',
-                    runId: ctx.runMgr.id,
-                    checkpointId,
-                    ...(decision.action === 'answer_question' && decision.questionId !== undefined
-                        ? { questionId: decision.questionId }
-                        : {}),
-                    answered: decision.action === 'answer_question',
+        }
+        // Registered HERE, before the first turn, not when the model is nearly
+        // done. Tools render at prefix position 0, so injecting one late would
+        // invalidate the whole prompt cache for the rest of the turn — the same
+        // reason the forced-final turn keeps its tools array and uses
+        // `toolChoice: 'none'` instead of dropping it.
+        if (params.structuredOutput &&
+            params.structuredOutput.mode !== 'native' &&
+            !params.tools.has(STRUCTURED_OUTPUT_TOOL_NAME)) {
+            params.tools.register(createStructuredOutputTool(params.structuredOutput.schema));
+        }
+        // ─── Provider capability negotiation (before tooling bootstrap) ────────
+        // Compare what the request asks for with what the DRIVER declared it
+        // does. Undeclared capabilities resolve permissively (today's behavior
+        // for third-party providers); declared gaps degrade loudly instead of
+        // silently.
+        const capabilities = resolveProviderCapabilities(params.provider);
+        const registeredToolCount = params.tools.listNames().length;
+        const stripToolSurfaces = !capabilities.supportsTools && registeredToolCount > 0;
+        // Counted separately because they are separate wire shapes: a driver can
+        // map images and drop documents, and a vision warning would send the
+        // reader looking at the wrong half.
+        const carries = (m, kind) => m.role === 'user' && (m.attachments ?? []).some((a) => (a.type ?? 'image') === kind);
+        const attachmentMessageCount = capabilities.supportsVision
+            ? 0
+            : params.messages.filter((m) => carries(m, 'image')).length;
+        const documentMessageCount = capabilities.supportsDocuments
+            ? 0
+            : params.messages.filter((m) => carries(m, 'document')).length;
+        if (stripToolSurfaces) {
+            const message = `Provider '${params.provider.id}' declares supportsTools: false but ${registeredToolCount} tool(s) are registered — stripping all tool surfaces from the prompt and request so the model is never told about tools it cannot call. Pass strictCapabilities: true to fail instead, or use a tools-capable provider.`;
+            if (params.strictCapabilities) {
+                throw new NamzuError({
+                    code: 'capability_unavailable',
+                    message,
+                    details: {
+                        providerId: params.provider.id,
+                        capability: 'tools',
+                        registeredToolCount,
+                    },
                 });
-            },
-        });
-        rootSpan.setAttributes({
-            [NAMZU.RUN_ID]: ctx.runMgr.id,
-            [GENAI.AGENT_NAME]: params.agentName,
-            [GENAI.AGENT_ID]: params.agentId,
-            [GENAI.REQUEST_MODEL]: runConfig.model,
-            [GENAI.SYSTEM]: params.provider.id,
-        });
-        let sandbox;
-        // Decided during checkpoint restore, executed after the sandbox
-        // exists — the approved tools may well need it.
-        let pendingResume = null;
-        /**
-         * The cadence park this resume answered, when the decision is one the
-         * ordinary continue path carries out. See the restore path below.
-         */
-        let answeredParkId;
-        /** Tool results recovered from the transcript; see the restore path. */
-        let recoveredResults = new Map();
-        let emergencyManager;
-        try {
-            await ctx.runMgr.init();
-            // A consumer coming back gets what it missed BEFORE the run says
-            // anything new, which is the only order that lets it fold one
-            // stream into one state. It has to follow `init()` — that is what
-            // binds the store and reads the log's head — and precede every
-            // emit below.
-            if (params.eventCursor) {
-                yield* catchUpFromCursor(ctx.runMgr, params.eventCursor, params.onEventReplay, params.claimFence, (error) => {
-                    ctx.log.warn('Replay observer failed', {
-                        'exception.message': toErrorMessage(error),
-                    });
+            }
+            ctx.log.warn('Capability mismatch: the provider declares no tool support', {
+                'namzu.capability.detail': message,
+                [GENAI.SYSTEM]: params.provider.id,
+                'namzu.runtime.registered_tool_count': registeredToolCount,
+            });
+        }
+        if (attachmentMessageCount > 0) {
+            const message = `Provider '${params.provider.id}' declares supportsVision: false but ${attachmentMessageCount} user message(s) carry image attachments — the driver will not map them, so the model never sees the images. Pass strictCapabilities: true to fail instead, or use a vision-capable provider.`;
+            if (params.strictCapabilities) {
+                throw new NamzuError({
+                    code: 'capability_unavailable',
+                    message,
+                    details: {
+                        providerId: params.provider.id,
+                        capability: 'vision',
+                        attachmentMessageCount,
+                    },
                 });
             }
-            ctx.log.info('Starting query', {
-                [NAMZU.RUN_ID]: ctx.runMgr.id,
-                'namzu.runtime.agent': params.agentName,
-                [GENAI.REQUEST_MODEL]: runConfig.model,
-                'namzu.runtime.token_budget': runConfig.tokenBudget,
-                'namzu.runtime.activity_tracking': ctx.activityStore.enabled,
-                'namzu.runtime.permission_mode': ctx.permissionMode.current,
-                'namzu.runtime.resume_from_checkpoint': params.resumeFromCheckpoint ?? null,
+            ctx.log.warn('Capability mismatch: the provider declares no vision support', {
+                'namzu.capability.detail': message,
+                [GENAI.SYSTEM]: params.provider.id,
+                'namzu.runtime.attachment_message_count': attachmentMessageCount,
             });
-            // 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();
+        }
+        if (documentMessageCount > 0) {
+            const message = `Provider '${params.provider.id}' declares supportsDocuments: false but ${documentMessageCount} user message(s) carry document attachments — the driver will not map them, so the model never sees the documents. Pass strictCapabilities: true to fail instead, or use a document-capable provider.`;
+            if (params.strictCapabilities) {
+                throw new NamzuError({
+                    code: 'capability_unavailable',
+                    message,
+                    details: {
+                        providerId: params.provider.id,
+                        capability: 'documents',
+                        documentMessageCount,
+                    },
+                });
             }
-            const contextLevel = params.contextLevel ?? 'full';
-            const cacheInput = {
-                systemPrompt: params.systemPrompt,
-                persona: params.persona,
-                skills: params.skills,
-                basePrompt: contextLevel === 'full' ? params.basePrompt : undefined,
-                tools: params.tools,
-                allowedTools: effectiveAllowedTools,
-                runtimeContext: params.runtimeContext,
-                contributions: promptContributions,
-            };
-            const segments = promptCache
-                ? promptCache.getSystemPromptSegmented(cacheInput, contextLevel, params.workingDirectory)
-                : promptBuilder.buildSegmented(contextLevel, params.workingDirectory);
-            ctx.log.info('Prompt segments assembled', {
-                'namzu.runtime.static_length': segments.static.length,
-                'namzu.runtime.dynamic_length': segments.dynamic.length,
+            ctx.log.warn('Capability mismatch: the provider declares no document support', {
+                'namzu.capability.detail': message,
+                [GENAI.SYSTEM]: params.provider.id,
+                'namzu.runtime.document_message_count': documentMessageCount,
             });
-            const pushSystemMessages = () => {
-                ctx.runMgr.pushMessage(createSystemMessage(segments.static, 'cache'));
-                if (segments.dynamic.length > 0) {
-                    ctx.runMgr.pushMessage(createSystemMessage(segments.dynamic, 'ephemeral'));
+        }
+        // Denied names are subtracted LAST, after the allow-list is resolved
+        // against the registry — so a deny reaches a turn that named no
+        // allow-list at all, which is the ordinary case for a delegated child.
+        // Applied to `effectiveAllowedTools`, which `query()` binds to both the
+        // request tool list AND the `ToolExecutor`: narrowing only the request
+        // shows the model fewer tools and lets it call any of them by name.
+        const allowedBeforeDenial = stripToolSurfaces
+            ? []
+            : withDeferredDiscoveryTool(params.tools, params.allowedTools);
+        const denied = new Set(params.deniedTools ?? []);
+        const effectiveAllowedTools = denied.size === 0
+            ? allowedBeforeDenial
+            : // An absent allow-list means "every registered tool", so a deny
+                // with no allow-list has to be resolved against the registry
+                // here — otherwise the subtraction would be from an empty list
+                // and would deny nothing, which is the shape a delegated child
+                // arrives in.
+                [...(allowedBeforeDenial ?? params.tools.listNames())].filter((name) => !denied.has(name));
+        // The two halves of a durable pause, owned by the TURN when the host
+        // does not own them.
+        //
+        // `SupervisorAgent` builds both before the turn exists, because the
+        // tools it builds close over them, and it passes them in. Nothing else
+        // could: neither type is exported from `public-runtime.ts`, so a host
+        // on `ReactiveAgent`, `drainQuery` or `resumeSession` had no way to supply
+        // either — and `ToolContext.requestPause`, which every tool author is
+        // handed, silently wrote no checkpoint and could receive no answer on
+        // those surfaces. Which agent class the host happened to pick is not
+        // visible at the call site, so the degradation was invisible too.
+        //
+        // A run-local pair is enough for the general seam because `query()`
+        // builds its `createToolPause` itself, below, and can hand it the
+        // run's own. Pinned by the "a pause is durable on any surface" cases
+        // in `__tests__/tool-pause-resume.test.ts`.
+        const questionParks = params.questionParks ?? new QuestionParkBinding();
+        const pendingAnswers = params.pendingAnswers ?? new PendingAnswers();
+        // One gate instance owns both model-issued calls and calls dispatched by
+        // another tool. Constructing it only inside the iteration review left the
+        // nested registry path outside the operator's policy entirely.
+        const gateConfig = params.authorizationGate;
+        const verificationGate = gateConfig?.enabled
+            ? new AuthorizationGate(gateConfig, ctx.log)
+            : undefined;
+        // Oversized tool output is spilled beside the session log
+        // (`<session-id>/tool-results/`). An in-memory session has nowhere to
+        // spill it, so the ordinary output budget applies.
+        const toolOutputDir = () => ctx.toolResultsDir;
+        // The same invocation-owned capability serves tools and optional preparation.
+        // Local cancellation cannot override the turn's cancellation or settled state.
+        const captureSessionEvidence = async (maxReadBytes, signal) => {
+            const combined = signal
+                ? AbortSignal.any([ctx.abortController.signal, signal])
+                : ctx.abortController.signal;
+            combined.throwIfAborted();
+            const source = await eventTranslator.captureSessionEvidence(maxReadBytes, combined);
+            combined.throwIfAborted();
+            return source;
+        };
+        // Whose jobs this turn 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.turnId;
+        // 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 turn 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,
+            sessionId: ctx.sessionId,
+            turnId: ctx.turnId,
+            workingDirectory: ctx.cwd,
+            ...(params.additionalDirectories?.length
+                ? { additionalDirectories: params.additionalDirectories }
+                : {}),
+            ...(params.outsideRootAccess ? { outsideRootAccess: params.outsideRootAccess } : {}),
+            ...(params.sandboxEscape ? { sandboxEscape: params.sandboxEscape } : {}),
+            permissionMode: () => ctx.permissionMode.current,
+            env: turnConfig.env ?? {},
+            abortSignal: ctx.abortController.signal,
+            allowedTools: effectiveAllowedTools,
+            invocationState: params.invocationState,
+            pluginManager: params.pluginManager,
+            ...(params.backgroundJobs ? { backgroundJobs: params.backgroundJobs } : {}),
+            ...(params.backgroundJobOwner ? { backgroundJobOwner: params.backgroundJobOwner } : {}),
+            ...(awaitedJobs ? { onJobAwaited: (id) => awaitedJobs.expect(id) } : {}),
+            // The `skill` tool's registry. Threaded from the turn rather than
+            // held by the tool, because a tool that reached for a module-level
+            // registry would answer about whatever the last turn configured.
+            ...(params.skillRegistry ? { skills: params.skillRegistry } : {}),
+            ...(params.web ? { web: params.web } : {}),
+            ...(params.fileReadTracker ? { fileReadTracker: params.fileReadTracker } : {}),
+            ...(params.toolTimeoutMs !== undefined ? { toolTimeoutMs: params.toolTimeoutMs } : {}),
+            ...(params.toolRetryBackoff !== undefined
+                ? { toolRetryBackoff: params.toolRetryBackoff }
+                : {}),
+            ...(params.maxToolCalls !== undefined
+                ? {
+                    maxToolCalls: params.maxToolCalls,
+                    readToolCallBudgetRecords: () => eventTranslator.readRecords({ mode: 'strict' }),
                 }
-            };
-            if (params.resumeFromCheckpoint) {
-                const checkpoint = await checkpointMgr.restore(params.resumeFromCheckpoint);
-                const projectedCheckpoint = {
-                    ...checkpoint,
-                    messages: projectStateBearingHistory(checkpoint.messages, {
-                        pinCompaction: false,
-                    }),
+                : {}),
+            ...(params.maxToolConcurrency !== undefined
+                ? { maxToolConcurrency: params.maxToolConcurrency }
+                : {}),
+            ...(params.maxToolOutputChars !== undefined
+                ? { maxToolOutputChars: params.maxToolOutputChars }
+                : {}),
+            ...(params.toolResultGuardrails !== undefined
+                ? { toolResultGuardrails: params.toolResultGuardrails }
+                : {}),
+            ...(params.retainedToolPreviewChars !== undefined
+                ? { retainedToolPreviewChars: params.retainedToolPreviewChars }
+                : {}),
+            ...(params.maxToolContentBytes !== undefined
+                ? { maxToolContentBytes: params.maxToolContentBytes }
+                : {}),
+            // Overflow lands beside the turn's other artifacts, so it is
+            // cleaned up with the turn and reachable by the model's own
+            // `read`/`grep` without a new affordance.
+            toolOutputDir,
+            captureSessionEvidence,
+            ...(params.repairToolCall ? { repairToolCall: params.repairToolCall } : {}),
+            ...(verificationGate ? { authorizationGate: verificationGate } : {}),
+            recordAudit: (input) => ctx.recorder.recordAudit(input),
+            // The durable pause, reachable from any tool rather than from the
+            // four kernel-owned points that used to own it. Built here from
+            // the machinery the turn already holds; the recorder binds a few
+            // lines below, and until it does a pause is in-process only —
+            // the same degradation the built-in question tool has.
+            toolPause: (toolUseId) => createToolPause({
+                sessionId: ctx.sessionId,
+                turnId: ctx.turnId,
+                toolUseId,
+                parkHandler: (request) => approvalPolicy.current.handler(request),
+                recorder: questionParks,
+                pendingAnswers,
+            }),
+        }, ctx.activityStore, eventTranslator.emitEvent, 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 turn's jobs are bound to, so a session-owned job that
+        // ends during this turn is reported here too.
+        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',
+                turnId: ctx.turnId,
+                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;
+        // 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 turn'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,
+            skills: params.skills,
+            basePrompt: params.basePrompt,
+            tools: params.tools,
+            allowedTools: effectiveAllowedTools,
+            runtimeContext: params.runtimeContext,
+            contributions: promptContributions,
+        });
+        const guard = new GuardCoordinator({
+            tokenBudget: turnConfig.tokenBudget,
+            timeoutMs: turnConfig.timeoutMs,
+            costLimitUsd: turnConfig.costLimitUsd,
+            maxIterations: turnConfig.maxIterations,
+        });
+        const checkpointMgr = new CheckpointManager(ctx.recorder, ctx.storage.checkpoints, {
+            tenantId: ctx.tenantId,
+            projectId: ctx.projectId,
+            sessionId: ctx.sessionId,
+            turnId: ctx.turnId,
+        });
+        // Every checkpoint carries compaction's accumulated state, so a turn that
+        // comes back in a new process can adopt it (see the restore block).
+        // Without it, compaction's own justification for dropping the prior
+        // `[COMPACTED CONTEXT]` block — that `serializeState` is cumulative —
+        // holds within one process and fails across a resume.
+        if (workingStateManager) {
+            const manager = workingStateManager;
+            checkpointMgr.setWorkingStateSource(() => snapshotWorkingState(manager));
+        }
+        const resultAssembler = new ResultAssembler({
+            recorder: ctx.recorder,
+            planManager: ctx.planManager,
+            activityStore: ctx.activityStore,
+            log: ctx.log,
+            emitEvent: eventTranslator.emitEvent,
+            drainPending: () => eventTranslator.drainPending(),
+            // Read at settle time, not now: checkpoints are written per
+            // iteration, so the answer changes as the turn proceeds. A turn
+            // that fails before writing one (a 429 on its first request)
+            // commits the state its loop began from, so it pauses like any
+            // later failure rather than failing with nothing to resume.
+            resumeCheckpointId: async () => checkpointMgr.lastCheckpointId ?? (await checkpointMgr.createAtLoopStart(ctx.recorder))?.id,
+            // Read only to recover WHY a cancellation happened. The turn loop
+            // already knows THAT it was cancelled; the origin lives on the abort
+            // reason and nothing else carries it this far.
+            signal: ctx.abortController.signal,
+        });
+        let advisoryCtx;
+        if (params.advisory && params.advisory.advisors.length > 0) {
+            // Advisors are model calls owned by this turn even when they use a
+            // different provider. Sending the raw definitions into the registry
+            // lets a triggered or model-requested consultation bypass both the
+            // finite stream-silence bound and Stop. Bind every advisor provider at
+            // the query boundary, where the effective timeout and run signal are
+            // already known; standalone AdvisoryExecutor callers retain their
+            // explicitly chosen provider/cancellation policy.
+            const boundedAdvisors = params.advisory.advisors.map((advisor) => ({
+                ...advisor,
+                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
+            // silently ignored for the length of the turn.
+            assertBudgetEnforceable(params.advisory);
+            const advisoryExecutor = new AdvisoryExecutor(ctx.log, params.advisory.budget, ctx.abortController.signal);
+            const triggerEvaluator = new TriggerEvaluator(params.advisory.triggers ?? [], params.advisory.budget);
+            advisoryCtx = new AdvisoryContext(advisorRegistry, advisoryExecutor, triggerEvaluator, params.advisory.budget);
+            // What the turn looks like when the MODEL consults an advisor, as
+            // opposed to when a trigger does. The trigger path has always passed
+            // this; the tool path passed an empty context, so an advisor the model
+            // asked for help saw the question and nothing else.
+            //
+            // `includeToolCatalog` and `useCompactedContext` are read here and
+            // nowhere else. Both were declared on `AdvisoryConfig` /
+            // `AdvisorDefinition` and consulted by nothing, so a host who turned
+            // the catalogue off still paid for it in every advisory prompt.
+            const advisoryConfig = params.advisory;
+            advisoryCtx.setCallContextProvider(() => {
+                const summary = workingStateManager && advisoryConfig.advisors.some((a) => a.useCompactedContext)
+                    ? serializeWorkingState(workingStateManager.getState())
+                    : undefined;
+                return {
+                    messages: ctx.recorder.messages,
+                    turn: iterationOrchestrator.getAdvisoryTurnContext(),
+                    ...(summary !== undefined ? { workingStateSummary: summary } : {}),
+                    ...(advisoryConfig.includeToolCatalog
+                        ? { toolCatalog: params.tools.toLLMTools(effectiveAllowedTools) }
+                        : {}),
+                    iteration: ctx.recorder.currentIteration,
                 };
-                await eventTranslator.emitEvent({
-                    type: 'run_resuming',
-                    runId: ctx.runMgr.id,
-                    fromCheckpointId: checkpoint.id,
-                });
-                yield* eventTranslator.drainPending();
-                // Budgets are properties of the RUN, not of the process hosting
-                // it. The checkpoint already carried all three; they were
-                // written and then discarded on the way back in, so a run
-                // recalled at $4.80 of a $5 cap came back with a fresh $5 and
-                // a fresh timeout clock. Restore before the first iteration so
-                // a resumed run that is already over budget stops immediately.
-                ctx.runMgr.restoreUsage(checkpoint.tokenUsage, checkpoint.costInfo, checkpoint.guardState.iterationCount);
-                guard.restoreElapsed(checkpoint.guardState.elapsedMs);
-                // Adopt the working state the earlier summary was built from.
-                // The `[COMPACTED CONTEXT]` block below is preserved precisely
-                // because it is the only surviving record of the history the
-                // first pass deleted — and without this, the NEXT compaction
-                // 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 && 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,
-                        'namzu.checkpoint.id': checkpoint.id,
-                        'namzu.runtime.slots': workingStateManager.slotCount(),
-                    });
+            });
+            if (params.advisory.enableAgentTool) {
+                const advisoryTools = buildAdvisoryTools({ advisoryCtx });
+                const overrides = params.runtimeToolOverrides;
+                for (const tool of advisoryTools) {
+                    const override = overrides?.[tool.name];
+                    if (override === 'disabled')
+                        continue;
+                    params.tools.register(tool, override ?? 'active');
                 }
-                ctx.log.info('Restored budgets from checkpoint', {
-                    [NAMZU.RUN_ID]: ctx.runMgr.id,
-                    'namzu.checkpoint.id': checkpoint.id,
-                    'namzu.usage.total_tokens': checkpoint.tokenUsage.totalTokens,
-                    'namzu.runtime.total_cost': checkpoint.costInfo.totalCost,
-                    [NAMZU.ITERATION]: checkpoint.guardState.iterationCount,
-                    'namzu.runtime.elapsed_ms': checkpoint.guardState.elapsedMs,
-                });
-                pushSystemMessages();
-                // A human answered the park in a different process; apply that
-                // answer to the tool calls they were actually shown. Without
-                // this the repair below throws the approval away and the model
-                // re-decides, so "yes, delete that row" degrades into "ask
-                // again and hope it asks for the same thing".
-                pendingResume =
-                    params.pendingDecision && projectedCheckpoint.pending
-                        ? planPendingResume(projectedCheckpoint, params.pendingDecision, ctx.log)
-                        : null;
-                // The park this resume ANSWERS even though there is no plan to
-                // carry the decision out through.
-                //
-                // `planPendingResume` covers the two arms whose decision has to
-                // reach something — the calls a `tool_review` park is about, the
-                // tool a `user_question` park is inside. An `iteration_checkpoint`
-                // park has neither, so it returns no plan, and the unpark further
-                // down — which ran only when there was one — never fired for it.
-                // A run that parked on the cadence, was resumed with
-                // `{action: 'continue'}` and went on to finish its work therefore
-                // kept reporting an OUTSTANDING park to `findPendingCheckpoint`,
-                // so a second resume of the finished run was refused with
-                // `awaiting-decision` for a decision already taken, and because
-                // `prune` skips an unresolved park the row could no longer be
-                // collected by anything.
-                //
-                // The decision IS carried out here — continuing is exactly what
-                // the loop below does, and a plan verdict is the answer to the
-                // question the plan park asked — so the park is resolved at the
-                // same point and with the same meaning "resolved" carries
-                // everywhere else: the record stays, and only its pending state
-                // ends. A `pause` is deliberately not resolved: it holds the
-                // park rather than answering it, which is how the live path
-                // treats it too. `answersParkOf` is the whole map, park type to
-                // answering decision, so an arm cannot go missing by being
-                // absent from a condition again — which is how the plan arm
-                // leaked a finished run's park.
-                //
-                // Resolving it does not depend on the resumed process being able
-                // to act on it, and that is deliberate: the plan's own fate is a
-                // separate defect (nothing restores a plan on the resume path at
-                // all, so the new process has none to approve, execute or
-                // reject) and making the resolution wait for it would leave the
-                // row outstanding for exactly the runs that need it cleared.
-                const parked = projectedCheckpoint.pending;
-                answeredParkId =
-                    params.pendingDecision &&
-                        parked !== undefined &&
-                        parked.resolvedAt === undefined &&
-                        answersParkOf(parked.request.type, params.pendingDecision)
-                        ? projectedCheckpoint.id
-                        : undefined;
-                // Recover completed observations and explicitly unknown outcomes.
-                // A recorded start is not proof that its external effect failed.
-                const unanswered = interruptedToolCalls(projectedCheckpoint.messages);
-                recoveredResults =
-                    unanswered.length > 0
-                        ? await recoverCompletedCalls(ctx.runMgr, unanswered, ctx.log, {
-                            answers: pendingResume?.answers,
-                            signal: ctx.abortController.signal,
-                        })
-                        : new Map();
-                // Preserve both known and unknown outcomes before continuing calls
-                // whose absence of a start was established by a complete scan.
-                if (!pendingResume && recoveredResults.size > 0) {
-                    pendingResume = planCrashResume(projectedCheckpoint, recoveredResults, ctx.log);
+            }
+        }
+        const iterationOrchestrator = new IterationOrchestrator({
+            captureSessionEvidence,
+            provider: resilientProvider,
+            providerCapabilities: capabilities,
+            strictCapabilities: params.strictCapabilities === true,
+            servingMember: () => serving.current,
+            turnConfig,
+            ...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),
+            ...(params.prepareStep ? { prepareStep: params.prepareStep } : {}),
+            ...(params.beforeStep ? { beforeStep: params.beforeStep } : {}),
+            ...(params.onStepFinish ? { onStepFinish: params.onStepFinish } : {}),
+            ...(params.reviewAnswer ? { reviewAnswer: params.reviewAnswer } : {}),
+            ...(params.maxAnswerReviews !== undefined
+                ? { maxAnswerReviews: params.maxAnswerReviews }
+                : {}),
+            ...(params.structuredOutput ? { structuredOutput: params.structuredOutput } : {}),
+            ...(params.parkRecordDelayMs !== undefined
+                ? { parkRecordDelayMs: params.parkRecordDelayMs }
+                : {}),
+            tools: params.tools,
+            allowedTools: effectiveAllowedTools,
+            recorder: ctx.recorder,
+            toolExecutor,
+            guard,
+            activityStore: ctx.activityStore,
+            emitEvent: eventTranslator.emitEvent,
+            drainPending: () => eventTranslator.drainPending(),
+            abortController: ctx.abortController,
+            log: ctx.log,
+            // Read through the box on every call, so a swap lands on the next
+            // question rather than the next turn.
+            resumeHandler: (request) => approvalPolicy.current.handler(request),
+            takeApprovalPolicyChange: () => approvalPolicy.takeUnannouncedChange(),
+            promptContributions,
+            ...(params.steering ? { steering: params.steering } : {}),
+            ...(jobNotices ? { jobNotices } : {}),
+            ...(awaitedJobs ? { awaitedJobs } : {}),
+            checkpointMgr,
+            planManager: ctx.planManager,
+            taskGateway: taskScheduler,
+            completionInbox: params.completionInbox,
+            taskStore: params.taskStore,
+            // Turn-scoped. An approval is a statement about this turn's work;
+            // carrying one into a later turn would be reuse nobody agreed to.
+            toolGrants: new ToolGrantSet(),
+            ...(params.reviewAllowedCalls ? { reviewAllowedCalls: params.reviewAllowedCalls } : {}),
+            // Turn-scoped for the same reason. A repeat count carried into a later
+            // 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.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
+            ...(params.resumeFromCheckpoint ? { resumedInput: queuedForThisRun } : {}),
+            ...(params.waitForInbound ? { waitForInbound: params.waitForInbound } : {}),
+            ...(params.projectInstructionContext
+                ? { projectInstructionContext: params.projectInstructionContext }
+                : {}),
+            ...(providerContextWindow !== undefined ? { providerContextWindow } : {}),
+            resolveModelContextWindow: async (model) => {
+                if (!modelContextWindows.has(model)) {
+                    modelContextWindows.set(model, await resolveProviderContextWindow(resilientProvider, model, ctx.abortController.signal, turnConfig.timeoutMs, log));
                 }
-                // An incomplete turn with a durable owner is NOT abandoned. A
-                // pending decision or crash-resume plan re-appends that exact
-                // assistant with real/denied/recovered results below. Remove it
-                // from the generic pass so no synthetic result competes with the
-                // authority that still owns the call. Everything else is abandoned
-                // history and is repaired conservatively rather than deleted.
-                const abandonedCheckpointMessages = pendingResume
-                    ? withoutOwnedResumeTurn(projectedCheckpoint.messages, pendingResume.assistant)
-                    : projectedCheckpoint.messages;
-                const checkpointRepair = repairToolMessageHistory(abandonedCheckpointMessages);
-                const restoredMessages = checkpointRepair.messages;
-                if (toolHistoryRepairChanged(checkpointRepair.report)) {
-                    pendingHistoryRepairs.push({
-                        source: 'abandoned-checkpoint',
-                        report: checkpointRepair.report,
+                return modelContextWindows.get(model);
+            },
+            workingStateManager,
+            taskRouter: params.taskRouter,
+            contextReducer: params.contextReducer,
+            workingMemoryProvider: params.workingMemoryProvider,
+            advisoryCtx,
+            agentBus: params.agentBus,
+            verificationGate,
+            pluginManager: params.pluginManager,
+        });
+        const tracer = getTracer();
+        // Whether the turn reached its settle. Read by the `finally` below, and
+        // the only thing that distinguishes a turn that finished from one whose
+        // consumer walked away — see `settleAbandonedTurn`.
+        let settled = false;
+        const runBody = (async function* () {
+            // Parent explicitly when a caller supplied one. Without this every
+            // run starts its OWN root trace, so a supervisor delegating to three
+            // children produced four disconnected traces instead of one tree —
+            // the same defect that made a 20-turn run show up as 21 roots before
+            // iterations were parented, except across the spawn boundary, where
+            // it is worse: the delegation structure is the thing you most want
+            // to see.
+            const runStartedAt = Date.now();
+            // Read before the span is minted, because a parent can only be set
+            // at creation. A resumed turn used to start a brand-new trace with no
+            // link to the one that crashed, so the failure and its recovery
+            // could not be put on one timeline — the turn id correlated them well
+            // enough to find both by query and not well enough to see a single
+            // waterfall, and for a replay fork (which mints a new turn id) not
+            // even that. An explicit caller-supplied parent still wins: it is
+            // the more specific statement about where this turn belongs.
+            const resumedTrace = selectedResumeState
+                ? selectedResumeState.traceContext
+                : params.resumeFromCheckpoint
+                    ? await checkpointMgr.readTraceContext(params.resumeFromCheckpoint)
+                    : undefined;
+            const rootSpan = tracer.startSpan(agentTurnSpanName(params.agentName), {}, parentContext(params.parentSpan ?? resumedTrace));
+            // Hand the turn span to the loop so every iteration parents to it.
+            iterationOrchestrator.setRootSpan(rootSpan);
+            // Every checkpoint from here on records the trace it was taken
+            // inside, so the next resume can join this one.
+            checkpointMgr.setTraceSource(() => serializeSpan(rootSpan));
+            // And every park it records carries an absolute deadline, so an
+            // unanswered approval cannot outlive the worker that asked for it.
+            checkpointMgr.setParkTtl(turnConfig.hitlParkTtlMs);
+            // A question raised from inside a tool becomes a real checkpoint
+            // here. It used to park under a synthetic id nothing ever wrote, so
+            // the checkpoint did not exist: nothing on disk said a human owed
+            // this turn an answer, and a remote host could not observe the
+            // question at all.
+            questionParks.bind({
+                record: async (question) => {
+                    try {
+                        const checkpoint = await checkpointMgr.create(ctx.recorder, ctx.recorder.currentIteration);
+                        await checkpointMgr.park(checkpoint, {
+                            type: 'user_question',
+                            sessionId: ctx.sessionId,
+                            turnId: ctx.turnId,
+                            checkpointId: checkpoint.id,
+                            question,
+                        });
+                        await eventTranslator.emitEvent({
+                            type: 'user_question_asked',
+                            checkpointId: checkpoint.id,
+                            questionId: question.questionId,
+                            question: question.question,
+                        });
+                        return checkpoint.id;
+                    }
+                    catch (err) {
+                        // A store that cannot record the park must not take the
+                        // tool down with it: the in-process await is still valid
+                        // and only the cross-process handoff is lost. Loudly,
+                        // because a host building an approval queue from durable
+                        // state will not see this question.
+                        ctx.log.error('Failed to record a question park — it is not resumable', {
+                            [NAMZU.TURN_ID]: ctx.recorder.turnId,
+                            'namzu.runtime.question_id': question.questionId,
+                            'exception.message': err instanceof Error ? err.message : String(err),
+                        });
+                        return null;
+                    }
+                },
+                resolve: async (checkpointId, decision) => {
+                    await checkpointMgr.unpark(checkpointId, decision).catch((err) => {
+                        ctx.log.error('Failed to clear a recorded question park', {
+                            [NAMZU.TURN_ID]: ctx.recorder.turnId,
+                            'namzu.checkpoint.id': checkpointId,
+                            'exception.message': err instanceof Error ? err.message : String(err),
+                        });
+                        return null;
                     });
-                    ctx.log.warn('Repaired abandoned tool history while restoring a checkpoint', {
-                        [NAMZU.RUN_ID]: ctx.runMgr.id,
-                        'namzu.checkpoint.id': checkpoint.id,
-                        'namzu.history.source': 'abandoned-checkpoint',
-                        'namzu.history.duplicate_tool_results_removed': checkpointRepair.report.duplicateToolResultsRemoved,
-                        'namzu.history.orphaned_tool_results_removed': checkpointRepair.report.orphanedToolResultsRemoved,
-                        'namzu.history.synthetic_tool_results_inserted': checkpointRepair.report.syntheticToolResultsInserted,
+                    await eventTranslator.emitEvent({
+                        type: 'user_question_answered',
+                        checkpointId,
+                        ...(decision.action === 'answer_question' && decision.questionId !== undefined
+                            ? { questionId: decision.questionId }
+                            : {}),
+                        answered: decision.action === 'answer_question',
+                    });
+                },
+            });
+            rootSpan.setAttributes({
+                [GENAI.CONVERSATION_ID]: ctx.sessionId,
+                [NAMZU.TURN_ID]: ctx.recorder.turnId,
+                ...(params.parentSessionId !== undefined && {
+                    [NAMZU.SESSION_PARENT_ID]: params.parentSessionId,
+                }),
+                [GENAI.AGENT_NAME]: params.agentName,
+                [GENAI.AGENT_ID]: params.agentId,
+                [GENAI.REQUEST_MODEL]: turnConfig.model,
+                [GENAI.SYSTEM]: params.provider.id,
+            });
+            let sandbox;
+            // Decided during checkpoint restore, executed after the sandbox
+            // exists — the approved tools may well need it.
+            let pendingResume = null;
+            /** The record id of the parked assistant message the plan re-appends. */
+            let pendingResumeAssistantId;
+            /**
+             * The cadence park this resume answered, when the decision is one the
+             * ordinary continue path carries out. See the restore path below.
+             */
+            let answeredParkId;
+            /** Tool results recovered from the transcript; see the restore path. */
+            let recoveredResults = new Map();
+            try {
+                // A consumer coming back gets what it missed BEFORE the turn says
+                // anything new, which is the only order that lets it fold one
+                // stream into one state. It follows the prelude's `open()` — which
+                // took the lease and read the log's head — and precedes every emit
+                // below.
+                if (params.eventCursor) {
+                    yield* catchUpFromCursor(ctx.recorder, params.eventCursor, params.onEventReplay, (error) => {
+                        ctx.log.warn('Replay observer failed', {
+                            'exception.message': toErrorMessage(error),
+                        });
                     });
                 }
-                // 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);
+                ctx.log.info('Starting query', {
+                    [NAMZU.TURN_ID]: ctx.recorder.turnId,
+                    'namzu.runtime.agent': params.agentName,
+                    [GENAI.REQUEST_MODEL]: turnConfig.model,
+                    'namzu.runtime.token_budget': turnConfig.tokenBudget,
+                    'namzu.runtime.activity_tracking': ctx.activityStore.enabled,
+                    'namzu.runtime.permission_mode': ctx.permissionMode.current,
+                    'namzu.runtime.resume_from_checkpoint': params.resumeFromCheckpoint ?? null,
+                });
+                // The operator's prompt, before the model sees it. A hook may
+                // refuse it — the turn 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 turn carries it.
+                if (params.pluginManager) {
+                    const hookResults = await params.pluginManager.executeHooks('user_prompt_submit', {
+                        turnId: ctx.turnId,
+                        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();
                 }
-                catch (err) {
-                    // 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,
+                const contextLevel = params.contextLevel ?? 'full';
+                const cacheInput = {
+                    systemPrompt: params.systemPrompt,
+                    persona: params.persona,
+                    skills: params.skills,
+                    basePrompt: contextLevel === 'full' ? params.basePrompt : undefined,
+                    tools: params.tools,
+                    allowedTools: effectiveAllowedTools,
+                    runtimeContext: params.runtimeContext,
+                    contributions: promptContributions,
+                };
+                const segments = promptCache
+                    ? promptCache.getSystemPromptSegmented(cacheInput, contextLevel, params.workingDirectory)
+                    : promptBuilder.buildSegmented(contextLevel, params.workingDirectory);
+                ctx.log.info('Prompt segments assembled', {
+                    'namzu.runtime.static_length': segments.static.length,
+                    'namzu.runtime.dynamic_length': segments.dynamic.length,
+                });
+                // The prompt floor is rebuilt every turn and never recorded:
+                // `turn_started.systemPrompt` carries it.
+                const pushSystemMessages = () => {
+                    ctx.recorder.pushMessage(createSystemMessage(segments.static, 'cache'), {
+                        transient: true,
+                    });
+                    if (segments.dynamic.length > 0) {
+                        ctx.recorder.pushMessage(createSystemMessage(segments.dynamic, 'ephemeral'), {
+                            transient: true,
+                        });
+                    }
+                };
+                const pushRestored = (message, ids) => {
+                    const messageId = ids.get(message);
+                    ctx.recorder.pushMessage(message, messageId ? { messageId } : {});
+                };
+                if (params.resumeFromCheckpoint) {
+                    const checkpoint = await checkpointMgr.restore(params.resumeFromCheckpoint);
+                    const projectedCheckpoint = {
+                        ...checkpoint,
+                        messages: projectStateBearingHistory(checkpoint.messages, {
+                            pinCompaction: false,
+                        }),
+                    };
+                    await eventTranslator.resumeTurn(checkpoint.id);
+                    yield* eventTranslator.drainPending();
+                    // Budgets are properties of the TURN, not of the process hosting
+                    // it. The checkpoint already carried all three; they were
+                    // written and then discarded on the way back in, so a turn
+                    // recalled at $4.80 of a $5 cap came back with a fresh $5 and
+                    // a fresh timeout clock. Restore before the first iteration so
+                    // a resumed turn that is already over budget stops immediately.
+                    ctx.recorder.restoreUsage(checkpoint.document.tokenUsage, checkpoint.document.costInfo, checkpoint.document.guards.iteration);
+                    guard.restoreElapsed(checkpoint.document.guards.elapsedMs);
+                    // Adopt the working state the earlier summary was built from.
+                    // The `[COMPACTED CONTEXT]` block below is preserved precisely
+                    // because it is the only surviving record of the history the
+                    // first pass deleted — and without this, the NEXT compaction
+                    // would drop it and replace it with a summary covering only
+                    // what happened after the resume, silently losing the turn's
+                    // first hour.
+                    if (workingStateManager && checkpoint.document.workingState && compactionConfig) {
+                        const revived = restoreWorkingState(checkpoint.document.workingState, compactionConfig);
+                        workingStateManager.replaceState(revived.getState());
+                        ctx.log.info('Restored compaction working state from checkpoint', {
+                            [NAMZU.TURN_ID]: ctx.recorder.turnId,
+                            'namzu.checkpoint.id': checkpoint.id,
+                            'namzu.runtime.slots': workingStateManager.slotCount(),
+                        });
+                    }
+                    ctx.log.info('Restored budgets from checkpoint', {
+                        [NAMZU.TURN_ID]: ctx.recorder.turnId,
                         'namzu.checkpoint.id': checkpoint.id,
-                        'exception.message': err instanceof Error ? err.message : String(err),
+                        'namzu.usage.total_tokens': checkpoint.document.tokenUsage.totalTokens,
+                        'namzu.runtime.total_cost': checkpoint.document.costInfo.totalCost,
+                        [NAMZU.ITERATION]: checkpoint.document.guards.iteration,
+                        'namzu.runtime.elapsed_ms': checkpoint.document.guards.elapsedMs,
                     });
-                }
-                for (const msg of restoredMessages) {
-                    if (msg.role === 'system') {
-                        // Re-push the FRESH static/dynamic floor (done above) but PRESERVE
-                        // the two system messages that carry irreplaceable run state: the
-                        // `[COMPACTED CONTEXT]` summary is the only surviving record of the
-                        // older history a compaction pass deleted, and the working-memory
-                        // slot pins the produced-artifact ledger. Dropping every system
-                        // message on restore silently lost both on resume.
-                        if (isCompactionMessage(msg.content) || isWorkingMemoryMessage(msg.content)) {
-                            ctx.runMgr.pushMessage(msg);
+                    pushSystemMessages();
+                    // A human answered the park in a different process; apply that
+                    // answer to the tool calls they were actually shown. Without
+                    // this the repair below throws the approval away and the model
+                    // re-decides, so "yes, delete that row" degrades into "ask
+                    // again and hope it asks for the same thing".
+                    pendingResume =
+                        params.pendingDecision && projectedCheckpoint.pending
+                            ? planPendingResume(projectedCheckpoint, params.pendingDecision, ctx.log)
+                            : null;
+                    // The park this resume ANSWERS even though there is no plan to
+                    // carry the decision out through.
+                    //
+                    // `planPendingResume` covers the two arms whose decision has to
+                    // reach something — the calls a `tool_review` park is about, the
+                    // tool a `user_question` park is inside. An `iteration_checkpoint`
+                    // park has neither, so it returns no plan, and the unpark further
+                    // down — which ran only when there was one — never fired for it.
+                    // A turn that parked on the cadence, was resumed with
+                    // `{action: 'continue'}` and went on to finish its work therefore
+                    // kept reporting an OUTSTANDING park to `findPendingCheckpoint`,
+                    // so a second resume of the finished turn was refused with
+                    // `awaiting-decision` for a decision already taken, and because
+                    // `prune` skips an unresolved park the row could no longer be
+                    // collected by anything.
+                    //
+                    // The decision IS carried out here — continuing is exactly what
+                    // the loop below does, and a plan verdict is the answer to the
+                    // question the plan park asked — so the park is resolved at the
+                    // same point and with the same meaning "resolved" carries
+                    // everywhere else: the record stays, and only its pending state
+                    // ends. A `pause` is deliberately not resolved: it holds the
+                    // park rather than answering it, which is how the live path
+                    // treats it too. `answersParkOf` is the whole map, park type to
+                    // answering decision, so an arm cannot go missing by being
+                    // absent from a condition again — which is how the plan arm
+                    // leaked a finished turn's park.
+                    //
+                    // Resolving it does not depend on the resumed process being able
+                    // to act on it, and that is deliberate: the plan's own fate is a
+                    // separate defect (nothing restores a plan on the resume path at
+                    // all, so the new process has none to approve, execute or
+                    // reject) and making the resolution wait for it would leave the
+                    // row outstanding for exactly the turns that need it cleared.
+                    const parked = projectedCheckpoint.pending;
+                    answeredParkId =
+                        params.pendingDecision &&
+                            parked !== undefined &&
+                            parked.resolvedAt === undefined &&
+                            answersParkOf(parked.request.type, params.pendingDecision)
+                            ? projectedCheckpoint.id
+                            : undefined;
+                    // Recover completed observations and explicitly unknown outcomes.
+                    // A recorded start is not proof that its external effect failed.
+                    const unanswered = interruptedToolCalls(projectedCheckpoint.messages);
+                    recoveredResults =
+                        unanswered.length > 0
+                            ? await recoverCompletedCalls(ctx.recorder, unanswered, ctx.log, {
+                                answers: pendingResume?.answers,
+                                signal: ctx.abortController.signal,
+                            })
+                            : new Map();
+                    // Preserve both known and unknown outcomes before continuing calls
+                    // whose absence of a start was established by a complete scan.
+                    if (!pendingResume && recoveredResults.size > 0) {
+                        pendingResume = planCrashResume(projectedCheckpoint, recoveredResults, ctx.log);
+                    }
+                    // An incomplete turn with a durable owner is NOT abandoned. A
+                    // pending decision or crash-resume plan re-appends that exact
+                    // assistant with real/denied/recovered results below. Remove it
+                    // from the generic pass so no synthetic result competes with the
+                    // authority that still owns the call. Everything else is abandoned
+                    // history and is repaired conservatively rather than deleted.
+                    pendingResumeAssistantId = pendingResume
+                        ? checkpoint.messageIds.get(pendingResume.assistant)
+                        : undefined;
+                    const abandonedCheckpointMessages = pendingResume
+                        ? withoutOwnedResumeTurn(projectedCheckpoint.messages, pendingResume.assistant)
+                        : projectedCheckpoint.messages;
+                    const checkpointRepair = repairToolMessageHistory(abandonedCheckpointMessages);
+                    const restoredMessages = checkpointRepair.messages;
+                    if (toolHistoryRepairChanged(checkpointRepair.report)) {
+                        pendingHistoryRepairs.push({
+                            source: 'abandoned-checkpoint',
+                            report: checkpointRepair.report,
+                        });
+                        ctx.log.warn('Repaired abandoned tool history while restoring a checkpoint', {
+                            [NAMZU.TURN_ID]: ctx.recorder.turnId,
+                            'namzu.checkpoint.id': checkpoint.id,
+                            'namzu.history.source': 'abandoned-checkpoint',
+                            'namzu.history.duplicate_tool_results_removed': checkpointRepair.report.duplicateToolResultsRemoved,
+                            'namzu.history.orphaned_tool_results_removed': checkpointRepair.report.orphanedToolResultsRemoved,
+                            'namzu.history.synthetic_tool_results_inserted': checkpointRepair.report.syntheticToolResultsInserted,
+                        });
+                    }
+                    // The ledger is process state and a resumed turn starts with an empty
+                    // one, so until something reads a file again this turn 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) {
+                        // A ledger that could not be rebuilt is the empty one every resume
+                        // used to get, so the turn 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.TURN_ID]: ctx.recorder.turnId,
+                            '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
+                            // the two system messages that carry irreplaceable run state: the
+                            // `[COMPACTED CONTEXT]` summary is the only surviving record of the
+                            // older history a compaction pass deleted, and the working-memory
+                            // slot pins the produced-artifact ledger. Dropping every system
+                            // message on restore silently lost both on resume.
+                            if (isCompactionMessage(msg.content) || isWorkingMemoryMessage(msg.content)) {
+                                pushRestored(msg, checkpoint.messageIds);
+                            }
+                            continue;
                         }
-                        continue;
+                        pushRestored(msg, checkpoint.messageIds);
                     }
-                    ctx.runMgr.pushMessage(msg);
+                    // The queue, on the resume path too. It is drained
+                    // unconditionally above, so leaving this out would take a
+                    // host's "start with this" off the record and deliver it
+                    // nowhere — the one outcome a durable queue must not have.
+                    //
+                    // AFTER the restored history rather than before it: on a
+                    // resume the conversation already exists, and a message left
+                    // for "the next turn" is the newest thing said, not the oldest.
+                    for (const queued of queuedForThisRun)
+                        ctx.recorder.pushMessage(queued);
                 }
-                // The queue, on the resume path too. It is drained
-                // unconditionally above, so leaving this out would take a
-                // host's "start with this" off the record and deliver it
-                // nowhere — the one outcome a durable queue must not have.
-                //
-                // AFTER the restored history rather than before it: on a
-                // resume the conversation already exists, and a message left
-                // for "the next run" is the newest thing said, not the oldest.
-                for (const queued of queuedForThisRun)
-                    ctx.runMgr.pushMessage(queued);
-            }
-            else if (params.continuationMode) {
-                for (const msg of initialMessages) {
-                    ctx.runMgr.pushMessage(msg);
+                else if (params.continuationMode) {
+                    for (const msg of initialMessages)
+                        pushRestored(msg, historyIds);
                 }
-            }
-            else {
-                pushSystemMessages();
-                for (const msg of initialMessages) {
-                    if (msg.role === 'system') {
-                        // A fresh run rebuilds its current static/dynamic prompt above,
-                        // so arbitrary historical system messages stay out. These two
-                        // are different: they are conversation STATE, and dropping them
-                        // deletes the only surviving record of compacted history or the
-                        // produced-artifact ledger. A compaction summary arriving from a
-                        // prior run is pinned because this new WorkingStateManager cannot
-                        // prove it has reconstructed equivalent state yet.
-                        if (isCompactionMessage(msg.content)) {
-                            ctx.runMgr.pushMessage({ ...msg, retain: true });
-                        }
-                        else if (isWorkingMemoryMessage(msg.content)) {
-                            ctx.runMgr.pushMessage(msg);
+                else {
+                    pushSystemMessages();
+                    for (const msg of initialMessages) {
+                        if (msg.role === 'system') {
+                            // A fresh turn rebuilds its current static/dynamic prompt above,
+                            // so arbitrary historical system messages stay out. These two
+                            // are different: they are conversation STATE, and dropping them
+                            // deletes the only surviving record of compacted history or the
+                            // produced-artifact ledger. A compaction summary arriving from a
+                            // prior turn is pinned because this new WorkingStateManager cannot
+                            // prove it has reconstructed equivalent state yet.
+                            if (isCompactionMessage(msg.content)) {
+                                // Pinned by the prelude already; a copy would lose its record id.
+                                pushRestored(msg.retain ? msg : { ...msg, retain: true }, historyIds);
+                            }
+                            else if (isWorkingMemoryMessage(msg.content)) {
+                                pushRestored(msg, historyIds);
+                            }
+                            continue;
                         }
-                        continue;
+                        pushRestored(msg, historyIds);
                     }
-                    ctx.runMgr.pushMessage(msg);
                 }
-            }
-            // Fresh and continuation histories seed the same operator state.
-            // A worker report or project-policy message may have role `user`,
-            // but it must not become the task or an operator requirement.
-            // Resume restores this state and adopts only its newer queue arrivals.
-            if (!params.resumeFromCheckpoint && workingStateManager) {
-                let isFirstUserMessage = true;
-                for (const message of initialMessages) {
-                    if (!isOperatorUserMessage(message) || !message.content.trim())
-                        continue;
-                    extractFromUserMessage(workingStateManager, message.content, isFirstUserMessage);
-                    isFirstUserMessage = false;
+                // Fresh and continuation histories seed the same operator state.
+                // A worker report or project-policy message may have role `user`,
+                // but it must not become the task or an operator requirement.
+                // Resume restores this state and adopts only its newer queue arrivals.
+                if (!params.resumeFromCheckpoint && workingStateManager) {
+                    let isFirstUserMessage = true;
+                    for (const message of initialMessages) {
+                        if (!isOperatorUserMessage(message) || !message.content.trim())
+                            continue;
+                        extractFromUserMessage(workingStateManager, message.content, isFirstUserMessage);
+                        isFirstUserMessage = false;
+                    }
+                }
+                const assembledPrompt = segments.dynamic.length > 0
+                    ? `${segments.static}\n\n---\n\n${segments.dynamic}`
+                    : segments.static;
+                ctx.recorder.markRunning();
+                // A resumed turn already began; `turn_resuming` above continued it.
+                if (!params.resumeFromCheckpoint) {
+                    await eventTranslator.beginTurn({
+                        systemPrompt: assembledPrompt,
+                        ...(params.origin ? { origin: params.origin } : {}),
+                        ...(params.abandonInterrupted ? { abandonInterrupted: true } : {}),
+                    });
                 }
-            }
-            const assembledPrompt = segments.dynamic.length > 0
-                ? `${segments.static}\n\n---\n\n${segments.dynamic}`
-                : segments.static;
-            ctx.runMgr.markRunning();
-            await eventTranslator.emitEvent({
-                type: 'run_started',
-                runId: ctx.runMgr.id,
-                systemPrompt: assembledPrompt,
-            });
-            yield* eventTranslator.drainPending();
-            // Pre-run materialization can observe cancellation before RunContext
-            // exists. The exact input has now been seeded and the run is writable;
-            // hand the cancellation to the normal terminal path before invoking
-            // any host callback, guardrail, plugin, sandbox, or provider. Those
-            // boundaries are not all cooperative and must not regain withdrawn
-            // authority merely because the run record still had to be created.
-            ctx.abortController.signal.throwIfAborted();
-            // Handed over here, and the position is load-bearing in three
-            // directions. It has to follow `wirePlanManager`, or a host that
-            // builds its plan in this callback does it into silence. It has to
-            // follow `runMgr.init()` and `run_started`, because plan events append
-            // to that durable run. It also has to follow the pre-model abort fence:
-            // a callback invoked after attachment resolution observed cancellation
-            // would regain withdrawn authority and could replace the cancellation
-            // with its own failure. This is still before the iteration loop, which
-            // is the guarantee the callback makes.
-            params.onContextCreated?.({ planManager: ctx.planManager });
-            // The box is handed out HERE, after `run_started`, and the position
-            // is load-bearing rather than tidy. It moved twice:
-            //
-            //  1. Beside the box's construction — a host that called `set`
-            //     synchronously reached `eventTranslator` inside its temporal
-            //     dead zone and killed the run before it started.
-            //  2. Beside the translator's construction — the translator existed,
-            //     but the run directory did not, so the durable append hit
-            //     ENOENT on `transcript.jsonl`.
-            //
-            // Both were found by the test that takes the box and immediately
-            // swaps the policy, which is not an exotic host: it is the shape of
-            // "start unattended" wiring. A policy change is durably recorded
-            // before it takes effect, so the handout cannot precede the run
-            // being writable.
-            params.onApprovalPolicy?.(approvalPolicy);
-            // History repair happens before the run manager sees the first model
-            // request, but its durable event cannot precede run_started: there is no
-            // writable run log until that event initializes it. Emit the measured
-            // counts here, still before any provider call, so hosts can tell that the
-            // model received a repaired projection rather than the raw history.
-            for (const repair of pendingHistoryRepairs) {
-                await eventTranslator.emitEvent({
-                    type: 'message_history_repaired',
-                    runId: ctx.runMgr.id,
-                    source: repair.source,
-                    ...repair.report,
-                });
-                yield* eventTranslator.drainPending();
-            }
-            // Surface capability degradation to the host as run events —
-            // explicit, not silent (the log.warn above fires at setup time;
-            // this is the machine-readable channel).
-            if (stripToolSurfaces) {
-                await eventTranslator.emitEvent({
-                    type: 'capability_warning',
-                    runId: ctx.runMgr.id,
-                    capability: 'tools',
-                    providerId: params.provider.id,
-                    message: `Provider '${params.provider.id}' does not support tools — ${registeredToolCount} registered tool(s) were stripped from the prompt and request.`,
-                });
-                yield* eventTranslator.drainPending();
-            }
-            if (attachmentMessageCount > 0) {
-                await eventTranslator.emitEvent({
-                    type: 'capability_warning',
-                    runId: ctx.runMgr.id,
-                    capability: 'vision',
-                    providerId: params.provider.id,
-                    message: `Provider '${params.provider.id}' does not support vision — image attachments on ${attachmentMessageCount} user message(s) will not reach the model.`,
-                });
-                yield* eventTranslator.drainPending();
-            }
-            if (documentMessageCount > 0) {
-                await eventTranslator.emitEvent({
-                    type: 'capability_warning',
-                    runId: ctx.runMgr.id,
-                    capability: 'documents',
-                    providerId: params.provider.id,
-                    message: `Provider '${params.provider.id}' does not support documents — document attachments on ${documentMessageCount} user message(s) will not reach the model.`,
-                });
-                yield* eventTranslator.drainPending();
-            }
-            if (params.pluginManager) {
-                const hookResults = await params.pluginManager.executeHooks('run_start', { runId: ctx.runId, signal: ctx.abortController.signal }, eventTranslator.emitEvent);
-                applyLifecycleHookResults('run_start', hookResults);
                 yield* eventTranslator.drainPending();
-            }
-            // --- Sandbox lifecycle: create before iteration loop ---
-            if (params.sandboxProvider) {
-                const rootAtCwd = runConfig.sandbox?.workspace === 'working-directory';
-                // Checked against what the CALLER passed, not against `ctx.cwd`.
-                // `ctx.cwd` falls back to `process.cwd()`, so reading it here
-                // would silently root the sandbox at whatever directory the
-                // host process happens to be in — which is not the directory
-                // anybody asked to confine, and is worse than the temp dir the
-                // caller declined. Refused before the sandbox exists, and not
-                // downgraded to ephemeral: a caller who asked for confinement
-                // of a specific tree and quietly got an empty one has been
-                // told their files are protected by something that is not
-                // looking at them.
-                if (rootAtCwd && params.workingDirectory === undefined) {
-                    throw new NamzuError({
-                        code: 'invalid_config',
-                        message: "sandbox.workspace is 'working-directory' but this run has no workingDirectory. Pass one, or use the default 'ephemeral' — the kernel will not fall back to a temp directory, because that would confine a directory you did not name.",
-                        details: { workspace: 'working-directory' },
+                // Pre-run materialization can observe cancellation before TurnContext
+                // exists. The exact input has now been seeded and the turn is writable;
+                // hand the cancellation to the normal terminal path before invoking
+                // any host callback, guardrail, plugin, sandbox, or provider. Those
+                // boundaries are not all cooperative and must not regain withdrawn
+                // authority merely because the turn record still had to be created.
+                ctx.abortController.signal.throwIfAborted();
+                // Handed over here, and the position is load-bearing in three
+                // directions. It has to follow `wirePlanManager`, or a host that
+                // builds its plan in this callback does it into silence. It has to
+                // follow `recorder.init()` and `turn_started`, because plan events append
+                // to that durable turn. It also has to follow the pre-model abort fence:
+                // a callback invoked after attachment resolution observed cancellation
+                // would regain withdrawn authority and could replace the cancellation
+                // with its own failure. This is still before the iteration loop, which
+                // is the guarantee the callback makes.
+                params.onContextCreated?.({ planManager: ctx.planManager });
+                // The box is handed out HERE, after `turn_started`, and the position
+                // is load-bearing rather than tidy. It moved twice:
+                //
+                //  1. Beside the box's construction — a host that called `set`
+                //     synchronously reached `eventTranslator` inside its temporal
+                //     dead zone and killed the turn before it started.
+                //  2. Beside the translator's construction — the translator existed,
+                //     but the turn directory did not, so the durable append hit
+                //     ENOENT on `transcript.jsonl`.
+                //
+                // Both were found by the test that takes the box and immediately
+                // swaps the policy, which is not an exotic host: it is the shape of
+                // "start unattended" wiring. A policy change is durably recorded
+                // before it takes effect, so the handout cannot precede the turn
+                // being writable.
+                params.onApprovalPolicy?.(approvalPolicy);
+                // History repair happens before the turn manager sees the first model
+                // request, but its durable event cannot precede turn_started: there is no
+                // writable run log until that event initializes it. Emit the measured
+                // counts here, still before any provider call, so hosts can tell that the
+                // model received a repaired projection rather than the raw history.
+                for (const repair of pendingHistoryRepairs) {
+                    await eventTranslator.emitEvent({
+                        type: 'message_history_repaired',
+                        turnId: ctx.recorder.turnId,
+                        source: repair.source,
+                        ...repair.report,
                     });
+                    yield* eventTranslator.drainPending();
                 }
-                if (rootAtCwd && !params.sandboxProvider.workspaceModes?.includes('working-directory')) {
-                    throw new NamzuError({
-                        code: 'invalid_config',
-                        message: `Sandbox provider '${params.sandboxProvider.id}' does not advertise working-directory workspace support. Refusing instead of passing a project path the provider may ignore.`,
-                        details: {
-                            providerId: params.sandboxProvider.id,
-                            workspace: 'working-directory',
-                        },
+                // Surface capability degradation to the host as run events —
+                // explicit, not silent (the log.warn above fires at setup time;
+                // this is the machine-readable channel).
+                if (stripToolSurfaces) {
+                    await eventTranslator.emitEvent({
+                        type: 'capability_warning',
+                        turnId: ctx.recorder.turnId,
+                        capability: 'tools',
+                        providerId: params.provider.id,
+                        message: `Provider '${params.provider.id}' does not support tools — ${registeredToolCount} registered tool(s) were stripped from the prompt and request.`,
                     });
+                    yield* eventTranslator.drainPending();
                 }
-                const acquisition = await acquireSandbox({
-                    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,
-                    },
-                    signal: ctx.abortController.signal,
-                    timeoutMs: guard.remainingUntilTimeoutMs(),
-                    teardownTimeoutMs: sandboxTeardownTimeoutMs,
-                    onLateTeardown: (result) => {
-                        if (result.kind === 'destroyed') {
-                            ctx.log.info('Late sandbox allocation was destroyed after the run stopped', {
-                                [NAMZU.RUN_ID]: ctx.runId,
-                            });
-                            return;
-                        }
-                        ctx.log.error('Late sandbox allocation did not stop cleanly', {
-                            [NAMZU.RUN_ID]: ctx.runId,
-                            ...errorAttributes(result.error),
-                        });
-                    },
-                });
-                if (acquisition.kind !== 'created') {
-                    if (acquisition.createPending) {
-                        ctx.log.warn('Sandbox creation was unsettled when the run stopped; any returned handle will be released, but a remote allocation hidden behind a lost response requires provider-side reconciliation or a fleet reaper', {
-                            [NAMZU.RUN_ID]: ctx.runId,
-                            'namzu.sandbox.provider_id': params.sandboxProvider.id,
+                if (attachmentMessageCount > 0) {
+                    await eventTranslator.emitEvent({
+                        type: 'capability_warning',
+                        turnId: ctx.recorder.turnId,
+                        capability: 'vision',
+                        providerId: params.provider.id,
+                        message: `Provider '${params.provider.id}' does not support vision — image attachments on ${attachmentMessageCount} user message(s) will not reach the model.`,
+                    });
+                    yield* eventTranslator.drainPending();
+                }
+                if (documentMessageCount > 0) {
+                    await eventTranslator.emitEvent({
+                        type: 'capability_warning',
+                        turnId: ctx.recorder.turnId,
+                        capability: 'documents',
+                        providerId: params.provider.id,
+                        message: `Provider '${params.provider.id}' does not support documents — document attachments on ${documentMessageCount} user message(s) will not reach the model.`,
+                    });
+                    yield* eventTranslator.drainPending();
+                }
+                if (params.pluginManager) {
+                    const hookResults = await params.pluginManager.executeHooks('turn_start', { sessionId: ctx.sessionId, turnId: ctx.turnId, signal: ctx.abortController.signal }, eventTranslator.emitEvent);
+                    applyLifecycleHookResults('turn_start', hookResults);
+                    yield* eventTranslator.drainPending();
+                }
+                // --- Sandbox lifecycle: create before iteration loop ---
+                if (params.sandboxProvider) {
+                    const rootAtCwd = turnConfig.sandbox?.workspace === 'working-directory';
+                    // Checked against what the CALLER passed, not against `ctx.cwd`.
+                    // `ctx.cwd` falls back to `process.cwd()`, so reading it here
+                    // would silently root the sandbox at whatever directory the
+                    // host process happens to be in — which is not the directory
+                    // anybody asked to confine, and is worse than the temp dir the
+                    // caller declined. Refused before the sandbox exists, and not
+                    // downgraded to ephemeral: a caller who asked for confinement
+                    // of a specific tree and quietly got an empty one has been
+                    // told their files are protected by something that is not
+                    // looking at them.
+                    if (rootAtCwd && params.workingDirectory === undefined) {
+                        throw new NamzuError({
+                            code: 'invalid_config',
+                            message: "sandbox.workspace is 'working-directory' but this turn has no workingDirectory. Pass one, or use the default 'ephemeral' — the kernel will not fall back to a temp directory, because that would confine a directory you did not name.",
+                            details: { workspace: 'working-directory' },
                         });
                     }
-                    if (acquisition.kind === 'cancelled') {
-                        ctx.runMgr.markCancelled();
-                    }
-                    else {
-                        ctx.runMgr.setStopReason('timeout');
-                        ctx.log.warn('Sandbox creation exhausted the run timeout', {
-                            [NAMZU.RUN_ID]: ctx.runId,
-                            'namzu.sandbox.provider_id': params.sandboxProvider.id,
-                            ...errorAttributes(acquisition.error),
+                    if (rootAtCwd && !params.sandboxProvider.workspaceModes?.includes('working-directory')) {
+                        throw new NamzuError({
+                            code: 'invalid_config',
+                            message: `Sandbox provider '${params.sandboxProvider.id}' does not advertise working-directory workspace support. Refusing instead of passing a project path the provider may ignore.`,
+                            details: {
+                                providerId: params.sandboxProvider.id,
+                                workspace: 'working-directory',
+                            },
                         });
                     }
-                    yield* resultAssembler.completeRun(rootSpan);
-                    // The run HAS settled, so the outer `finally` must not read
-                    // this as an abandonment — it would persist a second time.
+                    const acquisition = await acquireSandbox({
+                        provider: params.sandboxProvider,
+                        config: {
+                            ...(rootAtCwd ? { workingDirectory: ctx.cwd } : {}),
+                            ...(rootAtCwd && params.additionalDirectories?.length
+                                ? { additionalDirectories: params.additionalDirectories }
+                                : {}),
+                            timeoutMs: turnConfig.sandbox?.timeoutMs,
+                            memoryLimitMb: turnConfig.sandbox?.memoryLimitMb,
+                            maxProcesses: turnConfig.sandbox?.maxProcesses,
+                        },
+                        signal: ctx.abortController.signal,
+                        timeoutMs: guard.remainingUntilTimeoutMs(),
+                        teardownTimeoutMs: sandboxTeardownTimeoutMs,
+                        onLateTeardown: (result) => {
+                            if (result.kind === 'destroyed') {
+                                ctx.log.info('Late sandbox allocation was destroyed after the turn stopped', {
+                                    [NAMZU.TURN_ID]: ctx.turnId,
+                                });
+                                return;
+                            }
+                            ctx.log.error('Late sandbox allocation did not stop cleanly', {
+                                [NAMZU.TURN_ID]: ctx.turnId,
+                                ...errorAttributes(result.error),
+                            });
+                        },
+                    });
+                    if (acquisition.kind !== 'created') {
+                        if (acquisition.createPending) {
+                            ctx.log.warn('Sandbox creation was unsettled when the turn stopped; any returned handle will be released, but a remote allocation hidden behind a lost response requires provider-side reconciliation or a fleet reaper', {
+                                [NAMZU.TURN_ID]: ctx.turnId,
+                                'namzu.sandbox.provider_id': params.sandboxProvider.id,
+                            });
+                        }
+                        if (acquisition.kind === 'cancelled') {
+                            ctx.recorder.markCancelled();
+                        }
+                        else {
+                            ctx.recorder.setStopReason('timeout');
+                            ctx.log.warn('Sandbox creation exhausted the turn timeout', {
+                                [NAMZU.TURN_ID]: ctx.turnId,
+                                'namzu.sandbox.provider_id': params.sandboxProvider.id,
+                                ...errorAttributes(acquisition.error),
+                            });
+                        }
+                        yield* resultAssembler.completeTurn(rootSpan);
+                        // The turn HAS settled, so the outer `finally` must not read
+                        // this as an abandonment — it would persist a second time.
+                        settled = true;
+                        return await resultAssembler.finalize();
+                    }
+                    sandbox = acquisition.sandbox;
+                    toolExecutor.setSandbox(sandbox);
+                    await eventTranslator.emitEvent({
+                        type: 'sandbox_created',
+                        turnId: ctx.turnId,
+                        sandboxId: sandbox.id,
+                        environment: sandbox.environment,
+                    });
+                    yield* eventTranslator.drainPending();
+                    ctx.log.info('Sandbox created for run', {
+                        'namzu.sandbox.id': sandbox.id,
+                        'namzu.execution.environment': sandbox.environment,
+                        'namzu.runtime.root_dir': sandbox.rootDir,
+                    });
+                }
+                // Before the first model call: the cheapest place to refuse, since
+                // nothing has been spent. Previously unreachable — `turn_start`
+                // fires with only `{ sessionId, turnId }` and `turn_started` carries only the
+                // system prompt, so no hook could see the user's message.
+                const inputVerdict = await runInputGuardrails(params.inputGuardrails, {
+                    sessionId: ctx.sessionId,
+                    turnId: ctx.turnId,
+                    messages: ctx.recorder.messages,
+                    ...(segments?.static ? { systemPrompt: segments.static } : {}),
+                }, ctx.log);
+                if (inputVerdict.blocked) {
+                    await eventTranslator.emitEvent({
+                        type: 'guardrail_triggered',
+                        turnId: ctx.turnId,
+                        stage: 'input',
+                        action: 'block',
+                        ...(inputVerdict.name ? { guardrail: inputVerdict.name } : {}),
+                        ...(inputVerdict.reason ? { reason: inputVerdict.reason } : {}),
+                    });
+                    yield* eventTranslator.drainPending();
+                    // A guardrail block is a refusal — first-class in the audit trail
+                    // (LOG-14, design §5), not merely a SessionEvent a host happens to be
+                    // subscribed to when it fires.
+                    await ctx.recorder.recordAudit({
+                        what: { action: 'guardrail:input', resource: inputVerdict.name },
+                        outcome: 'refused',
+                        reason: inputVerdict.reason ?? 'blocked by an input guardrail',
+                        ...(params.persona?.identity.role ? { persona: params.persona.identity.role } : {}),
+                    });
+                    ctx.recorder.setStopReason('input_guardrail');
+                    ctx.recorder.setLastError(inputVerdict.reason ?? 'blocked by an input guardrail');
+                    yield* resultAssembler.completeTurn(rootSpan);
+                    // Same two lines as the sandbox path above, and for the same
+                    // reasons — with one that path does not have. This return used to
+                    // hand back `getRun()` without persisting, so the terminal state
+                    // reached the disk only because the abandonment path found
+                    // `settled` false and settled it a second time. A branch that
+                    // exists for runs which did NOT settle must not be the reason a
+                    // settled one is written down.
                     settled = true;
                     return await resultAssembler.finalize();
                 }
-                sandbox = acquisition.sandbox;
-                toolExecutor.setSandbox(sandbox);
-                await eventTranslator.emitEvent({
-                    type: 'sandbox_created',
-                    runId: ctx.runId,
-                    sandboxId: sandbox.id,
-                    environment: sandbox.environment,
-                });
-                yield* eventTranslator.drainPending();
-                ctx.log.info('Sandbox created for run', {
-                    'namzu.sandbox.id': sandbox.id,
-                    'namzu.execution.environment': sandbox.environment,
-                    'namzu.runtime.root_dir': sandbox.rootDir,
-                });
-            }
-            // Crash-save handlers live for exactly the run's lifetime, and are
-            // removed in the `finally` below. Opt-in — see `emergencySave`.
-            if (params.emergencySave) {
-                const runDir = ctx.runMgr.getRunDir();
-                if (runDir) {
-                    emergencyManager = EmergencySaveManager.instance(ctx.log);
-                    emergencyManager.attach(ctx.runMgr, runDir, ctx.log);
+                // Honor the approval a human already gave, before the loop's
+                // first model call. The sandbox exists by now, so an approved
+                // tool that needs one gets it.
+                if (pendingResume) {
+                    ctx.log.info('Applying a pending HITL decision to the checkpointed tool calls', {
+                        [NAMZU.TURN_ID]: ctx.turnId,
+                        'namzu.tool.names': pendingResume.response.message.toolCalls?.map((tc) => tc.function.name),
+                        'namzu.runtime.denied': pendingResume.denials.size,
+                    });
+                    // Hand the recorded answer to the already-built tool. The tool
+                    // closed over its registry when the agent was constructed,
+                    // long before this turn existed, so the answers are copied in
+                    // rather than passed down.
+                    if (pendingResume.answers) {
+                        for (const [questionId, answer] of pendingResume.answers.entries()) {
+                            pendingAnswers.set(questionId, answer);
+                        }
+                    }
+                    await applyPendingResume(pendingResume, ctx.recorder, toolExecutor, recoveredResults, pendingResumeAssistantId);
+                    yield* eventTranslator.drainPending();
                 }
-                else {
-                    ctx.log.warn('emergencySave requested but the run has no output directory — crash dumps disabled', { [NAMZU.RUN_ID]: ctx.runId });
+                // The decision has now actually been carried out, so the park it
+                // answered is no longer outstanding. Without this the checkpoint
+                // keeps reporting `pending` with no `resolvedAt`, and an approval
+                // queue re-serves a call that already ran — or a question already
+                // answered — which defeats the entire point of recording the park.
+                //
+                // Two arms reach this point, and being outside `if (pendingResume)`
+                // is what the second one needs. One is a plan whose decision was
+                // applied to a batch above. The other is the cadence arm, for which
+                // `planPendingResume` rightly produces no plan because the loop
+                // resuming IS its decision being carried out (`answeredParkId`, set
+                // on the restore path). Resolving only the first left a finished turn
+                // reporting `awaiting-decision` forever.
+                //
+                // What is RECORDED depends on which of the two produced the plan. A
+                // recovery plan means the batch was answered by the crash path
+                // rather than by the decision — the calls the human was asked about
+                // were closed with explicitly unknown outcomes — so the human's
+                // answer must not be written down as what ended the park. The park is
+                // still resolved: the question is moot, and leaving it outstanding
+                // would have `findPendingCheckpoint` serve it as the newest
+                // outstanding park, so a host resuming it would rewind this turn to
+                // the checkpoint the crash happened on and re-execute a batch the turn
+                // has long since moved past.
+                const resolvedCheckpointId = pendingResume?.checkpointId ?? answeredParkId;
+                const recordedDecision = pendingResume?.source === 'recovery' && params.pendingDecision
+                    ? supersededByRecovery(params.pendingDecision)
+                    : params.pendingDecision;
+                if (recordedDecision && resolvedCheckpointId) {
+                    await checkpointMgr
+                        .unpark(resolvedCheckpointId, recordedDecision)
+                        .catch((err) => {
+                        ctx.log.error('Applied a pending decision but failed to clear the park', {
+                            [NAMZU.TURN_ID]: ctx.turnId,
+                            'namzu.checkpoint.id': resolvedCheckpointId,
+                            'exception.message': err instanceof Error ? err.message : String(err),
+                        });
+                        return null;
+                    });
                 }
-            }
-            // Before the first model call: the cheapest place to refuse, since
-            // nothing has been spent. Previously unreachable — `run_start`
-            // fires with only `{ runId }` and `run_started` carries only the
-            // system prompt, so no hook could see the user's message.
-            const inputVerdict = await runInputGuardrails(params.inputGuardrails, {
-                runId: ctx.runId,
-                messages: ctx.runMgr.messages,
-                ...(segments?.static ? { systemPrompt: segments.static } : {}),
-            }, ctx.log);
-            if (inputVerdict.blocked) {
-                await eventTranslator.emitEvent({
-                    type: 'guardrail_triggered',
-                    runId: ctx.runId,
-                    stage: 'input',
-                    action: 'block',
-                    ...(inputVerdict.name ? { guardrail: inputVerdict.name } : {}),
-                    ...(inputVerdict.reason ? { reason: inputVerdict.reason } : {}),
+                yield* iterationOrchestrator.runLoop();
+                yield* finalizeTurn({
+                    ctx,
+                    params,
+                    eventTranslator,
+                    takeSteps: () => iterationOrchestrator.getSteps(),
+                    workingStateManager,
+                    resultAssembler,
+                    rootSpan,
                 });
-                yield* eventTranslator.drainPending();
-                // A guardrail block is a refusal — first-class in the audit trail
-                // (LOG-14, design §5), not merely a RunEvent a host happens to be
-                // subscribed to when it fires.
-                await ctx.runMgr.recordAudit({
-                    what: { action: 'guardrail:input', resource: inputVerdict.name },
-                    outcome: 'refused',
-                    reason: inputVerdict.reason ?? 'blocked by an input guardrail',
-                    ...(params.persona?.identity.role ? { persona: params.persona.identity.role } : {}),
-                });
-                ctx.runMgr.setStopReason('input_guardrail');
-                ctx.runMgr.setLastError(inputVerdict.reason ?? 'blocked by an input guardrail');
-                yield* resultAssembler.completeRun(rootSpan);
-                // Same two lines as the sandbox path above, and for the same
-                // reasons — with one that path does not have. This return used to
-                // hand back `getRun()` without persisting, so the terminal state
-                // reached the disk only because the abandonment path found
-                // `settled` false and settled it a second time. A branch that
-                // exists for runs which did NOT settle must not be the reason a
-                // settled one is written down.
-                settled = true;
-                return await resultAssembler.finalize();
             }
-            // Honor the approval a human already gave, before the loop's
-            // first model call. The sandbox exists by now, so an approved
-            // tool that needs one gets it.
-            if (pendingResume) {
-                ctx.log.info('Applying a pending HITL decision to the checkpointed tool calls', {
-                    [NAMZU.RUN_ID]: ctx.runId,
-                    'namzu.tool.names': pendingResume.response.message.toolCalls?.map((tc) => tc.function.name),
-                    'namzu.runtime.denied': pendingResume.denials.size,
-                });
-                // Hand the recorded answer to the already-built tool. The tool
-                // closed over its registry when the agent was constructed,
-                // long before this run existed, so the answers are copied in
-                // rather than passed down.
-                if (pendingResume.answers) {
-                    for (const [questionId, answer] of pendingResume.answers.entries()) {
-                        pendingAnswers.set(questionId, answer);
-                    }
-                }
-                await applyPendingResume(pendingResume, ctx.runMgr, toolExecutor, recoveredResults);
+            catch (err) {
+                // Another turn is active in this session: nothing of this turn was
+                // written, so there is nothing to settle. The caller gets the
+                // refusal itself.
+                if (isTurnInProgressError(err) && !ctx.recorder.isActive)
+                    throw err;
+                // A failed turn still spent its steps; report them.
+                ctx.recorder.setSteps(iterationOrchestrator.getSteps());
+                await executeUserInterruptHooks(err);
                 yield* eventTranslator.drainPending();
+                yield* resultAssembler.handleError(err, rootSpan);
             }
-            // The decision has now actually been carried out, so the park it
-            // answered is no longer outstanding. Without this the checkpoint
-            // keeps reporting `pending` with no `resolvedAt`, and an approval
-            // queue re-serves a call that already ran — or a question already
-            // answered — which defeats the entire point of recording the park.
-            //
-            // Two arms reach this point, and being outside `if (pendingResume)`
-            // is what the second one needs. One is a plan whose decision was
-            // applied to a batch above. The other is the cadence arm, for which
-            // `planPendingResume` rightly produces no plan because the loop
-            // resuming IS its decision being carried out (`answeredParkId`, set
-            // on the restore path). Resolving only the first left a finished run
-            // reporting `awaiting-decision` forever.
-            //
-            // What is RECORDED depends on which of the two produced the plan. A
-            // recovery plan means the batch was answered by the crash path
-            // rather than by the decision — the calls the human was asked about
-            // were closed with explicitly unknown outcomes — so the human's
-            // answer must not be written down as what ended the park. The park is
-            // still resolved: the question is moot, and leaving it outstanding
-            // would have `findPendingCheckpoint` serve it as the newest
-            // outstanding park, so a host resuming it would rewind this run to
-            // the checkpoint the crash happened on and re-execute a batch the run
-            // has long since moved past.
-            const resolvedCheckpointId = pendingResume?.checkpointId ?? answeredParkId;
-            const recordedDecision = pendingResume?.source === 'recovery' && params.pendingDecision
-                ? supersededByRecovery(params.pendingDecision)
-                : params.pendingDecision;
-            if (recordedDecision && resolvedCheckpointId) {
-                await checkpointMgr.unpark(resolvedCheckpointId, recordedDecision).catch((err) => {
-                    ctx.log.error('Applied a pending decision but failed to clear the park', {
-                        [NAMZU.RUN_ID]: ctx.runId,
-                        'namzu.checkpoint.id': resolvedCheckpointId,
-                        'exception.message': err instanceof Error ? err.message : String(err),
-                    });
-                    return null;
+            finally {
+                yield* releaseTurnResources({
+                    ctx,
+                    eventTranslator,
+                    unsubscribeJobExits,
+                    unsubscribeTaskStore,
+                    awaitedJobs,
+                    backgroundJobs: params.backgroundJobs,
+                    backgroundJobOwner: params.backgroundJobOwner,
+                    questionParks,
+                    workingStateManager,
+                    promoteMemory: params.promoteMemory,
+                    sandbox,
+                    sandboxTeardownTimeoutMs,
+                    runStartedAt,
+                    rootSpan,
                 });
             }
-            yield* iterationOrchestrator.runLoop();
-            yield* finalizeRun({
-                ctx,
-                params,
-                eventTranslator,
-                takeSteps: () => iterationOrchestrator.getSteps(),
-                workingStateManager,
-                resultAssembler,
-                rootSpan,
-            });
-        }
-        catch (err) {
-            // A failed run still spent its steps; report them.
-            ctx.runMgr.setSteps(iterationOrchestrator.getSteps());
-            await executeUserInterruptHooks(err);
-            yield* eventTranslator.drainPending();
-            yield* resultAssembler.handleError(err, rootSpan);
+            // Reached only by a turn that settled on its own terms. `finalize()` is
+            // the only thing in this body that writes the durable half of the turn,
+            // and a `return` completion arriving from a consumer (`break` out of
+            // `for await`, `gen.return()`) runs the `finally` above and stops short
+            // of here. The flag is what tells the two apart, and this is one of
+            // three sites that set it — the sandbox-acquisition and input-guardrail
+            // returns settle early and set it there. Set before the await rather
+            // than after, because a store that throws on the way out must not send
+            // the abandonment path over the same broken ground.
+            settled = true;
+            return await resultAssembler.finalize();
+        })();
+        try {
+            return yield* runBody;
         }
         finally {
-            yield* releaseRunResources({
-                ctx,
-                eventTranslator,
-                emergencyManager,
-                unsubscribeJobExits,
-                unsubscribeTaskStore,
-                awaitedJobs,
-                backgroundJobs: params.backgroundJobs,
-                backgroundJobOwner: params.backgroundJobOwner,
-                questionParks,
-                workingStateManager,
-                promoteMemory: params.promoteMemory,
-                sandbox,
-                sandboxTeardownTimeoutMs,
-                runStartedAt,
-                rootSpan,
-            });
+            if (!settled)
+                await settleAbandonedTurn(ctx.recorder, eventTranslator, ctx.log);
         }
-        // Reached only by a run that settled on its own terms. `finalize()` is
-        // the only thing in this body that writes the durable half of the run,
-        // and a `return` completion arriving from a consumer (`break` out of
-        // `for await`, `gen.return()`) runs the `finally` above and stops short
-        // of here. The flag is what tells the two apart, and this is one of
-        // three sites that set it — the sandbox-acquisition and input-guardrail
-        // returns settle early and set it there. Set before the await rather
-        // than after, because a store that throws on the way out must not send
-        // the abandonment path over the same broken ground.
-        settled = true;
-        return await resultAssembler.finalize();
-    })();
-    try {
-        return yield* runBody;
     }
     finally {
-        if (!settled)
-            await settleAbandonedRun(ctx.runMgr, ctx.log);
+        unsubscribeChildSessions?.();
+        // The lease `open()` took in the prelude; a caller-supplied lease is the
+        // caller's to give back.
+        await ctx.recorder.release();
     }
 }
 /**
- * Write a terminal durable record for a run whose consumer walked away.
- *
- * `for await (… ) break` and an explicit `gen.return()` both end the run
- * body early. Everything the run's `finally` owns still happens — background
- * jobs are killed, the sandbox is destroyed, the span ends, the duration is
- * recorded — and then the generator stops. `finalize()` never runs, so
- * `persist()` never runs, and the store keeps whatever `init()` wrote: a
- * non-terminal status for a run that no longer exists. `deriveRunStatus`
- * reads that record back as `queued`, work waiting to start, and a host
- * rebuilding its view from the store believes it.
- *
- * There is nothing to emit here and nothing to emit it to: the consumer
- * that would have received the events is the one that left. This is about
- * the durable record only.
+ * Write a durable record for a turn whose consumer walked away.
  *
- * `cancelled` is the verdict, and it is chosen from the existing vocabulary
- * because it is the one that is true. The run did not complete — no result
- * was produced and no terminal event was ever delivered — and nothing
- * failed, so `failed` would name an error that never happened; a run whose
- * consumer stopped reading and whose processes were torn down under it is
- * the same fact `markCancelled` already records when a run abort tears one
- * down. It needs no new `RunExecutionStatus` and no new `StopReason`.
+ * `for await (… ) break` and an explicit `gen.return()` both end the turn
+ * body early. Everything the body's `finally` owns still happens — jobs are
+ * killed, the sandbox is destroyed, the span ends — and then the generator
+ * stops without settling. Without this the log would end mid-turn, and the
+ * turn would read as `interrupted` for a process that is gone.
  *
- * A verdict the run already reached is left standing. A run that failed,
- * or was cancelled, before the consumer left still says so; what the
- * abandonment adds is that the record reaches the disk at all.
- *
- * Neither is a verdict written over a PARK. A park is a promise to a human
- * that outlives the consumer: the run is resumable and somebody is still owed
- * an answer, and `deriveRunStatus` reads a terminal status BEFORE it reads the
- * park — so recording `cancelled` turns `awaiting_hitl` into `cancelled` for a
- * run nobody answered for, while the unanswered question stays on the record
- * and the checkpoint it belongs to stays the place a resume starts from. The
- * durable state is asked rather than the in-memory one because the in-memory
- * one is the misleading half here: `handleHITLDecision` emits `run_paused` and
- * drains it BEFORE it calls `setStopReason('paused')`, so a consumer that
- * leaves on that event leaves a run whose status is `running` and whose stop
- * reason is unset at the exact instant its park is already durable.
- * `findPendingCheckpoint` is the same read an approval queue is built from,
- * expired parks included in its judgement: a park nobody answered in time is
- * not somebody still being asked.
+ * - A turn that already settled, or already paused, is left as it stands.
+ * - A turn parked on a decision (an open `decision_requested`) is PAUSED on
+ *   that checkpoint: a park is a promise to a human that outlives the
+ *   consumer, and `resumeSession` continues it once the answer arrives.
+ * - Any other turn is settled `cancelled` (`turn_completed`): it did not
+ *   complete and nothing failed; its consumer stopped reading.
  *
  * Never throws. It runs while an exception may already be unwinding, and a
- * store that cannot be written must not replace the run's real failure with
- * its own.
+ * log that cannot be written must not replace the turn's real failure.
  */
-async function settleAbandonedRun(runMgr, log) {
+async function settleAbandonedTurn(recorder, eventTranslator, log) {
     try {
-        // A terminal verdict is written whatever the park says: `deriveRunStatus`
-        // settles a run that finished, failed or was cancelled BEFORE it looks at
-        // a park ("terminal beats parked"), so a settled run is not waiting for
-        // anybody and the row it already wrote must reach the disk. This ordering
-        // is also what keeps a stale park from suppressing the write.
-        if (!isTerminalStatus(runMgr.status)) {
-            const parked = await findPendingCheckpoint(runMgr.getCheckpointStore(), runMgr.getRunScope());
-            if (parked) {
-                // Left exactly as it stands: no verdict, no write. The park row is
-                // this run's durable state, and `persist()` here would add a
-                // second claim — `running`, for a process that is gone — beside it.
-                log.info('Abandoned run left parked for a human to answer', {
-                    [NAMZU.RUN_ID]: runMgr.id,
-                    'namzu.checkpoint.id': parked.id,
-                    'namzu.runtime.park_type': parked.pending?.request.type,
-                });
-                return;
-            }
-            runMgr.markCancelled();
+        if (recorder.isClosed || recorder.isPaused || !recorder.isActive)
+            return;
+        await recorder.flush();
+        const parked = await findPendingCheckpoint(recorder.log, { turnId: recorder.turnId });
+        if (parked) {
+            recorder.setStopReason('paused');
+            await eventTranslator.emitEvent({
+                type: 'turn_paused',
+                checkpointId: parked.checkpointId,
+                reason: 'The consumer stopped reading while the turn was awaiting a decision.',
+            });
+            await recorder.persist();
+            log.info('Abandoned turn left paused for a human to answer', {
+                [NAMZU.TURN_ID]: recorder.turnId,
+                'namzu.checkpoint.id': parked.checkpointId,
+                'namzu.runtime.park_type': parked.pending.request.type,
+            });
+            return;
         }
-        // Once: the `finally` that calls this runs once, and every site in the
-        // run body that settles through `finalize()` sets `settled` before it
-        // returns, so the two can never both write.
-        await runMgr.persist();
-        log.info('Abandoned run recorded as cancelled', {
-            [NAMZU.RUN_ID]: runMgr.id,
+        if (!isTerminalStatus(recorder.status))
+            recorder.markCancelled();
+        await eventTranslator.emitEvent({
+            type: 'turn_completed',
+            result: recorder.getTurn().result ?? '',
+            ...(recorder.stopReason ? { stopReason: recorder.stopReason } : {}),
+            settlement: recorder.settlement(recorder.status === 'cancelled' ? 'cancelled' : 'completed'),
+        });
+        await recorder.persist();
+        log.info('Abandoned turn recorded as cancelled', {
+            [NAMZU.TURN_ID]: recorder.turnId,
         });
     }
     catch (err) {
-        log.error('Failed to record the terminal state of an abandoned run', {
-            [NAMZU.RUN_ID]: runMgr.id,
+        log.error('Failed to record the end of an abandoned turn', {
+            [NAMZU.TURN_ID]: recorder.turnId,
             'exception.message': err instanceof Error ? err.message : String(err),
         });
     }
@@ -1465,7 +1500,7 @@ export async function drainQuery(params, listener) {
     };
     return await drainPreparedQuery(fullParams, listener);
 }
-/** @internal Canonical resume state already selected by `resumeRun`. */
+/** @internal Canonical resume state already selected by `resumeSession`. */
 export async function drainQueryWithSelectedResumeState(params, state, listener) {
     const fullParams = {
         ...params,
@@ -1480,8 +1515,8 @@ export async function drainQueryWithSelectedResumeState(params, state, listener)
 }
 function assertSelectedResumeAttribution(params, state) {
     const mismatchedFields = [];
-    if (params.runId !== state.runId)
-        mismatchedFields.push('runId');
+    if (params.turnId !== state.turnId)
+        mismatchedFields.push('turnId');
     if (params.sessionId !== state.sessionId)
         mismatchedFields.push('sessionId');
     if (params.topicId !== state.topicId)
@@ -1490,13 +1525,13 @@ function assertSelectedResumeAttribution(params, state) {
         mismatchedFields.push('projectId');
     if (params.tenantId !== state.tenantId)
         mismatchedFields.push('tenantId');
-    if (params.parentRunId !== state.parentRunId)
-        mismatchedFields.push('parentRunId');
+    if (params.parentSessionId !== state.parentSessionId)
+        mismatchedFields.push('parentSessionId');
     if (mismatchedFields.length === 0)
         return;
     throw new NamzuError({
         code: 'invalid_config',
-        message: 'The selected resume state does not match the run attribution supplied to the query.',
+        message: 'The selected resume state does not match the turn attribution supplied to the query.',
         details: { fields: mismatchedFields },
     });
 }