@namzu/sdk 27.0.0 → 28.0.0

package/dist/runtime/query/index.js

@@ -1,16 +1,21 @@
 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 { extractFromUserMessage } from '../../compaction/extractor.js';
 import { WorkingStateManager } from '../../compaction/manager.js';
 import { serializeState as serializeWorkingState } from '../../compaction/serializer.js';
 import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire.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 { resolveModelPricing } from '../../pricing/index.js';
 import { resolveProviderCapabilities } from '../../provider/capabilities.js';
 import { withProviderFallback, } from '../../provider/fallback.js';
 import { withProviderRetry } from '../../provider/retry.js';
+import { DefaultFilesystemMigrator, loggingMigrationSink } from '../../session/migration/index.js';
+import { resolveAttachments } from '../../store/attachment/index.js';
 import { GENAI, NAMZU, agentRunSpanName, parentContext, serializeSpan, } from '../../telemetry/attributes.js';
 import { recordRunDuration } from '../../telemetry/metrics.js';
 import { getTracer } from '../../telemetry/runtime-accessors.js';
@@ -23,8 +28,12 @@ import { autoApproveHandler, } from '../../types/hitl/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 { 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 { pickRenamed } from '../../utils/renamed-field.js';
+import { AUTO_APPROVE_POLICY_NAME, createRunApprovalPolicy } from './approval-policy.js';
 import { CheckpointManager } from './checkpoint.js';
 import { RunContextFactory } from './context.js';
 import { EventTranslator } from './events.js';
@@ -36,6 +45,7 @@ import { isWorkingMemoryMessage } from './iteration/phases/working-memory.js';
 import { applyLifecycleHookResults } from './plugin-hooks.js';
 import { PromptBuilder } from './prompt.js';
 import { PendingAnswers, QuestionParkBinding } from './question-park.js';
+import { RepeatCallTracker } from './repeat-call.js';
 import { ResultAssembler } from './result.js';
 import { applyPendingResume, planCrashResume, planPendingResume, recoverCompletedCalls, unansweredToolCalls, } from './resume-pending.js';
 import { ToolGrantSet } from './tool-grants.js';
@@ -117,14 +127,93 @@ function assertBudgetIsMeasurable(params) {
         details: { model, providerId: params.provider.id, costLimitUsd: limit },
     });
 }
+/**
+ * Ask the driver what this model's window is, and never let the answer
+ * cost the run.
+ *
+ * Three outcomes collapse to two here on purpose. No member and a resolved
+ * `undefined` both mean "no answer" — the distinction matters to a driver
+ * author, not to a caller about to fall through to the table. A rejection
+ * is the third, and it is logged rather than propagated: a run that would
+ * have worked on the table must not fail because a listing endpoint was
+ * down.
+ */
+async function resolveProviderContextWindow(provider, model, signal, log) {
+    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) {
+    // 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
     // wrapped provider, so the retry policy cannot be bypassed by a code
@@ -149,9 +238,7 @@ export async function* query(params) {
     ];
     assertCostIsAttributable(chain, params.pricing);
     assertBudgetIsMeasurable(params);
-    const withRetry = (provider) => params.retry === false
-        ? provider
-        : withProviderRetry(provider, { config: params.retry, log: getRootLogger() });
+    const withRetry = (provider) => 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
@@ -163,7 +250,7 @@ export async function* query(params) {
         current: { index: 0, providerId: params.provider.id },
     };
     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
@@ -172,7 +259,62 @@ export async function* query(params) {
             ctx.runMgr.setServingProvider(to.providerId);
         },
     });
+    // Asked ONCE, here, before the loop exists. Both readers are synchronous
+    // and hot, so this can never move inside the iteration — and a driver
+    // that rejects, or one that hangs until the run is cancelled, must not
+    // take down a run the table could have served perfectly well. That is
+    // why the failure path is a swallow with a log rather than a throw: the
+    // window is an optimisation over a working default, not a prerequisite.
+    const providerContextWindow = await resolveProviderContextWindow(resilientProvider, 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) => {
+            log.debug('Could not read the topic state; using the run config', {
+                'namzu.topic.id': params.topicId,
+                'namzu.error.message': toErrorMessage(err),
+            });
+            return null;
+        })
+        : null;
+    // Whatever a host left for "the next run", taken and cleared in one
+    // compare-and-set write. Prepended to the messages this run starts from,
+    // so it is in the FIRST request rather than arriving a turn late.
+    //
+    // Cleared as it is read: a queue read and cleared separately re-delivers
+    // on a crash between the two, and "start with this" arriving twice is a
+    // different instruction from the one that was left.
+    const queuedForThisRun = params.topicStateStore
+        ? await drainQueuedMessages(params.topicStateStore, params.topicId, params.tenantId).catch((err) => {
+            log.debug('Could not drain the topic queue; starting without it', {
+                'namzu.topic.id': params.topicId,
+                'namzu.error.message': toErrorMessage(err),
+            });
+            return [];
+        })
+        : [];
+    // One effective list, used everywhere the run is seeded from. Three
+    // branches below push from it, and computing it at each would be three
+    // places to forget the queue.
+    //
+    // Stored attachments are resolved HERE, once, before the messages reach
+    // the run record. Resolving later — at the provider boundary — would put
+    // refs in the durable transcript and in every checkpoint, and a run
+    // resumed against a store that had since forgotten a ref would fail
+    // replaying its own history rather than at the moment somebody asked for
+    // the bytes. Every failure refuses: a message that silently lost its
+    // image is a model answering about a picture it never saw.
+    const seeded = queuedForThisRun.length > 0 ? [...queuedForThisRun, ...params.messages] : params.messages;
+    const initialMessages = [...(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,
@@ -180,21 +322,49 @@ export async function* query(params) {
         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}`,
@@ -228,7 +398,7 @@ export async function* query(params) {
         }
         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
@@ -287,9 +457,10 @@ export async function* query(params) {
                 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,
         });
     }
     if (attachmentMessageCount > 0) {
@@ -301,9 +472,10 @@ export async function* query(params) {
                 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,
         });
     }
     if (documentMessageCount > 0) {
@@ -315,14 +487,30 @@ export async function* query(params) {
                 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 = 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.
     //
@@ -349,12 +537,18 @@ export async function* query(params) {
         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 }
@@ -381,7 +575,7 @@ export async function* query(params) {
         toolPause: (toolUseId) => createToolPause({
             runId: ctx.runId,
             toolUseId,
-            parkHandler: params.resumeHandler,
+            parkHandler: (request) => approvalPolicy.current.handler(request),
             recorder: questionParks,
             pendingAnswers,
         }),
@@ -399,6 +593,7 @@ export async function* query(params) {
         tools: params.tools,
         allowedTools: effectiveAllowedTools,
         runtimeContext: params.runtimeContext,
+        ...(params.promptContributions ? { contributions: params.promptContributions } : {}),
     });
     const guard = new GuardCoordinator({
         tokenBudget: params.runConfig.tokenBudget,
@@ -426,6 +621,10 @@ export async function* query(params) {
         // Read at settle time, not now: checkpoints are written per
         // iteration, so the answer changes as the run proceeds.
         resumeCheckpointId: () => checkpointMgr.lastCheckpointId,
+        // Read only to recover WHY a cancellation happened. The run loop
+        // already knows THAT it was cancelled; the origin lives on the abort
+        // reason and nothing else carries it this far.
+        signal: ctx.abortController.signal,
     });
     let advisoryCtx;
     if (params.advisory && params.advisory.advisors.length > 0) {
@@ -470,8 +669,15 @@ export async function* query(params) {
             }
         }
     }
-    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({
         provider: resilientProvider,
@@ -479,6 +685,7 @@ export async function* query(params) {
         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 } : {}),
@@ -496,17 +703,27 @@ export async function* query(params) {
         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,
@@ -585,9 +802,9 @@ export async function* query(params) {
                     // 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;
                 }
@@ -595,9 +812,9 @@ export async function* query(params) {
             resolve: async (checkpointId, decision) => {
                 await checkpointMgr.unpark(checkpointId, decision).catch((err) => {
                     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;
                 });
@@ -651,13 +868,13 @@ export async function* query(params) {
             // callback actually makes.
             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';
             const cacheInput = {
@@ -668,13 +885,14 @@ export async function* query(params) {
                 tools: params.tools,
                 allowedTools: effectiveAllowedTools,
                 runtimeContext: params.runtimeContext,
+                ...(params.promptContributions ? { contributions: params.promptContributions } : {}),
             };
-            const segments = params.contextCache
-                ? params.contextCache.getSystemPromptSegmented(cacheInput, contextLevel, params.workingDirectory)
+            const segments = 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 = () => {
                 ctx.runMgr.pushMessage(createSystemMessage(segments.static, 'cache'));
@@ -709,18 +927,18 @@ export async function* query(params) {
                     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();
                 // A human answered the park in a different process; apply that
@@ -768,11 +986,11 @@ export async function* query(params) {
                     : 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,
                     });
                 }
                 for (const msg of restoredMessages) {
@@ -790,16 +1008,26 @@ export async function* query(params) {
                     }
                     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);
@@ -819,6 +1047,22 @@ export async function* query(params) {
                 systemPrompt: assembledPrompt,
             });
             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).
@@ -849,7 +1093,26 @@ export async function* query(params) {
             }
             // --- 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,
@@ -863,9 +1126,9 @@ export async function* query(params) {
                 });
                 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,
                 });
             }
             // Crash-save handlers live for exactly the run's lifetime, and are
@@ -877,7 +1140,7 @@ export async function* query(params) {
                     emergencyManager.attach(ctx.runMgr, runDir, ctx.log);
                 }
                 else {
-                    ctx.log.warn('emergencySave requested but the run has no output directory — crash dumps disabled', { runId: ctx.runId });
+                    ctx.log.warn('emergencySave requested but the run has no output directory — crash dumps disabled', { [NAMZU.RUN_ID]: ctx.runId });
                 }
             }
             // Before the first model call: the cheapest place to refuse, since
@@ -899,6 +1162,15 @@ export async function* query(params) {
                     ...(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);
@@ -909,9 +1181,9 @@ export async function* query(params) {
             // 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,
@@ -935,9 +1207,9 @@ export async function* query(params) {
                         .unpark(resolvedCheckpointId, params.pendingDecision)
                         .catch((err) => {
                         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;
                     });
@@ -975,6 +1247,13 @@ export async function* query(params) {
                         ...(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('');
@@ -1005,6 +1284,30 @@ export async function* query(params) {
             // WeakRef'd, settled run as the crash target for the rest of the
             // process's life.
             emergencyManager?.detach();
+            // A background job outlives the tool call that started it — that
+            // is what it is for — so nothing but this stops it outliving the
+            // RUN. Scoped to this run's id: a shared registry serving several
+            // runs must not have one of them tear down another's work.
+            //
+            // Awaited, and its failure swallowed. A job that would not die is
+            // worth a log line, and is not worth retracting a run's answer.
+            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.
@@ -1022,8 +1325,8 @@ export async function* query(params) {
                 }
                 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),
                     });
                 }
             }
@@ -1037,12 +1340,12 @@ export async function* query(params) {
                         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),
                     });
                 }
             }