@namzu/sdk 30.2.0 → 31.1.0

package/dist/runtime/query/index.js

@@ -2,7 +2,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 { findDanglingMessages, removeDanglingMessages } 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';
@@ -13,6 +13,7 @@ import { EmergencySaveManager } from '../../manager/run/emergency.js';
 import { resolveModelPricing } from '../../pricing/index.js';
 import { resolveProviderCapabilities } from '../../provider/capabilities.js';
 import { withProviderFallback, } from '../../provider/fallback.js';
+import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../../provider/idle-timeout.js';
 import { withProviderRetry } from '../../provider/retry.js';
 import { DefaultFilesystemMigrator, loggingMigrationSink } from '../../session/migration/index.js';
 import { resolveAttachments } from '../../store/attachment/index.js';
@@ -25,7 +26,7 @@ import { STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputTool, } from '../../
 import { buildTaskTools } from '../../tools/task/index.js';
 import { NamzuError } from '../../types/errors/index.js';
 import { autoApproveHandler, } from '../../types/hitl/index.js';
-import { createSystemMessage } from '../../types/message/index.js';
+import { createSystemMessage, } from '../../types/message/index.js';
 import { resolveRunEventReplay } from '../../types/run/event-cursor.js';
 import { memoryCandidateFor } from '../../types/run/memory-promotion.js';
 import { toErrorMessage } from '../../utils/error.js';
@@ -42,14 +43,18 @@ 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 { PromptBuilder } from './prompt.js';
 import { PendingAnswers, QuestionParkBinding } from './question-park.js';
 import { RepeatCallTracker } from './repeat-call.js';
+import { resolveMaxRequestRichContentBytes } from './request-rich-content.js';
 import { ResultAssembler } from './result.js';
 import { applyPendingResume, planCrashResume, planPendingResume, recoverCompletedCalls, unansweredToolCalls, } from './resume-pending.js';
+import { acquireSandbox, resolveSandboxTeardownTimeoutMs, teardownSandbox, } from './sandbox-lifecycle.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.
  *
@@ -137,11 +142,47 @@ function assertBudgetIsMeasurable(params) {
  * have worked on the table must not fail because a listing endpoint was
  * down.
  */
-async function resolveProviderContextWindow(provider, model, signal, log) {
+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 });
+    });
+    // Wire and directory config validation already limit this field to one
+    // hour. The clamp also keeps a direct QueryParams caller from triggering
+    // Node's >2^31-1 one-millisecond timer coercion and turning a huge run
+    // budget into an immediate metadata fallback.
+    const deadlineMs = 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 reported = await provider.resolveContextWindow(model, signal);
+        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) {
@@ -151,8 +192,61 @@ async function resolveProviderContextWindow(provider, model, signal, log) {
         });
         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.
+ *
+ * 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`.
+ */
+function withoutOwnedResumeTurn(messages, assistant) {
+    const ownerIndex = messages.lastIndexOf(assistant);
+    if (ownerIndex < 0) {
+        throw new NamzuError({
+            code: 'invalid_config',
+            message: 'A pending checkpoint resume plan does not own a message in its checkpoint.',
+        });
+    }
+    const ownedIds = new Set((assistant.toolCalls ?? []).map((call) => call.id));
+    return messages.filter((message, index) => index !== ownerIndex &&
+        !(index > ownerIndex && message.role === 'tool' && ownedIds.has(message.toolCallId)));
 }
 export async function* query(params) {
+    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
@@ -160,6 +254,18 @@ export async function* query(params) {
     // 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
@@ -172,7 +278,7 @@ export async function* query(params) {
     const runId = params.runId ?? generateRunId();
     const log = RunContextFactory.buildLogger({
         agentName: params.agentName,
-        runConfig: params.runConfig,
+        runConfig,
         runId,
         parentRunId: params.parentRunId,
         sessionId: params.sessionId,
@@ -222,9 +328,11 @@ export async function* query(params) {
     // 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 one level out: retry is
-    // applied per MEMBER and the fallback decorator wraps the result, so the
-    // composition is `fallback(retry(m0), retry(m1), …)`. That order is not a
+    // 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
@@ -237,7 +345,15 @@ export async function* query(params) {
     ];
     assertCostIsAttributable(chain, params.pricing);
     assertBudgetIsMeasurable(params);
-    const withRetry = (provider) => params.retry === false ? provider : withProviderRetry(provider, { config: params.retry, log });
+    const withRecovery = (provider) => {
+        const withIdleBound = withStreamIdleTimeout(provider, {
+            idleTimeoutMs: streamIdleTimeoutMs,
+            log,
+        });
+        return params.retry === false
+            ? withIdleBound
+            : withProviderRetry(withIdleBound, { config: params.retry, log });
+    };
     // 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
@@ -248,7 +364,10 @@ export async function* query(params) {
     const serving = {
         current: { index: 0, providerId: params.provider.id },
     };
-    const resilientProvider = withProviderFallback(chain.map((member) => ({ ...member, provider: withRetry(member.provider) })), {
+    const resilientProvider = withProviderFallback(chain.map((member) => ({
+        ...member,
+        provider: withRecovery(member.provider),
+    })), {
         log,
         onSwap: (to) => {
             serving.current = to;
@@ -264,7 +383,7 @@ export async function* query(params) {
     // 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, params.runConfig.model, params.signal, log);
+    const providerContextWindow = await resolveProviderContextWindow(resilientProvider, runConfig.model, params.signal, runConfig.timeoutMs, log);
     // 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.
@@ -310,13 +429,83 @@ export async function* query(params) {
     // 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;
-    const initialMessages = [...(await resolveAttachments(seeded, params.attachmentStore))];
+    let resolvedInitialMessages;
+    let attachmentResolutionCancelled = false;
+    try {
+        resolvedInitialMessages = [
+            ...(await resolveAttachments(seeded, params.attachmentStore, {
+                signal: params.signal,
+            })),
+        ];
+        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({
         ...(topicState ? { topicPermissionMode: topicState.permissionMode } : {}),
         ...(params.permissionModeRef ? { permissionModeRef: params.permissionModeRef } : {}),
         agentId: params.agentId,
         agentName: params.agentName,
-        runConfig: params.runConfig,
+        runConfig,
         provider: resilientProvider,
         workingDirectory: params.workingDirectory,
         pricing: params.pricing,
@@ -400,6 +589,97 @@ export async function* query(params) {
     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);
+    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.
+        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;
+            yield* cancelledAssembler.handleError(terminalError, rootSpan);
+        }
+        finally {
+            rootSpan.end();
+        }
+        return await cancelledAssembler.finalize();
+    }
     const unsubscribeTaskStore = params.taskStore
         ? eventTranslator.wireTaskStore(params.taskStore, ctx.runId)
         : undefined;
@@ -453,7 +733,11 @@ export async function* query(params) {
             throw new NamzuError({
                 code: 'capability_unavailable',
                 message,
-                details: { providerId: params.provider.id, capability: 'tools', registeredToolCount },
+                details: {
+                    providerId: params.provider.id,
+                    capability: 'tools',
+                    registeredToolCount,
+                },
             });
         }
         ctx.log.warn('Capability mismatch: the provider declares no tool support', {
@@ -468,7 +752,11 @@ export async function* query(params) {
             throw new NamzuError({
                 code: 'capability_unavailable',
                 message,
-                details: { providerId: params.provider.id, capability: 'vision', attachmentMessageCount },
+                details: {
+                    providerId: params.provider.id,
+                    capability: 'vision',
+                    attachmentMessageCount,
+                },
             });
         }
         ctx.log.warn('Capability mismatch: the provider declares no vision support', {
@@ -483,7 +771,11 @@ export async function* query(params) {
             throw new NamzuError({
                 code: 'capability_unavailable',
                 message,
-                details: { providerId: params.provider.id, capability: 'documents', documentMessageCount },
+                details: {
+                    providerId: params.provider.id,
+                    capability: 'documents',
+                    documentMessageCount,
+                },
             });
         }
         ctx.log.warn('Capability mismatch: the provider declares no document support', {
@@ -537,7 +829,7 @@ export async function* query(params) {
         runId: ctx.runId,
         workingDirectory: ctx.cwd,
         permissionMode: () => ctx.permissionMode.current,
-        env: params.runConfig.env ?? {},
+        env: runConfig.env ?? {},
         abortSignal: ctx.abortController.signal,
         allowedTools: effectiveAllowedTools,
         invocationState: params.invocationState,
@@ -595,10 +887,10 @@ export async function* query(params) {
         ...(params.promptContributions ? { contributions: params.promptContributions } : {}),
     });
     const guard = new GuardCoordinator({
-        tokenBudget: params.runConfig.tokenBudget,
-        timeoutMs: params.runConfig.timeoutMs,
-        costLimitUsd: params.runConfig.costLimitUsd,
-        maxIterations: params.runConfig.maxIterations,
+        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
@@ -627,11 +919,25 @@ export async function* query(params) {
     });
     let advisoryCtx;
     if (params.advisory && params.advisory.advisors.length > 0) {
-        const advisorRegistry = new AdvisorRegistry(params.advisory.advisors, params.advisory.defaultAdvisorId);
+        // 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: withStreamIdleTimeout(advisor.provider, {
+                idleTimeoutMs: streamIdleTimeoutMs,
+                log: ctx.log,
+            }),
+        }));
+        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);
+        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
@@ -675,7 +981,7 @@ export async function* query(params) {
     const iterationOrchestrator = new IterationOrchestrator({
         provider: resilientProvider,
         servingMember: () => serving.current,
-        runConfig: params.runConfig,
+        runConfig,
         ...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),
         ...(params.prepareStep ? { prepareStep: params.prepareStep } : {}),
         ...(params.beforeStep ? { beforeStep: params.beforeStep } : {}),
@@ -716,6 +1022,9 @@ export async function* query(params) {
         ...(params.repeatCallAdvisory === false ? {} : { repeatCalls: new RepeatCallTracker() }),
         compactionConfig: params.compactionConfig,
         ...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
+        ...(params.projectInstructionContext
+            ? { projectInstructionContext: params.projectInstructionContext }
+            : {}),
         ...(providerContextWindow !== undefined ? { providerContextWindow } : {}),
         workingStateManager,
         taskRouter: params.taskRouter,
@@ -744,9 +1053,11 @@ export async function* query(params) {
         // 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 = params.resumeFromCheckpoint
-            ? await checkpointMgr.readTraceContext(params.resumeFromCheckpoint)
-            : undefined;
+        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);
@@ -755,15 +1066,11 @@ export async function* query(params) {
         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(params.runConfig.hitlParkTtlMs);
+        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);
-        // And every EVENT it records carries the same fence as its generation,
-        // so a consumer whose cursor was minted under an older holding is told
-        // the sequence space changed rather than handed a splice from it.
-        eventTranslator.setGeneration(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
@@ -826,7 +1133,7 @@ export async function* query(params) {
             [NAMZU.RUN_ID]: ctx.runMgr.id,
             [GENAI.AGENT_NAME]: params.agentName,
             [GENAI.AGENT_ID]: params.agentId,
-            [GENAI.REQUEST_MODEL]: params.runConfig.model,
+            [GENAI.REQUEST_MODEL]: runConfig.model,
             [GENAI.SYSTEM]: params.provider.id,
         });
         let sandbox;
@@ -844,27 +1151,17 @@ export async function* query(params) {
             // 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);
+                yield* catchUpFromCursor(ctx.runMgr, params.eventCursor, params.onEventReplay, params.claimFence, (error) => {
+                    ctx.log.warn('Replay observer failed', {
+                        'exception.message': toErrorMessage(error),
+                    });
+                });
             }
-            // Handed over here, and the position is load-bearing in BOTH
-            // directions. It has to follow `wirePlanManager`, or a host that
-            // builds its plan in this callback — which is what the callback is
-            // for — does it into silence: `plan_ready`, `plan_approved` and
-            // every `plan_step_updated` are emitted with nothing subscribed,
-            // and the host then watches a stream that never mentions the plan
-            // it just created. It also has to follow `runMgr.init()`, because
-            // emitting appends to the run store and an uninitialised store
-            // throws — moving it up to the wiring alone traded a silent drop
-            // for 25 unhandled rejections.
-            //
-            // Still before the iteration loop, which is the guarantee the
-            // callback actually makes.
-            params.onContextCreated?.({ planManager: ctx.planManager });
             ctx.log.info('Starting query', {
                 [NAMZU.RUN_ID]: ctx.runMgr.id,
                 'namzu.runtime.agent': params.agentName,
-                [GENAI.REQUEST_MODEL]: params.runConfig.model,
-                'namzu.runtime.token_budget': params.runConfig.tokenBudget,
+                [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,
@@ -895,6 +1192,12 @@ export async function* query(params) {
             };
             if (params.resumeFromCheckpoint) {
                 const checkpoint = await checkpointMgr.restore(params.resumeFromCheckpoint);
+                const projectedCheckpoint = {
+                    ...checkpoint,
+                    messages: projectStateBearingHistory(checkpoint.messages, {
+                        pinCompaction: false,
+                    }),
+                };
                 await eventTranslator.emitEvent({
                     type: 'run_resuming',
                     runId: ctx.runMgr.id,
@@ -940,8 +1243,8 @@ export async function* query(params) {
                 // re-decides, so "yes, delete that row" degrades into "ask
                 // again and hope it asks for the same thing".
                 pendingResume =
-                    params.pendingDecision && checkpoint.pending
-                        ? planPendingResume(checkpoint, params.pendingDecision, ctx.log)
+                    params.pendingDecision && projectedCheckpoint.pending
+                        ? planPendingResume(projectedCheckpoint, params.pendingDecision, ctx.log)
                         : null;
                 // Results of tools that finished before the process died. The
                 // executor already emits one `tool_completed` per tool inline
@@ -949,7 +1252,7 @@ export async function* query(params) {
                 // durable all along — it was simply never read back, and the
                 // resumed run re-ran calls that had already charged a card or
                 // sent an email.
-                const unanswered = unansweredToolCalls(checkpoint.messages);
+                const unanswered = unansweredToolCalls(projectedCheckpoint.messages);
                 recoveredResults =
                     unanswered.length > 0
                         ? await recoverCompletedCalls(ctx.runMgr, unanswered, ctx.log)
@@ -960,30 +1263,31 @@ export async function* query(params) {
                 // the transcript proves execution had begun — a tool-review
                 // park has no completions and keeps the cheap repair below.
                 if (!pendingResume && recoveredResults.size > 0) {
-                    pendingResume = planCrashResume(checkpoint, recoveredResults, ctx.log);
+                    pendingResume = planCrashResume(projectedCheckpoint, recoveredResults, ctx.log);
                 }
-                // A checkpoint taken at a tool-review park snapshots the
-                // assistant turn AFTER its `tool_use` blocks but BEFORE any
-                // `tool_result` exists, so replaying it verbatim would send a
-                // malformed request on the first model call of the resumed
-                // run. Repair the incomplete turn rather than inheriting it:
-                // the model re-decides from the last valid state.
-                //
-                // The pending-decision path uses the SAME repair: it strips
-                // the unanswered turn here and `applyPendingResume` re-appends
-                // it together with the results that answer it, so the history
-                // stays well-formed either way.
-                const dangling = findDanglingMessages(checkpoint.messages);
-                const restoredMessages = dangling.isValid
-                    ? checkpoint.messages
-                    : removeDanglingMessages(checkpoint.messages);
-                if (!dangling.isValid && !pendingResume) {
-                    ctx.log.warn('Checkpoint contained unanswered tool calls — repaired on restore', {
+                // 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,
+                    });
+                    ctx.log.warn('Repaired abandoned tool history while restoring a checkpoint', {
                         [NAMZU.RUN_ID]: ctx.runMgr.id,
                         'namzu.checkpoint.id': checkpoint.id,
-                        'namzu.runtime.unanswered_assistant_turns': dangling.assistantsWithUnmatchedCalls.length,
-                        'namzu.runtime.orphaned_tool_messages': dangling.orphanedToolMessages.length,
-                        'namzu.runtime.removed': checkpoint.messages.length - restoredMessages.length,
+                        '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,
                     });
                 }
                 for (const msg of restoredMessages) {
@@ -1021,8 +1325,22 @@ export async function* query(params) {
                 pushSystemMessages();
                 let isFirstUserMessage = true;
                 for (const msg of initialMessages) {
-                    if (msg.role === 'system')
+                    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);
+                        }
                         continue;
+                    }
                     ctx.runMgr.pushMessage(msg);
                     if (workingStateManager && msg.role === 'user' && msg.content) {
                         extractFromUserMessage(workingStateManager, msg.content, isFirstUserMessage);
@@ -1040,6 +1358,23 @@ export async function* query(params) {
                 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:
             //
@@ -1056,6 +1391,20 @@ export async function* query(params) {
             // 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).
@@ -1079,14 +1428,24 @@ export async function* query(params) {
                 });
                 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 }, eventTranslator.emitEvent);
+                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 = params.runConfig.sandbox?.workspace === 'working-directory';
+                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
@@ -1104,12 +1463,52 @@ export async function* query(params) {
                         details: { workspace: 'working-directory' },
                     });
                 }
-                sandbox = await params.sandboxProvider.create({
-                    ...(rootAtCwd ? { workingDirectory: ctx.cwd } : {}),
-                    timeoutMs: params.runConfig.sandbox?.timeoutMs,
-                    memoryLimitMb: params.runConfig.sandbox?.memoryLimitMb,
-                    maxProcesses: params.runConfig.sandbox?.maxProcesses,
+                const acquisition = await acquireSandbox({
+                    provider: params.sandboxProvider,
+                    config: {
+                        ...(rootAtCwd ? { workingDirectory: ctx.cwd } : {}),
+                        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 (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),
+                        });
+                    }
+                    yield* resultAssembler.completeRun(rootSpan);
+                    return await resultAssembler.finalize();
+                }
+                sandbox = acquisition.sandbox;
                 toolExecutor.setSandbox(sandbox);
                 await eventTranslator.emitEvent({
                     type: 'sandbox_created',
@@ -1210,7 +1609,7 @@ export async function* query(params) {
             }
             yield* iterationOrchestrator.runLoop();
             if (params.pluginManager) {
-                const hookResults = await params.pluginManager.executeHooks('run_end', { runId: ctx.runId }, eventTranslator.emitEvent);
+                const hookResults = await params.pluginManager.executeHooks('run_end', { runId: ctx.runId, signal: ctx.abortController.signal }, eventTranslator.emitEvent);
                 applyLifecycleHookResults('run_end', hookResults);
                 yield* eventTranslator.drainPending();
             }
@@ -1326,19 +1725,20 @@ export async function* query(params) {
             // --- Sandbox lifecycle: destroy after run ---
             if (sandbox) {
                 const sandboxId = sandbox.id;
-                try {
-                    await sandbox.destroy();
+                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 });
                 }
-                catch (destroyErr) {
+                else {
                     ctx.log.error('Sandbox destroy failed', {
                         'namzu.sandbox.id': sandboxId,
-                        'exception.message': destroyErr instanceof Error ? destroyErr.message : String(destroyErr),
+                        ...errorAttributes(teardown.error),
                     });
                 }
             }
@@ -1363,20 +1763,31 @@ export async function* query(params) {
  * either way — a stale cursor belongs to the client, and must not be able to
  * stop the work.
  */
-async function* catchUpFromCursor(runMgr, cursor, onEventReplay, generation) {
+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);
-    onEventReplay?.(replay);
+    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;
 }
-export async function drainQuery(params, listener) {
-    const fullParams = {
-        ...params,
-        resumeHandler: params.resumeHandler ?? autoApproveHandler,
-    };
+async function drainPreparedQuery(fullParams, listener) {
     const gen = query(fullParams);
     let result = await gen.next();
     while (!result.done) {
@@ -1387,6 +1798,48 @@ export async function drainQuery(params, listener) {
     }
     return result.value;
 }
+export async function drainQuery(params, listener) {
+    const fullParams = {
+        ...params,
+        resumeHandler: params.resumeHandler ?? autoApproveHandler,
+    };
+    return await drainPreparedQuery(fullParams, listener);
+}
+/** @internal Canonical resume state already selected by `resumeRun`. */
+export async function drainQueryWithSelectedResumeState(params, state, listener) {
+    const fullParams = {
+        ...params,
+        resumeHandler: params.resumeHandler ?? autoApproveHandler,
+    };
+    if (fullParams.resumeFromCheckpoint !== state.checkpointId) {
+        throw new Error('The selected resume state does not match the requested checkpoint.');
+    }
+    assertSelectedResumeAttribution(fullParams, state);
+    selectedResumeStates.set(fullParams, state);
+    return await drainPreparedQuery(fullParams, listener);
+}
+function assertSelectedResumeAttribution(params, state) {
+    const mismatchedFields = [];
+    if (params.runId !== state.runId)
+        mismatchedFields.push('runId');
+    if (params.sessionId !== state.sessionId)
+        mismatchedFields.push('sessionId');
+    if (params.topicId !== state.topicId)
+        mismatchedFields.push('topicId');
+    if (params.projectId !== state.projectId)
+        mismatchedFields.push('projectId');
+    if (params.tenantId !== state.tenantId)
+        mismatchedFields.push('tenantId');
+    if (params.parentRunId !== state.parentRunId)
+        mismatchedFields.push('parentRunId');
+    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.',
+        details: { fields: mismatchedFields },
+    });
+}
 function withDeferredDiscoveryTool(tools, allowedTools) {
     if (!allowedTools)
         return undefined;