@namzu/sdk 27.1.0 → 28.0.0

package/src/runtime/query/index.ts

@@ -6,6 +6,8 @@ import {
 	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 { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
@@ -13,6 +15,7 @@ import type { ContextReducer } from '../../compaction/reducer.js'
 import { serializeState as serializeWorkingState } from '../../compaction/serializer.js'
 import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire.js'
 import type { CompactionConfig } from '../../config/runtime.js'
+import { BOOT_EVENT_NAMES } from '../../constants/telemetry/index.js'
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
 import { EmergencySaveManager } from '../../manager/run/emergency.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
@@ -24,7 +27,9 @@ import {
 	withProviderFallback,
 } from '../../provider/fallback.js'
 import { type ProviderRetryConfig, withProviderRetry } from '../../provider/retry.js'
+import { DefaultFilesystemMigrator, loggingMigrationSink } from '../../session/migration/index.js'
 import type { PathBuilder } from '../../session/workspace/path-builder.js'
+import { resolveAttachments } from '../../store/attachment/index.js'
 import {
 	GENAI,
 	NAMZU,
@@ -45,6 +50,7 @@ import type { AdvisoryConfig } from '../../types/advisory/index.js'
 import type { AgentRuntimeContext, RuntimeToolOverrides } from '../../types/agent/base.js'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
 import type { WorkingMemoryProvider } from '../../types/agent/working-memory.js'
+import type { AuthorizationGateConfig } from '../../types/authorization/index.js'
 import { NamzuError } from '../../types/errors/index.js'
 import type { InputGuardrailSpec, OutputGuardrailSpec } from '../../types/guardrail/index.js'
 import {
@@ -60,11 +66,12 @@ import type { AgentPersona } from '../../types/persona/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
 import type { ReviewAnswer } from '../../types/run/answer-review.js'
-import type { CheckpointStore, ClaimFence } from '../../types/run/checkpoint-store.js'
+import type { CheckpointStore, FencingToken } from '../../types/run/checkpoint-store.js'
 import type { RunEventCursor, RunEventReplay } from '../../types/run/event-cursor.js'
 import { resolveRunEventReplay } from '../../types/run/event-cursor.js'
 import type {
 	AgentRunConfig,
+	BeforeStep,
 	PrepareStepChain,
 	Run,
 	RunEvent,
@@ -76,19 +83,23 @@ import type { PromoteMemory } from '../../types/run/memory-promotion.js'
 import { memoryCandidateFor } from '../../types/run/memory-promotion.js'
 import type { RunStore } from '../../types/run/store.js'
 import type { Sandbox, SandboxProvider } from '../../types/sandbox/index.js'
-import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import type { ProjectId, TopicId } from '../../types/session/ids.js'
 import type { Skill } from '../../types/skills/index.js'
 import type { StructuredOutputConfig } from '../../types/structured-output/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
 import type { RepairToolCall } from '../../types/tool/repair.js'
-import type { VerificationGateConfig } from '../../types/verification/index.js'
 import type { BackoffPolicy } from '../../utils/backoff.js'
 import type { ModelPricing } from '../../utils/cost.js'
-import { getRootLogger } from '../../utils/logger.js'
-import { VerificationGate } from '../../verification/gate.js'
+import { toErrorMessage } from '../../utils/error.js'
+import { generateRunId } from '../../utils/id.js'
+import { errorAttributes } from '../../utils/log/exception.js'
+import { EVENT_NAME_ATTRIBUTE } from '../../utils/log/types.js'
+import type { Logger } from '../../utils/logger.js'
+import { pickRenamed } from '../../utils/renamed-field.js'
+import type { BackgroundJobRegistry } from '../jobs/registry.js'
+import { AUTO_APPROVE_POLICY_NAME, createRunApprovalPolicy } from './approval-policy.js'
 import { CheckpointManager } from './checkpoint.js'
-import type { ContextCache } from './context-cache.js'
 import { RunContextFactory } from './context.js'
 import { EventTranslator } from './events.js'
 import { GuardCoordinator } from './guard.js'
@@ -97,9 +108,11 @@ 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 type { PromptCache } from './prompt-cache.js'
 import { PromptBuilder } from './prompt.js'
 import type { PromptSegments } from './prompt.js'
 import { PendingAnswers, QuestionParkBinding } from './question-park.js'
+import { RepeatCallTracker } from './repeat-call.js'
 import { ResultAssembler } from './result.js'
 import {
 	type PendingResumePlan,
@@ -115,6 +128,22 @@ import { createToolPause } from './tool-pause.js'
 import { ToolingBootstrap } from './tooling.js'
 
 export interface QueryParams {
+	/**
+	 * Notice when the model issues the identical tool call repeatedly, and
+	 * say so on the next `tool_result`. Defaults on.
+	 *
+	 * `false` removes the tracker entirely rather than gating a branch, so
+	 * an opted-out run produces byte-identical messages to one from before
+	 * this existed.
+	 */
+	repeatCallAdvisory?: boolean
+
+	/**
+	 * Tool names this run may not use, subtracted from its effective list.
+	 * See {@link import('../../types/agent/base.js').BaseAgentConfig.deniedTools}.
+	 */
+	deniedTools?: readonly string[]
+
 	systemPrompt?: string
 	persona?: AgentPersona
 	skills?: Skill[]
@@ -209,6 +238,54 @@ export interface QueryParams {
 
 	/** Default per-tool execution deadline. See {@link ToolDefinition.timeoutMs}. */
 	toolTimeoutMs?: number
+	/**
+	 * Where background jobs this run starts are held, and killed.
+	 *
+	 * Host-owned so it can outlive one run — a registry built per run could
+	 * never be the thing that kills a run's jobs when the run is already
+	 * gone. This run's jobs are torn down in the `finally` below; another
+	 * run's are untouched.
+	 */
+	backgroundJobs?: BackgroundJobRegistry
+
+	/**
+	 * What else goes in this run's prompt.
+	 *
+	 * `static` and `dynamic` contributions reach the system prompt through
+	 * `PromptBuilder`; `turn` contributions reach the ephemeral trailing
+	 * message once per iteration. A host registers once and the placement
+	 * decides where it lands.
+	 */
+	promptContributions?: import('../../prompt/contributions.js').PromptContributionRegistry
+
+	/**
+	 * Where the `skill` tool loads from.
+	 *
+	 * Separate from `skills`, which is the LIST that goes in the prompt
+	 * manifest. A run can have the manifest without the tool — that is what
+	 * every run did before the tool existed — and the two are wired
+	 * independently on purpose: a host may want the guidance visible without
+	 * granting a way to pull bodies in mid-run.
+	 */
+	skillRegistry?: import('../../types/tool/index.js').SkillRegistryRef
+
+	/**
+	 * Where a message's stored attachments are resolved from.
+	 *
+	 * Absent is fine for every run whose attachments are inline, which is
+	 * every run that existed before this. A message carrying a ref with no
+	 * store REFUSES rather than dropping the attachment.
+	 */
+	attachmentStore?: import('../../store/attachment/index.js').AttachmentStore
+
+	/**
+	 * How this run reaches the web.
+	 *
+	 * `fetch` and `search` are independent, and this kernel ships only the
+	 * first — see `connector/web` for why choosing a search backend here
+	 * would choose it for every consumer.
+	 */
+	web?: import('../../types/tool/index.js').ToolContext['web']
 
 	/**
 	 * Wait between in-loop retries of a failed tool call, with full jitter.
@@ -317,6 +394,11 @@ export interface QueryParams {
 	 * Fails open — a throw leaves the step with the run's configuration.
 	 */
 	prepareStep?: PrepareStepChain
+	/**
+	 * Refuse the next model call before it is made. See {@link BeforeStep}.
+	 * A throw fails CLOSED, opposite to `prepareStep` beside it.
+	 */
+	beforeStep?: BeforeStep
 
 	/**
 	 * Force the run to finish by calling a schema-validated tool, and land
@@ -406,13 +488,13 @@ export interface QueryParams {
 	sessionId: SessionId
 
 	/**
-	 * Topic the Session lives under. Required in 0.3.0 — every run carries
-	 * the full five-layer scope (Tenant → Project → Thread → Session →
-	 * Run). Denormalized from `session.threadId`; callers build this
-	 * alongside `sessionId` so the query pipeline never needs a second
-	 * SessionStore round-trip to recover it.
+	 * Topic the Session lives under. Required — every run carries the full
+	 * five-layer scope (Tenant → Project → Topic → Session → Run).
+	 * Denormalized from `session.topicId`; callers build this alongside
+	 * `sessionId` so the query pipeline never needs a second SessionStore
+	 * round-trip to recover it.
 	 */
-	threadId: ThreadId
+	topicId: TopicId
 
 	/** Long-lived goal scope for the run. Required. */
 	projectId: ProjectId
@@ -455,7 +537,7 @@ export interface QueryParams {
 	 * takes no fence, so two workers that both took one run still overwrite
 	 * each other's run record, transcript and report — see the changeset.
 	 */
-	claimFence?: ClaimFence
+	claimFence?: FencingToken
 
 	/**
 	 * Where this run records its own evidence — the run record, its messages,
@@ -511,7 +593,14 @@ export interface QueryParams {
 
 	depth?: number
 
-	contextCache?: ContextCache
+	/**
+	 * @deprecated Renamed to {@link QueryParams.promptCache}. Removed in the
+	 * next major. Setting both to different instances throws rather than
+	 * picking one.
+	 */
+	contextCache?: PromptCache
+
+	promptCache?: PromptCache
 
 	contextLevel?: AgentContextLevel
 
@@ -523,7 +612,60 @@ export interface QueryParams {
 
 	runtimeContext?: AgentRuntimeContext
 
-	taskGateway?: import('../../types/agent/gateway.js').TaskGateway
+	/**
+	 * @deprecated Renamed to {@link QueryParams.taskScheduler}. Removed in
+	 * the next major. Setting both to different instances throws.
+	 */
+	taskGateway?: import('../../types/agent/scheduler.js').TaskScheduler
+
+	taskScheduler?: import('../../types/agent/scheduler.js').TaskScheduler
+
+	/**
+	 * Text queued for this run since its last turn, drained at the boundary.
+	 *
+	 * A callback because the queue belongs to whoever accepts the messages,
+	 * and an array captured here would be whatever was queued before the run
+	 * started. See `BaseAgentConfig.inboundMessages` for what it closes.
+	 */
+	inboundMessages?: () => import('../../types/message/index.js').Message[]
+
+	/**
+	 * Where this conversation's durable state lives.
+	 *
+	 * Supplies the permission mode when `runConfig.permissionMode` names
+	 * none, and receives the flip when a plan is approved. Absent is the
+	 * ordinary case: a run with no topic state behaves exactly as it did.
+	 */
+	topicStateStore?: import('../../store/topic/state.js').TopicStateStore
+
+	/**
+	 * The live permission-mode box, when the caller holds one too.
+	 *
+	 * Whoever builds the coordinator tools needs to flip this from the
+	 * approval hook, and that is not this function. Sharing the object is
+	 * what lets an approved plan leave plan mode in the SAME run.
+	 */
+	permissionModeRef?: { current: import('../../types/permission/index.js').PermissionMode }
+
+	/**
+	 * A name for the policy `resumeHandler` implements.
+	 *
+	 * Only ever written to the durable log and shown to an operator, so it
+	 * costs nothing to omit — but omitting it means every entry about who
+	 * approved something says `host`, which is the answer that helps least.
+	 */
+	approvalPolicyName?: string
+
+	/**
+	 * Receive this run's approval-policy box, so it can be swapped mid-run.
+	 *
+	 * The box is built HERE rather than passed in, unlike
+	 * {@link permissionModeRef}, because changing the policy emits a durable
+	 * event and only the run holds the emitter. A host that constructed its
+	 * own box would be able to change the policy without recording it, which
+	 * is the one thing this must not allow.
+	 */
+	onApprovalPolicy?: (policy: import('../../types/hitl/policy.js').RunApprovalPolicy) => void
 
 	/**
 	 * Where a worker completion goes when no tool call is waiting for it.
@@ -533,7 +675,7 @@ export interface QueryParams {
 	 * and the loop delivers what is left. Omitted, the loop drains nothing and
 	 * the behaviour is exactly what it was before the inbox existed.
 	 */
-	completionInbox?: import('../../gateway/completion-inbox.js').CompletionInbox
+	completionInbox?: import('../../scheduler/completion-inbox.js').CompletionInbox
 
 	onContextCreated?: (ctx: {
 		planManager: import('../../manager/plan/lifecycle.js').PlanManager
@@ -566,7 +708,13 @@ export interface QueryParams {
 
 	agentBus?: import('../../bus/index.js').AgentBus
 
-	verificationGate?: VerificationGateConfig
+	/**
+	 * @deprecated Renamed to `authorizationGate`. Removed in the next major.
+	 * Setting both to different configs throws.
+	 */
+	verificationGate?: AuthorizationGateConfig
+
+	authorizationGate?: AuthorizationGateConfig
 
 	pluginManager?: import('../../plugin/lifecycle.js').PluginLifecycleManager
 
@@ -667,14 +815,112 @@ function assertBudgetIsMeasurable(params: QueryParams): void {
 	})
 }
 
+/**
+ * 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: LLMProvider,
+	model: string | undefined,
+	signal: AbortSignal | undefined,
+	log: Logger,
+): Promise<number | undefined> {
+	if (!provider.resolveContextWindow || !model) return undefined
+	try {
+		const reported = await provider.resolveContextWindow(model, signal)
+		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
+	}
+}
+
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
+	// 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 = pickRenamed(
+		'contextCache',
+		params.contextCache,
+		'promptCache',
+		params.promptCache,
+	)
+	const taskScheduler = pickRenamed(
+		'taskGateway',
+		params.taskGateway,
+		'taskScheduler',
+		params.taskScheduler,
+	)
+
+	// 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 log = RunContextFactory.buildLogger({
+		agentName: params.agentName,
+		runConfig: params.runConfig,
+		runId,
+		parentRunId: params.parentRunId,
+		sessionId: params.sessionId,
+		topicId: params.topicId,
+		projectId: params.projectId,
+		tenantId: params.tenantId,
+	})
+
 	// Boot-time filesystem migration (session-hierarchy.md §13.4.1). First
 	// call per process per root actually runs; subsequent calls short-circuit
 	// via the in-memory guard in `context.ts`. Kept here rather than inside
 	// the synchronous `RunContextFactory.build` so the factory signature stays
 	// sync for tests / non-async call sites.
+	//
+	// The migrator built here — not `ensureMigrated`'s own default — is what
+	// turns the migration facts `DefaultFilesystemMigrator` already computes
+	// into a `namzu.migration.completed` record instead of discarding them.
+	// `ensureMigrated`'s default parameter stays
+	// `NOOP_FILESYSTEM_MIGRATION_SINK` (see `context.ts`), so any other path
+	// that reaches `ensureMigrated` keeps today's silent behaviour.
 	const cwdForMigration = params.workingDirectory ?? process.cwd()
-	await RunContextFactory.ensureMigrated(`${cwdForMigration}/.namzu`)
+	const migrationResult = await RunContextFactory.ensureMigrated(
+		`${cwdForMigration}/.namzu`,
+		new DefaultFilesystemMigrator(loggingMigrationSink(log)),
+	)
+	// `loggingMigrationSink` only ever hears about `kind: 'migrated'` — the
+	// only outcome `DefaultFilesystemMigrator` ever hands its sink (see the
+	// module doc on `FilesystemMigrationSink`). The other two are logged
+	// here, straight off the resolved result, rather than by widening
+	// `FilesystemMigrationEvent` to carry them: a wider union would need a
+	// new arm in every exhaustive switch already written over it — a major —
+	// for two outcomes `migrationResult.kind` already fully describes.
+	if (migrationResult.kind !== 'migrated') {
+		log.debug('filesystem migration: nothing to do', {
+			[EVENT_NAME_ATTRIBUTE]: BOOT_EVENT_NAMES.MIGRATION_COMPLETED,
+			// `namzu.migration.*`, matching `loggingMigrationSink` — the OTHER
+			// emitter of this same event name. Two emitters of one event writing
+			// two namespaces for the same fact is precisely the collision the
+			// namespaced-key rule exists to stop, and a per-module derivation is
+			// how it would be reintroduced.
+			'namzu.migration.kind': migrationResult.kind,
+			'namzu.migration.marker_path': migrationResult.markerPath,
+		})
+	}
 
 	// Every model call in the run — the loop's turns, the forced-final
 	// summary, advisory and compaction side calls — goes through this one
@@ -701,9 +947,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	assertCostIsAttributable(chain, params.pricing)
 	assertBudgetIsMeasurable(params)
 	const withRetry = (provider: LLMProvider): LLMProvider =>
-		params.retry === false
-			? provider
-			: withProviderRetry(provider, { config: params.retry, log: getRootLogger() })
+		params.retry === false ? provider : withProviderRetry(provider, { 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
@@ -717,7 +961,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	const resilientProvider = withProviderFallback(
 		chain.map((member) => ({ ...member, provider: withRetry(member.provider) })),
 		{
-			log: getRootLogger(),
+			log,
 			onSwap: (to) => {
 				serving.current = to
 				// `ctx` is declared below and is initialized before anything can
@@ -728,7 +972,74 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		},
 	)
 
+	// 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,
+		params.runConfig.model,
+		params.signal,
+		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.
+	//
+	// 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: unknown) => {
+					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: readonly Message[] = params.topicStateStore
+		? await drainQueuedMessages(params.topicStateStore, params.topicId, params.tenantId).catch(
+				(err: unknown) => {
+					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: Message[] =
+		queuedForThisRun.length > 0 ? [...queuedForThisRun, ...params.messages] : params.messages
+	const initialMessages: Message[] = [...(await resolveAttachments(seeded, params.attachmentStore))]
+
 	const ctx = RunContextFactory.build({
+		...(topicState ? { topicPermissionMode: topicState.permissionMode } : {}),
+		...(params.permissionModeRef ? { permissionModeRef: params.permissionModeRef } : {}),
 		agentId: params.agentId,
 		agentName: params.agentName,
 		runConfig: params.runConfig,
@@ -736,22 +1047,52 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		workingDirectory: params.workingDirectory,
 		pricing: params.pricing,
 		enableActivityTracking: params.enableActivityTracking,
-		messages: params.messages,
+		messages: initialMessages,
 		signal: params.signal,
 		sessionId: params.sessionId,
-		threadId: params.threadId,
+		topicId: params.topicId,
 		projectId: params.projectId,
 		tenantId: params.tenantId,
 		pathBuilder: params.pathBuilder,
 		checkpointStore: params.checkpointStore,
 		runStore: params.runStore,
-		runId: params.runId,
+		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),
 	})
 
 	ctx.planManager.setApprovalHandler(async (request) => {
-		const decision = await params.resumeHandler({
+		// `.current.handler`, never a captured `params.resumeHandler`. That
+		// capture is what made changing the policy mean ending the run.
+		const decision = await approvalPolicy.current.handler({
 			type: 'plan_approval',
 			runId: ctx.runId,
 			checkpointId: `cp_plan_${request.planId}` as import('../../types/ids/index.js').CheckpointId,
@@ -788,7 +1129,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		return { approved: false, feedback: `Action: ${decision.action}` }
 	})
 
-	const eventTranslator = new EventTranslator(ctx.runMgr)
+	const eventTranslator = new EventTranslator(ctx.runMgr, undefined, ctx.log)
 	eventTranslator.wireActivityStore(ctx.activityStore, ctx.runId)
 	eventTranslator.wirePlanManager(ctx.planManager, ctx.runId)
 	const unsubscribeTaskStore = params.taskStore
@@ -853,9 +1194,10 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				details: { providerId: params.provider.id, capability: 'tools', registeredToolCount },
 			})
 		}
-		ctx.log.warn(`CAPABILITY MISMATCH: ${message}`, {
-			providerId: params.provider.id,
-			registeredToolCount,
+		ctx.log.warn('Capability mismatch: the provider declares no tool support', {
+			'namzu.capability.detail': message,
+			[GENAI.SYSTEM]: params.provider.id,
+			'namzu.runtime.registered_tool_count': registeredToolCount,
 		})
 	}
 
@@ -868,9 +1210,10 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				details: { providerId: params.provider.id, capability: 'vision', attachmentMessageCount },
 			})
 		}
-		ctx.log.warn(`CAPABILITY MISMATCH: ${message}`, {
-			providerId: params.provider.id,
-			attachmentMessageCount,
+		ctx.log.warn('Capability mismatch: the provider declares no vision support', {
+			'namzu.capability.detail': message,
+			[GENAI.SYSTEM]: params.provider.id,
+			'namzu.runtime.attachment_message_count': attachmentMessageCount,
 		})
 	}
 
@@ -883,15 +1226,32 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				details: { providerId: params.provider.id, capability: 'documents', documentMessageCount },
 			})
 		}
-		ctx.log.warn(`CAPABILITY MISMATCH: ${message}`, {
-			providerId: params.provider.id,
-			documentMessageCount,
+		ctx.log.warn('Capability mismatch: the provider declares no document support', {
+			'namzu.capability.detail': message,
+			[GENAI.SYSTEM]: params.provider.id,
+			'namzu.runtime.document_message_count': documentMessageCount,
 		})
 	}
 
-	const effectiveAllowedTools = stripToolSurfaces
+	// Denied names are subtracted LAST, after the allow-list is resolved
+	// against the registry — so a deny reaches a run that named no
+	// allow-list at all, which is the ordinary case for a delegated child.
+	// Applied to `effectiveAllowedTools`, which `query()` binds to both the
+	// request tool list AND the `ToolExecutor`: narrowing only the request
+	// shows the model fewer tools and lets it call any of them by name.
+	const allowedBeforeDenial = stripToolSurfaces
 		? []
 		: withDeferredDiscoveryTool(params.tools, params.allowedTools)
+	const denied = new Set(params.deniedTools ?? [])
+	const effectiveAllowedTools: string[] | undefined =
+		denied.size === 0
+			? allowedBeforeDenial
+			: // An absent allow-list means "every registered tool", so a deny
+				// with no allow-list has to be resolved against the registry
+				// here — otherwise the subtraction would be from an empty list
+				// and would deny nothing, which is the shape a delegated child
+				// arrives in.
+				[...(allowedBeforeDenial ?? params.tools.listNames())].filter((name) => !denied.has(name))
 
 	// The two halves of a durable pause, owned by the RUN when the host
 	// does not own them.
@@ -922,12 +1282,18 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			tools: params.tools,
 			runId: ctx.runId,
 			workingDirectory: ctx.cwd,
-			permissionMode: ctx.permissionMode,
+			permissionMode: () => ctx.permissionMode.current,
 			env: params.runConfig.env ?? {},
 			abortSignal: ctx.abortController.signal,
 			allowedTools: effectiveAllowedTools,
 			invocationState: params.invocationState,
 			pluginManager: params.pluginManager,
+			...(params.backgroundJobs ? { backgroundJobs: params.backgroundJobs } : {}),
+			// The `skill` tool's registry. Threaded from the run rather than
+			// held by the tool, because a tool that reached for a module-level
+			// registry would answer about whatever the last run configured.
+			...(params.skillRegistry ? { skills: params.skillRegistry } : {}),
+			...(params.web ? { web: params.web } : {}),
 			...(params.toolTimeoutMs !== undefined ? { toolTimeoutMs: params.toolTimeoutMs } : {}),
 			...(params.toolRetryBackoff !== undefined
 				? { toolRetryBackoff: params.toolRetryBackoff }
@@ -955,7 +1321,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				createToolPause({
 					runId: ctx.runId,
 					toolUseId,
-					parkHandler: params.resumeHandler,
+					parkHandler: (request) => approvalPolicy.current.handler(request),
 					recorder: questionParks,
 					pendingAnswers,
 				}),
@@ -979,6 +1345,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		tools: params.tools,
 		allowedTools: effectiveAllowedTools,
 		runtimeContext: params.runtimeContext,
+		...(params.promptContributions ? { contributions: params.promptContributions } : {}),
 	})
 
 	const guard = new GuardCoordinator({
@@ -1013,6 +1380,10 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		// Read at settle time, not now: checkpoints are written per
 		// iteration, so the answer changes as the run proceeds.
 		resumeCheckpointId: () => checkpointMgr.lastCheckpointId,
+		// Read only to recover WHY a cancellation happened. The run loop
+		// already knows THAT it was cancelled; the origin lives on the abort
+		// reason and nothing else carries it this far.
+		signal: ctx.abortController.signal,
 	})
 
 	let advisoryCtx: AdvisoryContext | undefined
@@ -1072,8 +1443,20 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		}
 	}
 
-	const verificationGate = params.verificationGate?.enabled
-		? new VerificationGate(params.verificationGate, ctx.log)
+	// One resolve, one construction. Four sites read this field, and had
+	// each read `params.verificationGate` directly a host that set only the
+	// new name would get a gate on one path and none on another — which for
+	// an AUTHORIZATION gate means a tool call permitted somewhere it should
+	// have been refused. That is the failure this field's window has to not
+	// have.
+	const gateConfig = pickRenamed(
+		'verificationGate',
+		params.verificationGate,
+		'authorizationGate',
+		params.authorizationGate,
+	)
+	const verificationGate = gateConfig?.enabled
+		? new AuthorizationGate(gateConfig, ctx.log)
 		: undefined
 
 	const iterationOrchestrator = new IterationOrchestrator({
@@ -1082,6 +1465,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		runConfig: params.runConfig,
 		...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),
 		...(params.prepareStep ? { prepareStep: params.prepareStep } : {}),
+		...(params.beforeStep ? { beforeStep: params.beforeStep } : {}),
 		...(params.onStepFinish ? { onStepFinish: params.onStepFinish } : {}),
 		...(params.reviewAnswer ? { reviewAnswer: params.reviewAnswer } : {}),
 		...(params.maxAnswerReviews !== undefined ? { maxAnswerReviews: params.maxAnswerReviews } : {}),
@@ -1099,17 +1483,27 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		drainPending: () => eventTranslator.drainPending(),
 		abortController: ctx.abortController,
 		log: ctx.log,
-		resumeHandler: params.resumeHandler,
+		// Read through the box on every call, so a swap lands on the next
+		// question rather than the next run.
+		resumeHandler: (request) => approvalPolicy.current.handler(request),
+		takeApprovalPolicyChange: () => approvalPolicy.takeUnannouncedChange(),
+		...(params.promptContributions ? { promptContributions: params.promptContributions } : {}),
 		...(params.steering ? { steering: params.steering } : {}),
 		checkpointMgr,
 		planManager: ctx.planManager,
-		taskGateway: params.taskGateway,
+		taskGateway: taskScheduler,
 		completionInbox: params.completionInbox,
 		taskStore: params.taskStore,
 		// Run-scoped. An approval is a statement about this run's work;
 		// carrying one into a later run would be reuse nobody agreed to.
 		toolGrants: new ToolGrantSet(),
+		// Run-scoped for the same reason. A repeat count carried into a later
+		// run is a claim about work nobody repeated, and a module-level map
+		// would leak exactly that way.
+		...(params.repeatCallAdvisory === false ? {} : { repeatCalls: new RepeatCallTracker() }),
 		compactionConfig: params.compactionConfig,
+		...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
+		...(providerContextWindow !== undefined ? { providerContextWindow } : {}),
 		workingStateManager,
 		taskRouter: params.taskRouter,
 		contextReducer: params.contextReducer,
@@ -1196,9 +1590,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					// because a host building an approval queue from durable
 					// state will not see this question.
 					ctx.log.error('Failed to record a question park — it is not resumable', {
-						runId: ctx.runMgr.id,
-						questionId: question.questionId,
-						error: err instanceof Error ? err.message : String(err),
+						[NAMZU.RUN_ID]: ctx.runMgr.id,
+						'namzu.runtime.question_id': question.questionId,
+						'exception.message': err instanceof Error ? err.message : String(err),
 					})
 					return null
 				}
@@ -1206,9 +1600,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			resolve: async (checkpointId, decision) => {
 				await checkpointMgr.unpark(checkpointId, decision).catch((err: unknown) => {
 					ctx.log.error('Failed to clear a recorded question park', {
-						runId: ctx.runMgr.id,
-						checkpointId,
-						error: err instanceof Error ? err.message : String(err),
+						[NAMZU.RUN_ID]: ctx.runMgr.id,
+						'namzu.checkpoint.id': checkpointId,
+						'exception.message': err instanceof Error ? err.message : String(err),
 					})
 					return null
 				})
@@ -1272,13 +1666,13 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			params.onContextCreated?.({ planManager: ctx.planManager })
 
 			ctx.log.info('Starting query', {
-				runId: ctx.runMgr.id,
-				agent: params.agentName,
-				model: params.runConfig.model,
-				tokenBudget: params.runConfig.tokenBudget,
-				activityTracking: ctx.activityStore.enabled,
-				permissionMode: ctx.permissionMode,
-				resumeFromCheckpoint: params.resumeFromCheckpoint ?? null,
+				[NAMZU.RUN_ID]: ctx.runMgr.id,
+				'namzu.runtime.agent': params.agentName,
+				[GENAI.REQUEST_MODEL]: params.runConfig.model,
+				'namzu.runtime.token_budget': params.runConfig.tokenBudget,
+				'namzu.runtime.activity_tracking': ctx.activityStore.enabled,
+				'namzu.runtime.permission_mode': ctx.permissionMode.current,
+				'namzu.runtime.resume_from_checkpoint': params.resumeFromCheckpoint ?? null,
 			})
 
 			const contextLevel = params.contextLevel ?? 'full'
@@ -1290,19 +1684,16 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				tools: params.tools,
 				allowedTools: effectiveAllowedTools,
 				runtimeContext: params.runtimeContext,
+				...(params.promptContributions ? { contributions: params.promptContributions } : {}),
 			}
 
-			const segments: PromptSegments = params.contextCache
-				? params.contextCache.getSystemPromptSegmented(
-						cacheInput,
-						contextLevel,
-						params.workingDirectory,
-					)
+			const segments: PromptSegments = promptCache
+				? promptCache.getSystemPromptSegmented(cacheInput, contextLevel, params.workingDirectory)
 				: promptBuilder.buildSegmented(contextLevel, params.workingDirectory)
 
 			ctx.log.info('Prompt segments assembled', {
-				staticLength: segments.static.length,
-				dynamicLength: segments.dynamic.length,
+				'namzu.runtime.static_length': segments.static.length,
+				'namzu.runtime.dynamic_length': segments.dynamic.length,
 			})
 
 			const pushSystemMessages = (): void => {
@@ -1345,18 +1736,18 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					const revived = restoreWorkingState(checkpoint.workingState, params.compactionConfig)
 					workingStateManager.replaceState(revived.getState())
 					ctx.log.info('Restored compaction working state from checkpoint', {
-						runId: ctx.runMgr.id,
-						checkpointId: checkpoint.id,
-						slots: workingStateManager.slotCount(),
+						[NAMZU.RUN_ID]: ctx.runMgr.id,
+						'namzu.checkpoint.id': checkpoint.id,
+						'namzu.runtime.slots': workingStateManager.slotCount(),
 					})
 				}
 				ctx.log.info('Restored budgets from checkpoint', {
-					runId: ctx.runMgr.id,
-					checkpointId: checkpoint.id,
-					totalTokens: checkpoint.tokenUsage.totalTokens,
-					totalCost: checkpoint.costInfo.totalCost,
-					iteration: checkpoint.guardState.iterationCount,
-					elapsedMs: checkpoint.guardState.elapsedMs,
+					[NAMZU.RUN_ID]: ctx.runMgr.id,
+					'namzu.checkpoint.id': checkpoint.id,
+					'namzu.usage.total_tokens': checkpoint.tokenUsage.totalTokens,
+					'namzu.runtime.total_cost': checkpoint.costInfo.totalCost,
+					[NAMZU.ITERATION]: checkpoint.guardState.iterationCount,
+					'namzu.runtime.elapsed_ms': checkpoint.guardState.elapsedMs,
 				})
 
 				pushSystemMessages()
@@ -1409,11 +1800,12 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					: removeDanglingMessages(checkpoint.messages)
 				if (!dangling.isValid && !pendingResume) {
 					ctx.log.warn('Checkpoint contained unanswered tool calls — repaired on restore', {
-						runId: ctx.runMgr.id,
-						checkpointId: checkpoint.id,
-						unansweredAssistantTurns: dangling.assistantsWithUnmatchedCalls.length,
-						orphanedToolMessages: dangling.orphanedToolMessages.length,
-						removed: checkpoint.messages.length - restoredMessages.length,
+						[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,
 					})
 				}
 
@@ -1432,14 +1824,24 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					}
 					ctx.runMgr.pushMessage(msg)
 				}
+
+				// The queue, on the resume path too. It is drained
+				// unconditionally above, so leaving this out would take a
+				// host's "start with this" off the record and deliver it
+				// nowhere — the one outcome a durable queue must not have.
+				//
+				// AFTER the restored history rather than before it: on a
+				// resume the conversation already exists, and a message left
+				// for "the next run" is the newest thing said, not the oldest.
+				for (const queued of queuedForThisRun) ctx.runMgr.pushMessage(queued)
 			} else if (params.continuationMode) {
-				for (const msg of params.messages) {
+				for (const msg of initialMessages) {
 					ctx.runMgr.pushMessage(msg)
 				}
 			} else {
 				pushSystemMessages()
 				let isFirstUserMessage = true
-				for (const msg of params.messages) {
+				for (const msg of initialMessages) {
 					if (msg.role === 'system') continue
 					ctx.runMgr.pushMessage(msg)
 
@@ -1463,6 +1865,23 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			})
 			yield* eventTranslator.drainPending()
 
+			// The box is handed out HERE, after `run_started`, and the position
+			// is load-bearing rather than tidy. It moved twice:
+			//
+			//  1. Beside the box's construction — a host that called `set`
+			//     synchronously reached `eventTranslator` inside its temporal
+			//     dead zone and killed the run before it started.
+			//  2. Beside the translator's construction — the translator existed,
+			//     but the run directory did not, so the durable append hit
+			//     ENOENT on `transcript.jsonl`.
+			//
+			// Both were found by the test that takes the box and immediately
+			// swaps the policy, which is not an exotic host: it is the shape of
+			// "start unattended" wiring. A policy change is durably recorded
+			// before it takes effect, so the handout cannot precede the run
+			// being writable.
+			params.onApprovalPolicy?.(approvalPolicy)
+
 			// 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).
@@ -1499,7 +1918,27 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 
 			// --- Sandbox lifecycle: create before iteration loop ---
 			if (params.sandboxProvider) {
+				const rootAtCwd = params.runConfig.sandbox?.workspace === 'working-directory'
+				// Checked against what the CALLER passed, not against `ctx.cwd`.
+				// `ctx.cwd` falls back to `process.cwd()`, so reading it here
+				// would silently root the sandbox at whatever directory the
+				// host process happens to be in — which is not the directory
+				// anybody asked to confine, and is worse than the temp dir the
+				// caller declined. Refused before the sandbox exists, and not
+				// downgraded to ephemeral: a caller who asked for confinement
+				// of a specific tree and quietly got an empty one has been
+				// told their files are protected by something that is not
+				// looking at them.
+				if (rootAtCwd && params.workingDirectory === undefined) {
+					throw new NamzuError({
+						code: 'invalid_config',
+						message:
+							"sandbox.workspace is 'working-directory' but this run has no workingDirectory. Pass one, or use the default 'ephemeral' — the kernel will not fall back to a temp directory, because that would confine a directory you did not name.",
+						details: { workspace: 'working-directory' },
+					})
+				}
 				sandbox = await params.sandboxProvider.create({
+					...(rootAtCwd ? { workingDirectory: ctx.cwd } : {}),
 					timeoutMs: params.runConfig.sandbox?.timeoutMs,
 					memoryLimitMb: params.runConfig.sandbox?.memoryLimitMb,
 					maxProcesses: params.runConfig.sandbox?.maxProcesses,
@@ -1515,9 +1954,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				yield* eventTranslator.drainPending()
 
 				ctx.log.info('Sandbox created for run', {
-					sandboxId: sandbox.id,
-					environment: sandbox.environment,
-					rootDir: sandbox.rootDir,
+					'namzu.sandbox.id': sandbox.id,
+					'namzu.execution.environment': sandbox.environment,
+					'namzu.runtime.root_dir': sandbox.rootDir,
 				})
 			}
 
@@ -1531,7 +1970,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				} else {
 					ctx.log.warn(
 						'emergencySave requested but the run has no output directory — crash dumps disabled',
-						{ runId: ctx.runId },
+						{ [NAMZU.RUN_ID]: ctx.runId },
 					)
 				}
 			}
@@ -1559,6 +1998,15 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					...(inputVerdict.reason ? { reason: inputVerdict.reason } : {}),
 				})
 				yield* eventTranslator.drainPending()
+				// A guardrail block is a refusal — first-class in the audit trail
+				// (LOG-14, design §5), not merely a RunEvent a host happens to be
+				// subscribed to when it fires.
+				await ctx.runMgr.recordAudit({
+					what: { action: 'guardrail:input', resource: inputVerdict.name },
+					outcome: 'refused',
+					reason: inputVerdict.reason ?? 'blocked by an input guardrail',
+					...(params.persona?.identity.role ? { persona: params.persona.identity.role } : {}),
+				})
 				ctx.runMgr.setStopReason('input_guardrail')
 				ctx.runMgr.setLastError(inputVerdict.reason ?? 'blocked by an input guardrail')
 				yield* resultAssembler.completeRun(rootSpan)
@@ -1570,9 +2018,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// tool that needs one gets it.
 			if (pendingResume) {
 				ctx.log.info('Applying a pending HITL decision to the checkpointed tool calls', {
-					runId: ctx.runId,
-					tools: pendingResume.response.message.toolCalls?.map((tc) => tc.function.name),
-					denied: pendingResume.denials.size,
+					[NAMZU.RUN_ID]: ctx.runId,
+					'namzu.tool.names': pendingResume.response.message.toolCalls?.map(
+						(tc) => tc.function.name,
+					),
+					'namzu.runtime.denied': pendingResume.denials.size,
 				})
 				// Hand the recorded answer to the already-built tool. The tool
 				// closed over its registry when the agent was constructed,
@@ -1598,9 +2048,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 						.unpark(resolvedCheckpointId, params.pendingDecision)
 						.catch((err: unknown) => {
 							ctx.log.error('Applied a pending decision but failed to clear the park', {
-								runId: ctx.runId,
-								checkpointId: resolvedCheckpointId,
-								error: err instanceof Error ? err.message : String(err),
+								[NAMZU.RUN_ID]: ctx.runId,
+								'namzu.checkpoint.id': resolvedCheckpointId,
+								'exception.message': err instanceof Error ? err.message : String(err),
 							})
 							return null
 						})
@@ -1651,6 +2101,13 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 						...(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('')
@@ -1680,6 +2137,30 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// 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.
+			if (params.backgroundJobs) {
+				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.
@@ -1697,8 +2178,9 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					await params.promoteMemory(candidate)
 				} catch (promoteErr) {
 					ctx.log.error('Memory promotion threw — the run is unaffected', {
-						runId: ctx.runId,
-						error: promoteErr instanceof Error ? promoteErr.message : String(promoteErr),
+						[NAMZU.RUN_ID]: ctx.runId,
+						'exception.message':
+							promoteErr instanceof Error ? promoteErr.message : String(promoteErr),
 					})
 				}
 			}
@@ -1713,11 +2195,12 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 						runId: ctx.runId,
 						sandboxId,
 					})
-					ctx.log.info('Sandbox destroyed', { sandboxId })
+					ctx.log.info('Sandbox destroyed', { 'namzu.sandbox.id': sandboxId })
 				} catch (destroyErr) {
 					ctx.log.error('Sandbox destroy failed', {
-						sandboxId,
-						error: destroyErr instanceof Error ? destroyErr.message : String(destroyErr),
+						'namzu.sandbox.id': sandboxId,
+						'exception.message':
+							destroyErr instanceof Error ? destroyErr.message : String(destroyErr),
 					})
 				}
 			}
@@ -1749,7 +2232,7 @@ async function* catchUpFromCursor(
 	runMgr: RunPersistence,
 	cursor: RunEventCursor,
 	onEventReplay: ((replay: RunEventReplay) => void) | undefined,
-	generation: ClaimFence | undefined,
+	generation: FencingToken | undefined,
 ): AsyncGenerator<RunEvent, void> {
 	const missed = await runMgr.getRunStore().readEvents({ sinceSeq: cursor.sinceSeq })
 	const replay = resolveRunEventReplay(