@namzu/sdk 42.0.0 → 42.0.2

package/dist/runtime/query/index.js

@@ -1,9 +1,7 @@
 import { join } from 'node:path';
 import { AdvisorRegistry, AdvisoryContext, AdvisoryExecutor, TriggerEvaluator, assertBudgetEnforceable, } from '../../advisory/index.js';
-import { drainQueuedMessages } from '../../agents/handle.js';
 import { AuthorizationGate } from '../../authorization/gate.js';
-import { consolidationEntry } from '../../compaction/consolidation.js';
-import { repairToolMessageHistory, toolHistoryRepairChanged, } from '../../compaction/dangling.js';
+import { repairToolMessageHistory, toolHistoryRepairChanged } from '../../compaction/dangling.js';
 import { extractFromUserMessage } from '../../compaction/extractor.js';
 import { WorkingStateManager } from '../../compaction/manager.js';
 import { serializeState as serializeWorkingState } from '../../compaction/serializer.js';
@@ -11,225 +9,44 @@ import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire
 import { CompactionConfigSchema } from '../../config/runtime.js';
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js';
 import { EmergencySaveManager } from '../../manager/run/emergency.js';
-import { resolveModelPricing } from '../../pricing/index.js';
 import { PromptContributionRegistry } from '../../prompt/contributions.js';
 import { resolveProviderCapabilities } from '../../provider/capabilities.js';
-import { isCallerAbortError } from '../../provider/errors.js';
-import { withProviderFallback, } from '../../provider/fallback.js';
-import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../../provider/idle-timeout.js';
-import { withProviderRetry } from '../../provider/retry.js';
+import { withStreamIdleTimeout } from '../../provider/idle-timeout.js';
 import { withTokenBudget } from '../../provider/token-budget.js';
-import { resolveAttachments } from '../../store/attachment/index.js';
 import { GENAI, NAMZU, agentRunSpanName, parentContext, serializeSpan, } from '../../telemetry/attributes.js';
-import { recordRunDuration } from '../../telemetry/metrics.js';
 import { getTracer } from '../../telemetry/runtime-accessors.js';
 import { buildAdvisoryTools } from '../../tools/advisory/index.js';
 import { SearchToolsTool } from '../../tools/builtins/search-tools.js';
 import { STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputTool, } from '../../tools/builtins/structuredOutput.js';
 import { buildTaskTools } from '../../tools/task/index.js';
+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 { cancelCauseOf } from '../../types/run/cancel-cause.js';
-import { resolveRunEventReplay } from '../../types/run/event-cursor.js';
-import { memoryCandidateFor } from '../../types/run/memory-promotion.js';
 import { toErrorMessage } from '../../utils/error.js';
-import { generateCheckpointId, generateRunId } from '../../utils/id.js';
 import { errorAttributes } from '../../utils/log/exception.js';
 import { AwaitedJobs } from '../jobs/awaited-jobs.js';
-import { AUTO_APPROVE_POLICY_NAME, createRunApprovalPolicy } from './approval-policy.js';
-import { CheckpointManager } from './checkpoint.js';
-import { RunContextFactory } from './context.js';
-import { EventTranslator } from './events.js';
+import { catchUpFromCursor, settlePreStartCancellation } from './cancelled-before-start.js';
+import { CheckpointManager, findPendingCheckpoint } from './checkpoint.js';
+import { finalizeRun } from './finalize-run.js';
 import { GuardCoordinator } from './guard.js';
-import { runInputGuardrails, runOutputGuardrails } from './guardrails.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 { awaitProjectInstructionCallback, collapseProjectInstructionSnapshots, replaceProjectInstructionSnapshot, } from './project-instructions.js';
+import { prepareRun, projectStateBearingHistory, resolveProviderContextWindow, selectedResumeStates, } from './prepare-run.js';
 import { PromptBuilder } from './prompt.js';
 import { PendingAnswers, QuestionParkBinding } from './question-park.js';
+import { releaseRunResources } from './release-run.js';
 import { RepeatCallTracker } from './repeat-call.js';
-import { resolveMaxRequestRichContentBytes } from './request-rich-content.js';
 import { ResultAssembler } from './result.js';
-import { applyPendingResume, interruptedToolCalls, planCrashResume, planPendingResume, recoverCompletedCalls, } from './resume-pending.js';
-import { acquireSandbox, resolveSandboxTeardownTimeoutMs, teardownSandbox, } from './sandbox-lifecycle.js';
+import { answersParkOf, applyPendingResume, interruptedToolCalls, planCrashResume, planPendingResume, recoverCompletedCalls, supersededByRecovery, } from './resume-pending.js';
+import { acquireSandbox } from './sandbox-lifecycle.js';
 import { SteeringBinding, isOperatorUserMessage } from './steering.js';
-import { resolveQueryBudget } from './token-budget.js';
-import { assertMaxToolCalls } from './tool-call-budget.js';
 import { ToolGrantSet } from './tool-grants.js';
 import { createToolPause } from './tool-pause.js';
 import { ToolingBootstrap } from './tooling.js';
-const selectedResumeStates = new WeakMap();
-/**
- * Refuse to price a run whose tokens two differently-priced members may produce.
- *
- * `RunPersistence` holds ONE {@link ModelPricing} table and applies it to every
- * accumulation regardless of which model produced the tokens. Across a swap that
- * makes `costInfo.totalCost` wrong by an unbounded margin, and silently — the
- * number keeps the shape of an answer. `CostInfo` cannot express the truth
- * either: it carries `inputCostPer1M` / `outputCostPer1M`, and there is no
- * honest value for those once a total spans two rate cards.
- *
- * So the total is refused rather than blended. Naming what that costs is part
- * of the refusal, because the caller loses `costLimitUsd` with it: the guard
- * enforces that limit from this same accumulated total, and a limit enforced
- * with the wrong rate card stops a run early or late by the same unbounded
- * margin. A budget that is quietly wrong is worse than a budget that is
- * declined.
- *
- * Reachable, not decorative: a host that passes `pricing` and declares a chain
- * hits it on the first call. It costs `@namzu/cli` nothing, which passes no
- * pricing at all — its `/cost` already reports that the provider gave no price.
- *
- * The way out is per-member pricing, which needs a `CostInfo` that can sum over
- * heterogeneous rates. That is a public-type change and it is not this one.
- */
-function assertCostIsAttributable(chain, pricing) {
-    if (pricing === undefined || chain.length < 2)
-        return;
-    throw new NamzuError({
-        code: 'invalid_config',
-        message: `A provider chain of ${chain.length} members was declared together with a single pricing table. ` +
-            'One table cannot price two members, so the run would report a total that is wrong by an unbounded ' +
-            'margin — and `runConfig.costLimitUsd` would be enforced against that same wrong total. ' +
-            'Either drop `pricing` (usage is still reported per model in the run) or declare one member.',
-        details: { chainLength: chain.length },
-    });
-}
-/**
- * Refuse a budget that cannot be measured.
- *
- * `runConfig.costLimitUsd` is enforced against `costInfo.totalCost`, and that
- * total only moves for tokens something has a rate for. A model no rate card
- * covers therefore produced a limit that could never trip — a host that set a
- * cost cap had no cost cap, and nothing said so. That was every run before the
- * price catalogue existed, which is how it went unnoticed.
- *
- * Refusing at the front is the cheap half of the answer: it costs the caller
- * nothing, fires before any spend, and names both ways out. The other half is
- * the `cost_unmeasurable` stop, for the models this cannot see — a step naming
- * its own, or a chain member declaring one.
- *
- * This is the same shape `advisory/budget.ts` already applies to
- * `AdvisoryBudget.maxCostPerRun`, one layer down, and for the same reason. The
- * run path simply never had it.
- */
-function assertBudgetIsMeasurable(params) {
-    const limit = params.runConfig.costLimitUsd;
-    if (limit === undefined || limit <= 0)
-        return;
-    // A host-supplied table prices whatever it is pointed at, so a caller who
-    // brought one has answered the question themselves.
-    if (params.pricing !== undefined)
-        return;
-    const model = params.runConfig.model;
-    if (resolveModelPricing(params.provider.id, model) !== undefined)
-        return;
-    throw new NamzuError({
-        code: 'invalid_config',
-        message: `runConfig.costLimitUsd is set to ${limit}, but no rate is known for model "${model}" on ` +
-            `provider "${params.provider.id}". The limit is enforced against the run's accumulated ` +
-            'cost, and tokens with no rate never reach that total — so the budget would read as ' +
-            'satisfied for the whole run and stop nothing. Either pass `pricing` to declare the rate ' +
-            'yourself, add the model to packages/sdk/src/pricing/rates.source.json, or drop ' +
-            '`costLimitUsd` and bound the run with `tokenBudget`, which is measurable here.',
-        details: { model, providerId: params.provider.id, costLimitUsd: limit },
-    });
-}
-/**
- * Ask the driver what this model's window is, and never let the answer
- * cost the run.
- *
- * Three outcomes collapse to two here on purpose. No member and a resolved
- * `undefined` both mean "no answer" — the distinction matters to a driver
- * author, not to a caller about to fall through to the table. A rejection
- * is the third, and it is logged rather than propagated: a run that would
- * have worked on the table must not fail because a listing endpoint was
- * down.
- */
-async function resolveProviderContextWindow(provider, model, signal, timeoutMs, log) {
-    if (!provider.resolveContextWindow || !model)
-        return undefined;
-    if (signal?.aborted)
-        return undefined;
-    // The resolver is an optional optimisation that runs before RunContext
-    // owns its child controller. Give it a private deadline signal and fuse
-    // caller cancellation into that transport in the safe direction: neither
-    // outcome aborts the caller's controller. Passing a signal is necessary
-    // but not sufficient, because a third-party driver can accept it and still
-    // leave its promise pending; the race below makes fallback independent of
-    // driver cooperation. Promise.race keeps the losing provider promise
-    // observed, so a later rejection cannot become unhandled.
-    const deadline = new AbortController();
-    const resolverSignal = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
-    const interrupted = Symbol('provider-context-window-interrupted');
-    let onAbort;
-    const interruption = new Promise((resolve) => {
-        onAbort = () => resolve(interrupted);
-        resolverSignal.addEventListener('abort', onAbort, { once: true });
-    });
-    // Direct QueryParams callers can supply a large run deadline. The clamp
-    // avoids Node's >2^31-1 one-millisecond timer coercion during metadata lookup.
-    // Metadata discovery remains optional and bounded even without a run deadline.
-    const deadlineMs = timeoutMs === 0 ? 5_000 : Math.min(Math.max(0, timeoutMs), 2_147_483_647);
-    const timer = setTimeout(() => {
-        deadline.abort(new Error(`Provider context-window lookup exceeded ${deadlineMs}ms`));
-    }, deadlineMs);
-    try {
-        const resolution = provider.resolveContextWindow(model, resolverSignal);
-        const reported = await Promise.race([resolution, interruption]);
-        if (reported === interrupted) {
-            if (deadline.signal.aborted) {
-                log.debug('Provider context-window lookup timed out; using the table', {
-                    'namzu.model.id': model,
-                    'namzu.runtime.timeout_ms': deadlineMs,
-                });
-            }
-            return undefined;
-        }
-        return typeof reported === 'number' && reported > 0 ? reported : undefined;
-    }
-    catch (err) {
-        log.debug('Provider could not report a context window; using the table', {
-            'namzu.model.id': model,
-            'namzu.error.message': toErrorMessage(err),
-        });
-        return undefined;
-    }
-    finally {
-        clearTimeout(timer);
-        if (onAbort)
-            resolverSignal.removeEventListener('abort', onAbort);
-    }
-}
-/**
- * Project historical system messages exactly as a new run will persist them.
- *
- * Arbitrary historical prompt floors are rebuilt for this run and therefore
- * never reach its provider-bound conversation. Repair must happen AFTER that
- * removal: treating a soon-to-be-dropped system message as a tool-result
- * boundary can replace an exact real result with an invented unknown outcome.
- * The two state-bearing system forms survive; fresh inherited compaction is
- * pinned until this run can prove it reconstructed equivalent state.
- */
-function projectStateBearingHistory(messages, options) {
-    const projected = [];
-    for (const message of messages) {
-        if (message.role !== 'system') {
-            projected.push(message);
-            continue;
-        }
-        if (isCompactionMessage(message.content)) {
-            projected.push(options.pinCompaction ? { ...message, retain: true } : message);
-        }
-        else if (isWorkingMemoryMessage(message.content)) {
-            projected.push(message);
-        }
-    }
-    return collapseProjectInstructionSnapshots(projected);
-}
 /**
  * Remove the incomplete turn still owned by a durable resume plan.
  *
@@ -295,469 +112,10 @@ function withOwnedResumeOutcomes(messages, assistant, recovered) {
     ];
 }
 export async function* query(params) {
-    assertMaxToolCalls(params.maxToolCalls);
-    // Required types do not protect JavaScript callers. Reject missing scope
-    // before opening a budget or persisting a run without its owning identity.
-    const missingFields = ['sessionId', 'topicId', 'projectId', 'tenantId'].filter((field) => !params[field]);
-    if (missingFields.length > 0) {
-        throw new NamzuError({
-            code: 'invalid_config',
-            message: `query requires sessionId, topicId, projectId, and tenantId; missing: ${missingFields.join(', ')}.`,
-            details: { missingFields },
-        });
-    }
-    const selectedResumeState = selectedResumeStates.get(params);
-    selectedResumeStates.delete(params);
-    // Resolved at the DOOR, before a run id exists or a logger is built.
-    // A caller who set both spellings of a renamed field has a config bug,
-    // and refusing it here costs them nothing; refusing it at the read site
-    // deep in the loop turns the same bug into a mid-run failure, after a
-    // provider call has been paid for and a partial transcript written.
-    const promptCache = params.promptCache;
-    const taskScheduler = params.taskScheduler;
-    const streamIdleTimeoutMs = resolveStreamIdleTimeoutMs(params.runConfig.streamIdleTimeoutMs);
-    const maxRequestRichContentBytes = resolveMaxRequestRichContentBytes(params.runConfig.maxRequestRichContentBytes);
-    const sandboxTeardownTimeoutMs = resolveSandboxTeardownTimeoutMs(params.sandboxTeardownTimeoutMs);
-    // Persist the EFFECTIVE value, not only an override. A run replayed after a
-    // later release must be able to explain which liveness policy settled it;
-    // an absent field whose meaning follows the currently-installed default
-    // would rewrite that evidence at read time.
-    const runConfig = {
-        ...params.runConfig,
-        streamIdleTimeoutMs,
-        maxRequestRichContentBytes,
-    };
-    // The run's one correlated logger, built before anything below needs
-    // one — the migration check, the retry/fallback wrappers and `ctx`
-    // itself all read this SAME object, so a retry warning and the run
-    // record it retried for carry the identical `namzu.run.id` instead of
-    // three separate `getRootLogger()` reads that happened to agree by
-    // accident. `runId` is resolved here, once, rather than left to
-    // `build`'s own `config.runId ?? generateRunId()` fallback —
-    // generating it twice would silently hand the log and the run two
-    // different ids.
-    const runId = params.runId ?? generateRunId();
-    const budget = await resolveQueryBudget(params, runId, selectedResumeState);
-    const log = RunContextFactory.buildLogger({
-        agentName: params.agentName,
-        runConfig,
-        runId,
-        parentRunId: params.parentRunId,
-        sessionId: params.sessionId,
-        topicId: params.topicId,
-        projectId: params.projectId,
-        tenantId: params.tenantId,
-    });
-    // Every model call in the run — the loop's turns, the forced-final
-    // summary, advisory and compaction side calls — goes through this one
-    // wrapped provider, so the retry policy cannot be bypassed by a code
-    // path that happens to hold the raw driver.
-    // The logger is passed on purpose: `withProviderRetry` guards every one
-    // of its warns behind `options.log`, and this is its only production
-    // call site — so without it the "failed, retrying" and "failed, giving
-    // up" lines were dead code and a backoff left no trace anywhere.
-    //
-    // With a chain declared, the same sentence holds two levels out. The idle
-    // watchdog is applied to each raw member, retry wraps that, and fallback
-    // wraps the members: `fallback(retry(idle(m0)), retry(idle(m1)), …)`. The
-    // idle layer cannot sit outside retry, because its timer would then count a
-    // legitimate backoff as provider silence. This order is not a
-    // preference. Assembled the other way round — which is what a host gets if
-    // it wraps its own chain and hands the result in, because this function
-    // would then wrap THAT in retry — an exhausted chain gets restarted from
-    // the head by the outer loop and a throttle on the last member is counted
-    // by two budgets. Building it here is what makes the order unspellable
-    // wrong.
-    const chain = [
-        { provider: params.provider },
-        ...(params.fallbackProviders ?? []),
-    ];
-    assertCostIsAttributable(chain, params.pricing);
-    assertBudgetIsMeasurable(params);
-    const withRecovery = (provider) => {
-        const withIdleBound = withStreamIdleTimeout(provider, {
-            idleTimeoutMs: streamIdleTimeoutMs,
-            log,
-        });
-        const metered = withTokenBudget(withIdleBound, budget);
-        return params.retry === false
-            ? metered
-            : withProviderRetry(metered, {
-                config: params.retry,
-                log,
-                canRetry: () => budget.remaining > 0,
-            });
-    };
-    // Who is serving right now, for the run RECORD rather than for the request.
-    //
-    // It starts at the head and moves only when the chain does, which is the
-    // whole of the truth because the cursor never rewinds. The run cannot read
-    // this off `resilientProvider`: that wrapper reports the head's `id` on
-    // purpose, so asking it produces the declaration back — the defect this
-    // record exists to fix.
-    const serving = {
-        current: { index: 0, providerId: params.provider.id },
-    };
-    const resilientProvider = withProviderFallback(chain.map((member) => ({
-        ...member,
-        provider: withRecovery(member.provider),
-    })), {
-        log,
-        canFallback: () => budget.remaining > 0,
-        onSwap: (to) => {
-            serving.current = to;
-            // `ctx` is declared below and is initialized before anything can
-            // call the provider: this fires from inside a `chatStream`, and
-            // the first one is issued by the loop that `ctx` is built for.
-            ctx.runMgr.setServingProvider(to.providerId);
-        },
-    });
-    // Asked ONCE, here, before the loop exists. Both readers are synchronous
-    // and hot, so this can never move inside the iteration — and a driver
-    // that rejects, or one that hangs until the run is cancelled, must not
-    // take down a run the table could have served perfectly well. That is
-    // why the failure path is a swallow with a log rather than a throw: the
-    // window is an optimisation over a working default, not a prerequisite.
-    const providerContextWindow = await resolveProviderContextWindow(resilientProvider, runConfig.model, params.signal, runConfig.timeoutMs, log);
-    const modelContextWindows = new Map();
-    if (runConfig.model)
-        modelContextWindows.set(runConfig.model, providerContextWindow);
-    // The mode this conversation was left in, when the run config names none.
-    // Read once, before the loop exists, for the same reason the context
-    // window is: the executor's resolver is synchronous and hot.
-    //
-    // A store that throws is not a run failure — the run falls back to the
-    // config's answer, which is exactly what it did before this existed.
-    const topicState = params.topicStateStore
-        ? await params.topicStateStore
-            .getState(params.topicId, params.tenantId)
-            .catch((err) => {
-            log.debug('Could not read the topic state; using the run config', {
-                'namzu.topic.id': params.topicId,
-                'namzu.error.message': toErrorMessage(err),
-            });
-            return null;
-        })
-        : null;
-    // Whatever a host left for "the next run", taken and cleared in one
-    // compare-and-set write. Prepended to the messages this run starts from,
-    // so it is in the FIRST request rather than arriving a turn late.
-    //
-    // Cleared as it is read: a queue read and cleared separately re-delivers
-    // on a crash between the two, and "start with this" arriving twice is a
-    // different instruction from the one that was left.
-    const queuedForThisRun = params.topicStateStore
-        ? await drainQueuedMessages(params.topicStateStore, params.topicId, params.tenantId).catch((err) => {
-            log.debug('Could not drain the topic queue; starting without it', {
-                'namzu.topic.id': params.topicId,
-                'namzu.error.message': toErrorMessage(err),
-            });
-            return [];
-        })
-        : [];
-    // One effective list, used everywhere the run is seeded from. Three
-    // branches below push from it, and computing it at each would be three
-    // places to forget the queue.
-    //
-    // Stored attachments are resolved HERE, once, before the messages reach
-    // the run record. Resolving later — at the provider boundary — would put
-    // refs in the durable transcript and in every checkpoint, and a run
-    // resumed against a store that had since forgotten a ref would fail
-    // replaying its own history rather than at the moment somebody asked for
-    // the bytes. Every failure refuses: a message that silently lost its
-    // image is a model answering about a picture it never saw.
-    const seeded = queuedForThisRun.length > 0 ? [...queuedForThisRun, ...params.messages] : params.messages;
-    let resolvedInitialMessages;
-    let attachmentResolutionCancelled = false;
-    try {
-        resolvedInitialMessages = [
-            ...(await resolveAttachments(seeded, params.attachmentStore, {
-                signal: params.signal,
-                timeoutMs: params.attachmentResolveTimeoutMs,
-            })),
-        ];
-        params.signal?.throwIfAborted();
-    }
-    catch (error) {
-        // Attachment materialization precedes RunContext construction so stored
-        // bytes never enter a live run's checkpoints. Cancellation still belongs
-        // to that run: preserve the exact input refs, build the context below, and
-        // let its normal terminal path classify/persist a cancelled Run. Every
-        // other store failure remains a pre-run refusal.
-        if (!params.signal?.aborted || error !== params.signal.reason)
-            throw error;
-        resolvedInitialMessages = [...seeded];
-        attachmentResolutionCancelled = true;
-    }
-    if (!attachmentResolutionCancelled && params.projectInstructionContext?.prepareInitialSnapshot) {
-        const preparationSignal = params.signal ?? new AbortController().signal;
-        let snapshot;
-        try {
-            const prepared = await awaitProjectInstructionCallback(preparationSignal, () => params.projectInstructionContext?.prepareInitialSnapshot?.({
-                messages: [...resolvedInitialMessages],
-                signal: preparationSignal,
-            }));
-            // The callback promise can settle, remove its listener, and queue this
-            // continuation immediately before a queued abort. Publication is a
-            // separate authority boundary, so fence it too.
-            preparationSignal.throwIfAborted();
-            snapshot = prepared;
-        }
-        catch (error) {
-            // This callback runs before RunContext owns its child controller. A
-            // caller cancellation here still belongs to the run: publish no late
-            // snapshot and let the context below settle the normal cancelled Run.
-            // Compare the exact reason: a callback failure that won first must not
-            // be erased merely because cancellation arrived before this catch ran.
-            if (!preparationSignal.aborted || error !== preparationSignal.reason)
-                throw error;
-        }
-        if (snapshot !== undefined) {
-            resolvedInitialMessages = replaceProjectInstructionSnapshot(resolvedInitialMessages, snapshot, 'before-latest-user');
-        }
-    }
-    const pendingHistoryRepairs = [];
-    const projectedInitialMessages = collapseProjectInstructionSnapshots(params.resumeFromCheckpoint || params.continuationMode
-        ? resolvedInitialMessages
-        : projectStateBearingHistory(resolvedInitialMessages, {
-            pinCompaction: true,
-        }));
-    const initialRepair = params.resumeFromCheckpoint
-        ? { messages: projectedInitialMessages, report: undefined }
-        : repairToolMessageHistory(projectedInitialMessages);
-    const initialMessages = initialRepair.messages;
-    if (initialRepair.report && toolHistoryRepairChanged(initialRepair.report)) {
-        pendingHistoryRepairs.push({
-            source: 'fresh-history',
-            report: initialRepair.report,
-        });
-        log.warn('Repaired provider-invalid tool history before starting the run', {
-            [NAMZU.RUN_ID]: runId,
-            'namzu.history.source': 'fresh-history',
-            'namzu.history.duplicate_tool_results_removed': initialRepair.report.duplicateToolResultsRemoved,
-            'namzu.history.orphaned_tool_results_removed': initialRepair.report.orphanedToolResultsRemoved,
-            'namzu.history.synthetic_tool_results_inserted': initialRepair.report.syntheticToolResultsInserted,
-        });
-    }
-    const ctx = RunContextFactory.build({
-        budget,
-        ...(topicState ? { topicPermissionMode: topicState.permissionMode } : {}),
-        ...(params.permissionModeRef ? { permissionModeRef: params.permissionModeRef } : {}),
-        agentId: params.agentId,
-        agentName: params.agentName,
-        runConfig,
-        provider: resilientProvider,
-        workingDirectory: params.workingDirectory,
-        pricing: params.pricing,
-        enableActivityTracking: params.enableActivityTracking,
-        messages: initialMessages,
-        signal: params.signal,
-        sessionId: params.sessionId,
-        topicId: params.topicId,
-        projectId: params.projectId,
-        tenantId: params.tenantId,
-        pathBuilder: params.pathBuilder,
-        checkpointStore: params.checkpointStore,
-        runStore: params.runStore,
-        runId,
-        parentRunId: params.parentRunId,
-        depth: params.depth,
-        log,
-    });
-    // Built here because the plan-approval closure below captures it, and
-    // its `emit` resolves `eventTranslator` at CALL time — the translator is
-    // a `const` some lines further down.
-    //
-    // The HANDOUT is therefore deliberately NOT here. A host given the box
-    // at this point can call `set` synchronously, `emit` reaches
-    // `eventTranslator` inside its temporal dead zone, and the run dies
-    // before it starts. That is not hypothetical: it is what the first
-    // version of this did, and the test that hands out the box and
-    // immediately swaps the policy is the one that found it.
-    const approvalPolicy = createRunApprovalPolicy({
-        runId: ctx.runId,
-        initial: {
-            // By identity against the default, not by presence. `resumeHandler`
-            // is REQUIRED on `QueryParams` — `drainQuery` substitutes
-            // `autoApproveHandler` before calling here — so "is it set" is
-            // always yes and would name every run `host`, including the ones
-            // approving everything unattended. Identity is what actually
-            // separates the two.
-            name: params.approvalPolicyName ??
-                (params.resumeHandler === autoApproveHandler ? AUTO_APPROVE_POLICY_NAME : 'host'),
-            handler: params.resumeHandler,
-        },
-        emit: (event) => eventTranslator.emitEvent(event),
-    });
-    const planApprovalIds = new Map();
-    ctx.planManager.setApprovalHandler(async (request) => {
-        let checkpointId = planApprovalIds.get(request.planId);
-        if (!checkpointId) {
-            checkpointId = generateCheckpointId();
-            planApprovalIds.set(request.planId, checkpointId);
-        }
-        // `.current.handler`, never a captured `params.resumeHandler`. That
-        // capture is what made changing the policy mean ending the run.
-        const decision = await approvalPolicy.current.handler({
-            type: 'plan_approval',
-            runId: ctx.runId,
-            checkpointId,
-            plan: {
-                planId: request.planId,
-                title: request.title,
-                steps: request.steps.map((s, i) => ({
-                    id: s.id,
-                    description: s.description,
-                    toolName: s.toolName,
-                    agentId: s.agentId,
-                    dependsOn: s.dependsOn,
-                    order: s.order ?? i + 1,
-                })),
-                summary: request.summary,
-            },
-        });
-        if (decision.action === 'approve_plan') {
-            // Optional approve-with-edits channel: the host may attach
-            // feedback to an approval. `PlanApprovalResponse.feedback`
-            // already exists on the type; threading it through lets the
-            // coordinator's approve_plan tool surface the user's edits in
-            // the same tool_result that unblocks the park. Bare approvals
-            // stay byte-identical (`{ approved: true }`).
-            return decision.feedback
-                ? { approved: true, feedback: decision.feedback }
-                : { approved: true };
-        }
-        if (decision.action === 'reject_plan') {
-            return { approved: false, feedback: decision.feedback };
-        }
-        return { approved: false, feedback: `Action: ${decision.action}` };
-    });
-    const eventTranslator = new EventTranslator(ctx.runMgr, undefined, ctx.log);
-    eventTranslator.wireActivityStore(ctx.activityStore, ctx.runId);
-    eventTranslator.wirePlanManager(ctx.planManager, ctx.runId);
-    eventTranslator.setGeneration(params.claimFence);
-    let interruptHooksStarted = false;
-    const executeUserInterruptHooks = async (terminalError) => {
-        if (interruptHooksStarted ||
-            !params.pluginManager ||
-            !isCallerAbortError(terminalError, ctx.abortController.signal) ||
-            params.parentRunId !== undefined ||
-            (params.depth ?? 0) !== 0 ||
-            cancelCauseOf(ctx.abortController.signal.reason) !== 'user') {
-            return;
-        }
-        interruptHooksStarted = true;
-        try {
-            // Deliberately omit the already-aborted run signal. The lifecycle
-            // manager still supplies each handler its own deadline signal, while
-            // `run_interrupt`'s observational fan-out prevents one result from
-            // suppressing the cleanup hooks that follow it.
-            await params.pluginManager.executeHooks('run_interrupt', { runId: ctx.runId, cancelCause: 'user' }, eventTranslator.emitEvent);
-        }
-        catch (error) {
-            // Cancellation is the terminal authority. A hook event sink or an
-            // unexpected manager failure is reported, but cannot turn Stop into a
-            // failed run or prevent the durable cancellation verdict.
-            ctx.log.error('Run interrupt hooks did not settle cleanly', {
-                [NAMZU.RUN_ID]: ctx.runId,
-                ...errorAttributes(error),
-            });
-        }
-    };
+    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;
     if (attachmentResolutionCancelled) {
-        // Attachment materialization happens before RunContext exists. Once it
-        // observes cancellation, do only the work required to leave an honest
-        // durable run: initialize the record, retain the unresolved references,
-        // and settle through the ordinary cancellation classifier. Prompt
-        // contributions/cache, host callbacks, tools, plugins, sandbox, guardrails,
-        // advisors, and providers are all authority-bearing work and stay out.
-        // The dedicated root interrupt notification is the sole plugin exception:
-        // it runs after cancellation under its own deadline and cannot regain model
-        // or tool authority.
-        if (params.resumeFromCheckpoint && !selectedResumeState) {
-            // The canonical resume surface hands query the checkpoint state it
-            // already selected. A raw resume query has no such snapshot; after
-            // cancellation, reading the store again could hang without a signal,
-            // while persisting without it would erase the existing transcript.
-            // Refuse before binding/persisting rather than choose either failure.
-            ctx.abortController.signal.throwIfAborted();
-        }
-        const cancelledPrompt = params.systemPrompt ?? '';
-        const cancelledAssembler = new ResultAssembler({
-            runMgr: ctx.runMgr,
-            planManager: ctx.planManager,
-            activityStore: ctx.activityStore,
-            log: ctx.log,
-            emitEvent: eventTranslator.emitEvent,
-            drainPending: () => eventTranslator.drainPending(),
-            signal: ctx.abortController.signal,
-        });
-        const rootSpan = getTracer().startSpan(agentRunSpanName(params.agentName), {}, parentContext(params.parentSpan ?? selectedResumeState?.traceContext));
-        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,
-        });
-        try {
-            await ctx.runMgr.init();
-            if (selectedResumeState) {
-                ctx.runMgr.restoreUsage(selectedResumeState.tokenUsage, selectedResumeState.costInfo, selectedResumeState.currentIteration);
-                for (const message of selectedResumeState.messages)
-                    ctx.runMgr.pushMessage(message);
-                for (const queued of queuedForThisRun)
-                    ctx.runMgr.pushMessage(queued);
-            }
-            else if (params.continuationMode) {
-                for (const message of initialMessages)
-                    ctx.runMgr.pushMessage(message);
-            }
-            else {
-                ctx.runMgr.pushMessage(createSystemMessage(cancelledPrompt, 'cache'));
-                for (const message of initialMessages)
-                    ctx.runMgr.pushMessage(message);
-            }
-            if (params.eventCursor) {
-                yield* catchUpFromCursor(ctx.runMgr, params.eventCursor, params.onEventReplay, params.claimFence, (error) => {
-                    ctx.log.warn('Replay observer failed after attachment cancellation', {
-                        'exception.message': toErrorMessage(error),
-                    });
-                });
-            }
-            if (selectedResumeState) {
-                await eventTranslator.emitEvent({
-                    type: 'run_resuming',
-                    runId: ctx.runId,
-                    fromCheckpointId: selectedResumeState.checkpointId,
-                });
-                yield* eventTranslator.drainPending();
-            }
-            ctx.runMgr.markRunning();
-            await eventTranslator.emitEvent({
-                type: 'run_started',
-                runId: ctx.runId,
-                systemPrompt: cancelledPrompt,
-            });
-            yield* eventTranslator.drainPending();
-            ctx.abortController.signal.throwIfAborted();
-        }
-        catch (error) {
-            // Attachment resolution has already observed the caller's abort. A
-            // reconnect callback can still throw while replay is being reported,
-            // but it cannot replace that terminal cause or turn a cancelled run
-            // into an unpersisted rejection.
-            const terminalError = ctx.abortController.signal.aborted
-                ? ctx.abortController.signal.reason
-                : error;
-            await executeUserInterruptHooks(terminalError);
-            yield* eventTranslator.drainPending();
-            yield* cancelledAssembler.handleError(terminalError, rootSpan);
-        }
-        finally {
-            rootSpan.end();
-        }
-        return await cancelledAssembler.finalize();
+        return yield* settlePreStartCancellation(params, prepared);
     }
     const unsubscribeTaskStore = params.taskStore
         ? eventTranslator.wireTaskStore(params.taskStore, ctx.runId)
@@ -1220,7 +578,11 @@ export async function* query(params) {
         pluginManager: params.pluginManager,
     });
     const tracer = getTracer();
-    return yield* (async function* () {
+    // 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 —
@@ -1324,6 +686,11 @@ export async function* query(params) {
         // 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;
@@ -1451,6 +818,48 @@ export async function* query(params) {
                     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);
@@ -1756,6 +1165,9 @@ export async function* query(params) {
                         });
                     }
                     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.
+                    settled = true;
                     return await resultAssembler.finalize();
                 }
                 sandbox = acquisition.sandbox;
@@ -1816,7 +1228,15 @@ export async function* query(params) {
                 ctx.runMgr.setStopReason('input_guardrail');
                 ctx.runMgr.setLastError(inputVerdict.reason ?? 'blocked by an input guardrail');
                 yield* resultAssembler.completeRun(rootSpan);
-                return ctx.runMgr.getRun();
+                // 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
@@ -1838,130 +1258,55 @@ export async function* query(params) {
                 }
                 await applyPendingResume(pendingResume, ctx.runMgr, toolExecutor, recoveredResults);
                 yield* eventTranslator.drainPending();
-                // The decision has now actually been carried out, so the park
-                // is no longer outstanding. Without this the checkpoint keeps
-                // reporting `pending` with no `resolvedAt`, and an approval
-                // queue re-serves a destructive call that already ran — which
-                // defeats the entire point of recording the park.
-                const resolvedCheckpointId = pendingResume.checkpointId;
-                if (params.pendingDecision) {
-                    await checkpointMgr
-                        .unpark(resolvedCheckpointId, params.pendingDecision)
-                        .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;
-                    });
-                }
-            }
-            yield* iterationOrchestrator.runLoop();
-            if (params.pluginManager) {
-                const hookResults = await params.pluginManager.executeHooks('run_end', { runId: ctx.runId, signal: ctx.abortController.signal }, eventTranslator.emitEvent);
-                applyLifecycleHookResults('run_end', hookResults);
-                yield* eventTranslator.drainPending();
-                // A delegated run says so once more, by name, so a hook that
-                // only cares when a subagent finishes need not read parent ids
-                // off every run_end.
-                if (params.parentRunId !== undefined) {
-                    const stopResults = await params.pluginManager.executeHooks('subagent_stop', {
-                        runId: ctx.runId,
-                        parentRunId: params.parentRunId,
-                        signal: ctx.abortController.signal,
-                    }, eventTranslator.emitEvent);
-                    applyLifecycleHookResults('subagent_stop', stopResults);
-                    yield* eventTranslator.drainPending();
-                }
             }
-            // Hand the step record to the run before it settles, so the
-            // returned `Run` carries it.
-            ctx.runMgr.setSteps(iterationOrchestrator.getSteps());
-            // Gates the FINAL result, not the stream — `text_delta` already
-            // reached the host as the model produced it. A rewrite is
-            // therefore a correction, and the event says so; buffering every
-            // token to gate the stream itself would trade the streaming UX
-            // for the guarantee, which is the host's call, not the SDK's.
-            if (params.outputGuardrails && params.outputGuardrails.length > 0) {
-                // Read what the run produced WITHOUT settling it. This used to
-                // call `markCompleted()` just to materialize the text, which
-                // force-marked a cancelled or paused run `completed` merely
-                // because a guardrail was configured — the presence of a
-                // safety check silently rewrote the run's own outcome.
-                const produced = ctx.runMgr.materializeResult();
-                const outputVerdict = await runOutputGuardrails(params.outputGuardrails, { runId: ctx.runId, output: produced, messages: ctx.runMgr.messages }, ctx.log);
-                if (outputVerdict.blocked || outputVerdict.rewritten !== undefined) {
-                    ctx.runMgr.clearStructuredOutput();
-                    if (params.structuredOutput &&
-                        outputVerdict.rewritten !== undefined &&
-                        ctx.runMgr.stopReason === 'end_turn')
-                        ctx.runMgr.setStopReason('output_guardrail');
-                }
-                if (outputVerdict.blocked) {
-                    await eventTranslator.emitEvent({
-                        type: 'guardrail_triggered',
-                        runId: ctx.runId,
-                        stage: 'output',
-                        action: 'block',
-                        ...(outputVerdict.name ? { guardrail: outputVerdict.name } : {}),
-                        ...(outputVerdict.reason ? { reason: outputVerdict.reason } : {}),
-                    });
-                    yield* eventTranslator.drainPending();
-                    // Same reasoning as the input-guardrail branch above.
-                    await ctx.runMgr.recordAudit({
-                        what: { action: 'guardrail:output', resource: outputVerdict.name },
-                        outcome: 'refused',
-                        reason: outputVerdict.reason ?? 'blocked by an output guardrail',
-                        ...(params.persona?.identity.role ? { persona: params.persona.identity.role } : {}),
-                    });
-                    ctx.runMgr.setStopReason('output_guardrail');
-                    ctx.runMgr.setLastError(outputVerdict.reason ?? 'blocked by an output guardrail');
-                    ctx.runMgr.setResult('');
-                }
-                else if (outputVerdict.rewritten !== undefined) {
-                    await eventTranslator.emitEvent({
-                        type: 'guardrail_triggered',
-                        runId: ctx.runId,
-                        stage: 'output',
-                        action: 'rewrite',
-                        ...(outputVerdict.name ? { guardrail: outputVerdict.name } : {}),
-                        ...(outputVerdict.reason ? { reason: outputVerdict.reason } : {}),
+            // 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),
                     });
-                    yield* eventTranslator.drainPending();
-                    ctx.runMgr.setResult(outputVerdict.rewritten);
-                }
-            }
-            if (params.consolidateInto && workingStateManager) {
-                const entry = consolidationEntry(workingStateManager.getState(), {
-                    runId: ctx.runId,
-                    at: Date.now(),
+                    return null;
                 });
-                if (entry) {
-                    try {
-                        const { entry: saved } = await params.consolidateInto.create(entry);
-                        await eventTranslator.emitEvent({
-                            type: 'memory_consolidated',
-                            runId: ctx.runId,
-                            memoryId: saved.id,
-                            title: entry.title,
-                            decisions: workingStateManager.getState().decisions.length,
-                            discoveries: workingStateManager.getState().discoveries.length,
-                            failures: workingStateManager.getState().failures.length,
-                        });
-                        yield* eventTranslator.drainPending();
-                    }
-                    catch (error) {
-                        ctx.log.warn('consolidation into the memory store failed', {
-                            [NAMZU.RUN_ID]: ctx.runId,
-                            'namzu.memory.error': toErrorMessage(error),
-                        });
-                    }
-                }
             }
-            if (ctx.abortController.signal.aborted)
-                ctx.runMgr.markCancelled();
-            yield* resultAssembler.completeRun(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.
@@ -1971,104 +1316,128 @@ export async function* query(params) {
             yield* resultAssembler.handleError(err, rootSpan);
         }
         finally {
-            // Release the process's termination path as soon as this run is
-            // done with it. Leaving the handlers installed would keep a
-            // WeakRef'd, settled run as the crash target for the rest of the
-            // process's life.
-            emergencyManager?.detach();
-            // A background job outlives the tool call that started it — that
-            // is what it is for — so nothing but this stops it outliving the
-            // RUN. Scoped to this run's id: a shared registry serving several
-            // runs must not have one of them tear down another's work.
-            //
-            // Awaited, and its failure swallowed. A job that would not die is
-            // worth a log line, and is not worth retracting a run's answer.
-            unsubscribeJobExits?.();
-            // The wait-intent recorder listens on the same shared registry and
-            // leaks the same way if it is left attached.
-            awaitedJobs?.close();
-            // Only jobs bound to this run. Jobs a host bound to its session are
-            // the host's to stop, when the session ends.
-            if (params.backgroundJobs && (params.backgroundJobOwner ?? ctx.runId) === ctx.runId) {
-                try {
-                    const stopped = await params.backgroundJobs.killOwner(ctx.runId);
-                    if (stopped.length > 0) {
-                        ctx.log.info('Background jobs stopped with the run', {
-                            [NAMZU.RUN_ID]: ctx.runId,
-                            'namzu.jobs.stopped': stopped.length,
-                        });
-                    }
-                }
-                catch (jobErr) {
-                    ctx.log.error('A background job did not stop cleanly', {
-                        [NAMZU.RUN_ID]: ctx.runId,
-                        ...errorAttributes(jobErr),
-                    });
-                }
-            }
-            // Same reasoning for the question channel: the tools outlive the
-            // run that bound them, so leaving it attached would have a later
-            // run's question written into this run's checkpoint store.
-            questionParks.unbind();
-            // Offer what the run learned to whoever decides what is worth
-            // keeping. In `finally` and awaited: a run that failed still
-            // discovered things, and a fire-and-forget write would race the
-            // process exiting on a one-shot CLI run. A throw here is
-            // swallowed — a memory that failed to form must not retract an
-            // answer that was already produced.
-            const candidate = memoryCandidateFor(ctx.runId, workingStateManager);
-            if (params.promoteMemory && candidate) {
-                try {
-                    await params.promoteMemory(candidate);
-                }
-                catch (promoteErr) {
-                    ctx.log.error('Memory promotion threw — the run is unaffected', {
-                        [NAMZU.RUN_ID]: ctx.runId,
-                        'exception.message': promoteErr instanceof Error ? promoteErr.message : String(promoteErr),
-                    });
-                }
-            }
-            // --- Sandbox lifecycle: destroy after run ---
-            if (sandbox) {
-                const sandboxId = sandbox.id;
-                const teardown = await teardownSandbox(sandbox, sandboxTeardownTimeoutMs);
-                if (teardown.kind === 'destroyed') {
-                    await eventTranslator.emitEvent({
-                        type: 'sandbox_destroyed',
-                        runId: ctx.runId,
-                        sandboxId,
-                    });
-                    yield* eventTranslator.drainPending();
-                    ctx.log.info('Sandbox destroyed', { 'namzu.sandbox.id': sandboxId });
-                }
-                else {
-                    ctx.log.error('Sandbox destroy failed', {
-                        'namzu.sandbox.id': sandboxId,
-                        ...errorAttributes(teardown.error),
-                    });
-                }
-            }
-            unsubscribeTaskStore?.();
-            // Keyed by HOW it settled, not just that it did: a run that was
-            // cancelled and a run that hit its budget have very different
-            // duration distributions, and averaging them together describes
-            // neither.
-            recordRunDuration(ctx.runMgr.getRun().status ?? 'unknown', Date.now() - runStartedAt);
-            rootSpan.end();
+            yield* releaseRunResources({
+                ctx,
+                eventTranslator,
+                emergencyManager,
+                unsubscribeJobExits,
+                unsubscribeTaskStore,
+                awaitedJobs,
+                backgroundJobs: params.backgroundJobs,
+                backgroundJobOwner: params.backgroundJobOwner,
+                questionParks,
+                workingStateManager,
+                promoteMemory: params.promoteMemory,
+                sandbox,
+                sandboxTeardownTimeoutMs,
+                runStartedAt,
+                rootSpan,
+            });
         }
+        // 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);
+    }
 }
 /**
- * Hand a returning consumer what it missed, or tell it why it cannot have it.
+ * Write a terminal durable record for a run whose consumer walked away.
  *
- * Yields NOTHING on a refusal. A partial catch-up is the failure this exists to
- * prevent: a consumer that receives some of the gap folds it into its state and
- * cannot tell the state is wrong, where one that receives an explicit
- * `unavailable` re-derives from the transcript and is right. The run continues
- * either way — a stale cursor belongs to the client, and must not be able to
- * stop the work.
+ * `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.
+ *
+ * `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`.
+ *
+ * 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.
+ *
+ * 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.
  */
+async function settleAbandonedRun(runMgr, 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();
+        }
+        // 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,
+        });
+    }
+    catch (err) {
+        log.error('Failed to record the terminal state of an abandoned run', {
+            [NAMZU.RUN_ID]: runMgr.id,
+            'exception.message': err instanceof Error ? err.message : String(err),
+        });
+    }
+}
 /** The text of the newest user turn, which is what a prompt hook is asked about. */
 function lastUserPrompt(messages) {
     for (let i = messages.length - 1; i >= 0; i--) {
@@ -2078,30 +1447,6 @@ function lastUserPrompt(messages) {
     }
     return '';
 }
-async function* catchUpFromCursor(runMgr, cursor, onEventReplay, generation, onReplayObserverError) {
-    const missed = await runMgr.getRunStore().readEvents({ sinceSeq: cursor.sinceSeq });
-    const replay = resolveRunEventReplay(cursor, {
-        lastSeq: runMgr.lastEventSeq,
-        ...(generation !== undefined ? { generation } : {}),
-    }, missed);
-    if (onEventReplay) {
-        try {
-            // A callback typed `void` may still be implemented with `async` in
-            // TypeScript. Observe that runtime Promise so a late rejection cannot
-            // become process-wide, but never await host code here: replay delivery
-            // and an already-cancelled run must not inherit observer liveness.
-            const settlement = onEventReplay(replay);
-            void Promise.resolve(settlement).catch(onReplayObserverError);
-        }
-        catch (error) {
-            onReplayObserverError(error);
-        }
-    }
-    if (replay.status !== 'replayed')
-        return;
-    for (const event of replay.events)
-        yield event;
-}
 async function drainPreparedQuery(fullParams, listener) {
     const gen = query(fullParams);
     let result = await gen.next();