@namzu/sdk 27.1.0 → 29.0.0

package/src/invariants/index.ts

@@ -0,0 +1,201 @@
+// Module self-checks: what a module says about its OWN live state, asked
+// at the moment somebody wants to know.
+//
+// This lived in `src/verification/` beside the tool-authorization gate, and
+// moved out when that directory became `src/authorization/` — because it is
+// the one thing in there that genuinely verifies a claim. Merging it into
+// `authorization/` would have put a registry of module invariants inside a
+// module named for deciding whether a tool call is permitted, which is a
+// worse home than the one it started in.
+
+import { ManagedRegistry } from '../registry/ManagedRegistry.js'
+
+/**
+ * What a module's check said about its own claim, the moment it was asked.
+ *
+ * Three states, not two, for the same reason {@link InvariantOutcome} shares
+ * its shape with NZ-BOOT-02's `CapabilityProbe`: a check that could not run
+ * — no live run to point it at, a dependency not wired yet — is not the same
+ * fact as a check that ran and found nothing wrong, and collapsing the two
+ * turns "I do not know" into the strongest possible wrong answer. See
+ * `docs/conventions/an-optional-dependency-may-not-degrade-a-check.md`.
+ */
+export type InvariantOutcome =
+	| { readonly state: 'holds' }
+	| { readonly state: 'violated'; readonly detail: string }
+	| { readonly state: 'unknown'; readonly reason: string }
+
+/**
+ * A module's claim about its own live state, as a function of whatever
+ * context evaluating it needs.
+ *
+ * Stored on the registry as `InvariantCheck<never>` — see the note on
+ * {@link InvariantDefinition.check} for why the erasure is deliberate rather
+ * than a shortcut.
+ */
+export type InvariantCheck<TContext = unknown> = (
+	ctx: TContext,
+) => InvariantOutcome | Promise<InvariantOutcome>
+
+/**
+ * Thrown by {@link InvariantRegistry.register} when `<moduleName>:<name>` is
+ * already taken.
+ *
+ * `ManagedRegistry.register` — what this class is built on — warns and
+ * OVERWRITES a duplicate id by default; that is right for a registry of
+ * definitions a later one is meant to supersede, and wrong here. Two
+ * invariants sharing a name is always a bug (two modules picked the same
+ * words, or one module's own top-level registration ran twice), and
+ * overwriting would silently keep whichever registration lost the race while
+ * every reference to the other's `id` kept resolving as if it still existed.
+ * Mirrors `ProbeNameCollisionError`.
+ */
+export class InvariantNameCollisionError extends Error {
+	readonly moduleName: string
+	readonly invariantName: string
+
+	constructor(moduleName: string, invariantName: string) {
+		super(
+			`Invariant "${moduleName}:${invariantName}" is already registered. Two modules picked the same name, or this module registered itself twice — pick a different name, or find the second registration.`,
+		)
+		this.name = 'InvariantNameCollisionError'
+		this.moduleName = moduleName
+		this.invariantName = invariantName
+	}
+}
+
+/**
+ * Thrown by {@link InvariantRegistry.assert} when the named invariant's
+ * check reports `violated`. Never thrown for `unknown` — a check that could
+ * not answer is not a check that answered no, and `assert` treating the two
+ * alike would turn "ask again with more context" into a hard failure the
+ * check never claimed to be.
+ */
+export class ModuleInvariantError extends Error {
+	readonly moduleName: string
+	readonly invariantName: string
+	readonly detail: string
+
+	constructor(moduleName: string, invariantName: string, detail: string) {
+		super(`${moduleName}: invariant "${invariantName}" violated — ${detail}`)
+		this.name = 'ModuleInvariantError'
+		this.moduleName = moduleName
+		this.invariantName = invariantName
+		this.detail = detail
+	}
+}
+
+interface InvariantDefinition {
+	readonly id: string
+	readonly moduleName: string
+	readonly name: string
+	/**
+	 * Erased to `never` at storage. Two invariants close over unrelated
+	 * context shapes — a candidate message list here, a run directory and a
+	 * presented fence there — and one map cannot state both statically. The
+	 * pairing of a check with the shape of `ctx` it expects is a contract the
+	 * CALLER of `evaluate`/`assert` keeps by knowing which id it is asking,
+	 * the same way `ProbeRegistry` keeps event-kind/handler pairing outside
+	 * the type system once an entry is stored by name. `never` rather than
+	 * `unknown` in this field's own type because a function expecting
+	 * `unknown` cannot accept one written for a narrower context —
+	 * TypeScript checks parameters contravariantly — while `never` is a
+	 * subtype of every context a real check is written for, so `register`'s
+	 * generic check parameter is always assignable here.
+	 */
+	readonly check: InvariantCheck<never>
+	violations: number
+}
+
+/**
+ * The place a package registers a claim about its own live state, and the
+ * place an operator or `namzu doctor` reads what this build asserts about
+ * itself.
+ *
+ * Built on {@link ManagedRegistry} for storage and its logging, composed
+ * rather than extended: `ManagedRegistry.register(id, item)` is public,
+ * two-argument, and overwrites — exposing it directly (by extending the
+ * class under the name `register`) would either fail to compile against
+ * this class's three-argument `register(moduleName, name, check)`, or, named
+ * differently, leave the inherited two-argument overwrite-on-collision
+ * method reachable as an unguarded back door around the one guarantee this
+ * class exists to make.
+ */
+export class InvariantRegistry {
+	private readonly definitions: ManagedRegistry<InvariantDefinition>
+
+	constructor() {
+		this.definitions = new ManagedRegistry<InvariantDefinition>({
+			componentName: 'InvariantRegistry',
+		})
+	}
+
+	/**
+	 * Reserve `<moduleName>:<name>` for `check`, once. Throws
+	 * {@link InvariantNameCollisionError} on a second registration under the
+	 * same id — see the class doc for why this does not delegate to the base
+	 * registry's own collision handling.
+	 */
+	register<TContext>(moduleName: string, name: string, check: InvariantCheck<TContext>): void {
+		const id = `${moduleName}:${name}`
+		if (this.definitions.has(id)) {
+			throw new InvariantNameCollisionError(moduleName, name)
+		}
+		this.definitions.register(id, {
+			id,
+			moduleName,
+			name,
+			check: check as InvariantCheck<never>,
+			violations: 0,
+		})
+	}
+
+	/** Every registered id, in registration order. */
+	listIds(): string[] {
+		return this.definitions.listIds()
+	}
+
+	/**
+	 * Run `id`'s check against `ctx` and return what it said. A `violated`
+	 * result counts against that invariant's own violation counter; `holds`
+	 * and `unknown` do not, so the counter answers "how many times has this
+	 * actually been false" and nothing else.
+	 */
+	async evaluate<TContext = never>(id: string, ctx: TContext): Promise<InvariantOutcome> {
+		const definition = this.definitions.getOrThrow(id)
+		const outcome = await definition.check(ctx as never)
+		if (outcome.state === 'violated') definition.violations += 1
+		return outcome
+	}
+
+	/**
+	 * `evaluate`, but a `violated` outcome throws {@link ModuleInvariantError}
+	 * instead of being handed back. `unknown` does not throw — see the error
+	 * class's own doc.
+	 */
+	async assert<TContext = never>(id: string, ctx: TContext): Promise<void> {
+		const outcome = await this.evaluate(id, ctx)
+		if (outcome.state === 'violated') {
+			const definition = this.definitions.getOrThrow(id)
+			throw new ModuleInvariantError(definition.moduleName, definition.name, outcome.detail)
+		}
+	}
+
+	/** Violations `id` has recorded since this registry was created. */
+	violationCount(id: string): number {
+		return this.definitions.getOrThrow(id).violations
+	}
+}
+
+/**
+ * The process-wide registry. `compaction.ts` and `claim-disk.ts` each
+ * register one invariant against it at import time — see the registration
+ * beside each — which is what makes `listIds()` non-empty from the day this
+ * file lands rather than a registry nothing has ever driven.
+ */
+export const invariants: InvariantRegistry = new InvariantRegistry()
+
+/** A scoped registry for a test, or a host that wants its own. */
+export function createInvariantRegistry(): InvariantRegistry {
+	return new InvariantRegistry()
+}

package/src/manager/agent/lifecycle.ts

@@ -1,5 +1,6 @@
 import { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js'
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
+import { GENAI } from '../../constants/telemetry/index.js'
 import type { AgentRegistry } from '../../registry/agent/definitions.js'
 import {
 	type CapacityValidator,
@@ -21,8 +22,9 @@ import type {
 } from '../../types/agent/task.js'
 import { isTerminalAgentTaskState } from '../../types/agent/task.js'
 import { NamzuError } from '../../types/errors/index.js'
-import type { AgentId, RunId, SessionId, TaskId, TenantId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TaskId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
+import { type CancelCause, RunCancelled } from '../../types/run/cancel-cause.js'
 import type { RunEvent, RunEventListener } from '../../types/run/events.js'
 import type { Lineage } from '../../types/run/lineage.js'
 import { RUN_EVENT_SCHEMA_VERSION } from '../../types/run/schema-version.js'
@@ -35,9 +37,10 @@ import { createChildAbortController } from '../../utils/abort.js'
 import { ZERO_COST } from '../../utils/cost.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { generateTaskId } from '../../utils/id.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { requireOpenProject } from '../project/lifecycle.js'
-import type { ThreadManager } from '../thread/lifecycle.js'
+import type { TopicManager } from '../topic/lifecycle.js'
 
 /**
  * Dependencies threaded into {@link AgentManager}. Phase 6 promoted the
@@ -64,13 +67,26 @@ export interface AgentManagerDeps {
 	readonly summaryMaterializer: SessionSummaryMaterializer
 	readonly capacity: CapacityValidator
 	/**
-	 * Gate session creation on the parent Thread being `'open'` via
-	 * {@link ThreadManager.requireOpen}. Added in Phase 2.6 to close the
+	 * Gate session creation on the parent Topic being `'open'` via
+	 * {@link TopicManager.requireOpen}. Added in Phase 2.6 to close the
 	 * archive-gate gap flagged by the Phase 2.5 commit: without this,
-	 * `ThreadManager.archive` was best-effort because spawn could still
+	 * `TopicManager.archive` was best-effort because spawn could still
 	 * attach a live session under an archived Thread.
 	 */
-	readonly threadManager: ThreadManager
+	readonly threadManager: TopicManager
+
+	/**
+	 * A pre-built logger. No in-package caller threads a real one today —
+	 * `packages/cli/src/integrations/subagents/runtime.ts` is the only
+	 * production `new AgentManager(...)` call, and CLI wiring is out of this
+	 * task's scope (`packages/cli` is not counted by `getRootLoggerCount`,
+	 * which is SDK-only) — but the field is genuinely host-reachable: it is
+	 * a plain object-literal parameter (no exported type import required to
+	 * satisfy it structurally) on `AgentManager`, which IS exported from
+	 * `public-runtime.ts`. Same standing as `RunConfig.logger` when it was
+	 * first added.
+	 */
+	readonly log?: Logger
 }
 
 interface ChildSpawnRecord {
@@ -81,6 +97,14 @@ interface ChildSpawnRecord {
 	rootSessionId: SessionId
 	childDepth: number
 	workspaceRef?: WorkspaceRef
+	/**
+	 * What this child was actually granted, after the ancestor union.
+	 *
+	 * Recorded rather than left implicit so a test — and an operator reading
+	 * a spawn record — can ask what a child was allowed, instead of
+	 * inferring it from whether a call happened to be refused.
+	 */
+	resolvedToolDenies?: readonly string[]
 }
 
 /**
@@ -122,7 +146,7 @@ export class AgentManager {
 	) {
 		this.registry = registry
 		this.config = { ...AGENT_MANAGER_DEFAULTS, ...config }
-		this.log = getRootLogger().child({ component: 'AgentManager' })
+		this.log = resolveLogger(deps.log).child({ [SCOPE_ATTRIBUTE]: 'manager/agent/lifecycle' })
 		this.deps = deps
 	}
 
@@ -195,11 +219,34 @@ export class AgentManager {
 
 		const childParentActor: ActorRef = {
 			kind: 'agent',
-			agentId: context.parentAgentId as AgentId,
+			agentId: context.parentAgentId,
 			tenantId: context.tenantId,
 			parentActor: context.parentActor,
 		}
 
+		// The union of every deny along the chain, plus this spawn's own.
+		//
+		// Without it, NZ-GATE-09's scope stopped at one level: a child denied
+		// `bash` could spawn a grandchild naming no scope, and the grandchild
+		// got bash back. A restriction that a descendant can shed by
+		// delegating is not a restriction.
+		//
+		// No containment CHECK here, deliberately. The obvious shape is to
+		// confirm with `isDescendantOfActor` that the child really sits under
+		// the actor whose scope is being inherited — but `childParentActor`
+		// is built two statements up FROM `context.parentActor`, so the
+		// answer is yes by construction and the branch could never be taken.
+		// A check that cannot fail reads as a safeguard and is not one. The
+		// predicate is exported for the callers that do face an actor they
+		// did not construct: an audit walking a subtree, a host asking
+		// whether one run's actor is contained by another's.
+		//
+		// Union, not replace, and not "innermost wins": a descendant may
+		// narrow further and may never widen.
+		const inheritedDenies = context.toolDenies ?? []
+		const ownDenies = options.toolScope?.deny ?? []
+		const resolvedDenies = [...new Set([...inheritedDenies, ...ownDenies])]
+
 		const childContext: AgentTaskContext = {
 			parentRunId: context.parentRunId,
 			parentAgentId: context.parentAgentId,
@@ -208,10 +255,11 @@ export class AgentManager {
 			budgetTracker: context.budgetTracker,
 			factoryOptions: context.factoryOptions,
 			tenantId: context.tenantId,
-			threadId: context.threadId,
+			topicId: context.topicId,
 			sessionId: spawnRecord.childSessionId,
 			projectId: context.projectId,
 			parentActor: childParentActor,
+			...(resolvedDenies.length > 0 ? { toolDenies: resolvedDenies } : {}),
 		}
 
 		const agentTask: AgentTask = {
@@ -228,6 +276,7 @@ export class AgentManager {
 		}
 
 		this.instances.set(taskId, agentTask)
+		if (resolvedDenies.length > 0) spawnRecord.resolvedToolDenies = resolvedDenies
 		this.spawnRecords.set(taskId, spawnRecord)
 		this.emit({
 			type: 'pending',
@@ -263,7 +312,11 @@ export class AgentManager {
 				at: new Date(),
 			})
 		}
-		this.log.info(`Agent task pending: ${taskId} (${options.agentId}, depth=${context.depth})`)
+		this.log.info('Agent task pending', {
+			'namzu.agent.task_id': taskId,
+			'namzu.agent.definition_id': options.agentId,
+			'namzu.agent.depth': context.depth,
+		})
 
 		const definition = this.registry.getOrThrow(options.agentId)
 		let childConfig: BaseAgentConfig
@@ -290,7 +343,7 @@ export class AgentManager {
 			// configBuilder may not have been updated to emit these yet; we
 			// stamp them here so query() sees them regardless.
 			childConfig.sessionId = spawnRecord?.childSessionId ?? context.sessionId
-			childConfig.threadId = context.threadId
+			childConfig.topicId = context.topicId
 			childConfig.projectId = context.projectId
 			childConfig.tenantId = context.tenantId
 			// Stamp the trace parent the same way, rather than trusting every
@@ -328,7 +381,7 @@ export class AgentManager {
 			if (inheritedEnv) childConfig.env = inheritedEnv
 		} else {
 			this.log.warn('No configBuilder, using bare config', {
-				agentId: options.agentId,
+				[GENAI.AGENT_ID]: options.agentId,
 			})
 			childConfig = {
 				model: options.configOverrides?.model ?? 'default',
@@ -346,7 +399,7 @@ export class AgentManager {
 				effort: options.configOverrides?.effort,
 				env: options.configOverrides?.env,
 				sessionId: spawnRecord.childSessionId,
-				threadId: context.threadId,
+				topicId: context.topicId,
 				projectId: context.projectId,
 				tenantId: context.tenantId,
 				parentRunId: context.parentRunId,
@@ -355,6 +408,47 @@ export class AgentManager {
 			}
 		}
 
+		// Stamped AFTER the builder, for the fourth time and the same reason:
+		// a `configBuilder` is written by whoever registered the agent and
+		// cannot forward a field it was never told about. A scope applied
+		// before it would be silently discarded by every builder that returns
+		// a fixed config — which is most of them.
+		//
+		// OUTSIDE the branch, unlike the four stamps above, and that is the
+		// point. Written inside the `configBuilder` arm it read correctly and
+		// left the bare-config arm below ignoring `toolScope` entirely — a
+		// caller that asked for a narrower child got a wider one, silently,
+		// and in the only direction that matters. Every other field here is
+		// an inheritance, where missing it costs the child something; this
+		// one is a restriction, where missing it costs the CALLER something.
+		//
+		// Narrowing only: the deny list is SUBTRACTED from whatever the child
+		// would otherwise have. `allowedTools` absent means "every registered
+		// tool", so a deny with no existing allow-list has to be resolved
+		// against the registry at the run rather than here — which `query()`
+		// does, and which is why this appends to `deniedTools` rather than
+		// synthesising an allow-list.
+		if (resolvedDenies.length > 0) {
+			childConfig.deniedTools = [
+				...new Set([...(childConfig.deniedTools ?? []), ...resolvedDenies]),
+			]
+		}
+		if (options.personaOverride) childConfig.persona = options.personaOverride
+
+		// Outside the branch, like the scope above it and for the same reason:
+		// a `configBuilder` cannot forward a field it was never told about.
+		//
+		// Bound to the taskId rather than to the task object, so a drain after
+		// the task is gone throws where the caller is instead of returning an
+		// empty array from a closure over a corpse.
+		//
+		// This is the delivery point `pendingMessages` never had.
+		// `continueTask` and `queueMessage` pushed onto it and nothing in the
+		// kernel drained it — the manager interface's own docblock said "the
+		// runtime does not deliver it", and `continue_task` was unmounted from
+		// the coordinator tools because of that.
+		childConfig.inboundMessages = () => this.drainMessages(taskId)
+
 		this.runChild(agentTask, options, childConfig, listener).catch((err) => {
 			this.markFailed(taskId, toErrorMessage(err))
 		})
@@ -362,17 +456,23 @@ export class AgentManager {
 		return agentTask
 	}
 
-	cancel(taskId: TaskId): void {
+	cancel(taskId: TaskId, cause?: CancelCause): void {
 		const agentTask = this.instances.get(taskId)
 		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return
 
-		agentTask.childAbortController.abort('canceled')
-		this.markCanceled(taskId)
+		// Was the bare string `'canceled'`, which `abortReasonText` suppresses
+		// by name — its docblock cites this exact call site — so the child's
+		// run saw a cancellation with no attributable origin at all.
+		agentTask.childAbortController.abort(cause ? new RunCancelled(cause) : undefined)
+		this.markCanceled(taskId, cause)
 	}
 
-	cancelAll(parentRunId: RunId): void {
+	cancelAll(parentRunId: RunId, cause: CancelCause = 'parent'): void {
+		// `'parent'` by default, because this call site IS a parent
+		// abandoning its children. `AbstractAgent.cancel` takes no default
+		// for the opposite reason: its caller could be anyone.
 		for (const agentTask of this.listByParent(parentRunId)) {
-			this.cancel(agentTask.taskId)
+			this.cancel(agentTask.taskId, cause)
 		}
 	}
 
@@ -385,11 +485,21 @@ export class AgentManager {
 			role: 'user' as const,
 			content: message,
 		} as Message)
-		this.log.info(`Message queued for task ${taskId} via continueTask`)
+		this.log.info('Message queued for task via continueTask', {
+			'namzu.agent.task_id': taskId,
+		})
 	}
 
 	queueMessage(taskId: TaskId, message: Message): void {
 		const agentTask = this.requireInstance(taskId)
+		// Refused on a settled task, like `continueTask` above. A silent push
+		// leaves the caller believing something is in flight when the only
+		// thing that would ever have drained it has finished.
+		if (isTerminalAgentTaskState(agentTask.state)) {
+			throw new Error(
+				`Cannot queue a message for terminal task: ${taskId} (state: ${agentTask.state})`,
+			)
+		}
 		agentTask.pendingMessages.push(message)
 	}
 
@@ -561,21 +671,21 @@ export class AgentManager {
 		// Thread archive gate — runs FIRST so an archived thread fails fastest
 		// with the correct error (not DelegationCapacityExceeded or a project
 		// lookup error). Phase 2.6 closes the gap the Phase 2.5 commit
-		// flagged: without it, `ThreadManager.archive` could be undermined by
+		// flagged: without it, `TopicManager.archive` could be undermined by
 		// a concurrent spawn landing a live session post-archival.
 		// Scope: this gate enforces the archive invariant at the production
 		// ingress path (AgentManager.sendMessage + handoff flows). Direct
 		// callers of `SessionStore.createSession` bypass it — the store layer
-		// is intentionally unaware of thread status to preserve its
+		// is intentionally unaware of topic status to preserve its
 		// single-responsibility boundary.
-		await this.deps.threadManager.requireOpen(context.threadId, context.tenantId)
+		await this.deps.threadManager.requireOpen(context.topicId, context.tenantId)
 
 		// Parent session cross-check: validate that `options.parentSessionId`
-		// exists for this tenant AND lives under the same thread as the
-		// context. A mismatched `context.threadId` would otherwise attach the
-		// child's sub-session edge to a parent in a different thread —
-		// corrupting the hierarchy invariant (cross-thread spawn is forbidden
-		// by design). Mirrors the `source.threadId === assignment.threadId`
+		// exists for this tenant AND lives under the same topic as the
+		// context. A mismatched `context.topicId` would otherwise attach the
+		// child's sub-session edge to a parent in a different topic —
+		// corrupting the hierarchy invariant (cross-topic spawn is forbidden
+		// by design). Mirrors the `source.topicId === assignment.topicId`
 		// check in handoff (Phase 2.4).
 		const parentSession = await store.getSession(options.parentSessionId, context.tenantId)
 		if (!parentSession) {
@@ -583,9 +693,9 @@ export class AgentManager {
 				`Parent session ${options.parentSessionId} not found for tenant ${context.tenantId} — spawn rejected`,
 			)
 		}
-		if (parentSession.threadId !== context.threadId) {
+		if (parentSession.topicId !== context.topicId) {
 			throw new Error(
-				`Thread mismatch on spawn: parent session ${parentSession.id} is on thread ${parentSession.threadId}, but context.threadId=${context.threadId}. Cross-thread spawn is forbidden (session-hierarchy.md §6.3).`,
+				`Topic mismatch on spawn: parent session ${parentSession.id} is on topic ${parentSession.topicId}, but context.topicId=${context.topicId}. Cross-topic spawn is forbidden (session-hierarchy.md §6.3).`,
 			)
 		}
 		if (parentSession.projectId !== context.projectId) {
@@ -622,18 +732,18 @@ export class AgentManager {
 
 		const childActor: ActorRef = {
 			kind: 'agent',
-			agentId: options.agentId as AgentId,
+			agentId: options.agentId,
 			tenantId: context.tenantId,
 			parentActor: context.parentActor,
 		}
 
-		// Child session inherits the parent's threadId verbatim (cross-thread
+		// Child session inherits the parent's topicId verbatim (cross-topic
 		// spawn is forbidden by design — a delegated sub-agent stays on the
 		// same topic). Phase 2.6 elides the previous parent-session read by
-		// carrying `threadId` on `AgentTaskContext`.
+		// carrying `topicId` on `AgentTaskContext`.
 		const childSession = await store.createSession(
 			{
-				threadId: context.threadId,
+				topicId: context.topicId,
 				projectId: context.projectId,
 				currentActor: childActor,
 			},
@@ -849,8 +959,8 @@ export class AgentManager {
 				await this.disposeChildWorkspace(spawnRecord)
 			} catch (err) {
 				this.log.error('Sub-session finalization failed', {
-					taskId: agentTask.taskId,
-					error: toErrorMessage(err),
+					'namzu.task.id': agentTask.taskId,
+					'exception.message': toErrorMessage(err),
 				})
 			}
 		}
@@ -876,8 +986,8 @@ export class AgentManager {
 				})
 			} catch (err) {
 				this.log.error('subsession_idled emission error', {
-					taskId: agentTask.taskId,
-					error: toErrorMessage(err),
+					'namzu.task.id': agentTask.taskId,
+					'exception.message': toErrorMessage(err),
 				})
 			}
 		}
@@ -911,10 +1021,10 @@ export class AgentManager {
 		if (unused === 0) return
 		agentTask.context.budgetTracker.remaining += unused
 		this.log.debug('Returned unspent child budget', {
-			taskId: agentTask.taskId,
-			reserved,
-			spent,
-			returned: unused,
+			'namzu.task.id': agentTask.taskId,
+			'namzu.manager.reserved': reserved,
+			'namzu.manager.spent': spent,
+			'namzu.manager.returned': unused,
 		})
 	}
 
@@ -933,7 +1043,7 @@ export class AgentManager {
 			taskId,
 			result,
 		})
-		this.log.info(`Agent task completed: ${taskId}`)
+		this.log.info('Agent task completed', { 'namzu.agent.task_id': taskId })
 		this.scheduleEviction(taskId)
 		this.resolveCompletionCallbacks(taskId)
 	}
@@ -966,7 +1076,10 @@ export class AgentManager {
 			taskId,
 			error,
 		})
-		this.log.error(`Agent task failed: ${taskId}`, { error })
+		this.log.error('Agent task failed', {
+			'namzu.agent.task_id': taskId,
+			'exception.message': error,
+		})
 
 		// Best-effort: mark sub-session failed + dispose workspace. The result
 		// emission path already synthesized a failure result above.
@@ -974,8 +1087,8 @@ export class AgentManager {
 		if (spawnRecord) {
 			this.failSubSession(spawnRecord).catch((err) => {
 				this.log.warn('SubSession failure update failed', {
-					taskId,
-					error: toErrorMessage(err),
+					'namzu.task.id': taskId,
+					'exception.message': toErrorMessage(err),
 				})
 			})
 		}
@@ -1021,15 +1134,15 @@ export class AgentManager {
 			.dispose(spawnRecord.workspaceRef)
 			.catch((disposeErr) => {
 				this.log.warn('Workspace dispose failed', {
-					backend,
-					workspaceId: spawnRecord.workspaceRef?.id,
-					subSessionId: spawnRecord.subSessionId,
-					error: toErrorMessage(disposeErr),
+					'namzu.manager.backend': backend,
+					'namzu.manager.workspace_id': spawnRecord.workspaceRef?.id,
+					'namzu.sub_session.id': spawnRecord.subSessionId,
+					'exception.message': toErrorMessage(disposeErr),
 				})
 			})
 	}
 
-	private markCanceled(taskId: TaskId): void {
+	private markCanceled(taskId: TaskId, cause?: CancelCause): void {
 		const agentTask = this.instances.get(taskId)
 		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return
 
@@ -1040,8 +1153,9 @@ export class AgentManager {
 			type: 'agent_canceled',
 			runId: agentTask.context.parentRunId,
 			taskId,
+			...(cause ? { cancelCause: cause } : {}),
 		})
-		this.log.info(`Agent task canceled: ${taskId}`)
+		this.log.info('Agent task canceled', { 'namzu.agent.task_id': taskId })
 		this.scheduleEviction(taskId)
 		this.resolveCompletionCallbacks(taskId)
 	}
@@ -1071,7 +1185,7 @@ export class AgentManager {
 			this.instances.delete(taskId)
 			this.spawnRecords.delete(taskId)
 			this.evictionTimers.delete(taskId)
-			this.log.info(`Agent task evicted: ${taskId}`)
+			this.log.info('Agent task evicted', { 'namzu.agent.task_id': taskId })
 		}, this.config.evictionMs)
 
 		this.evictionTimers.set(taskId, timer)
@@ -1099,8 +1213,8 @@ export class AgentManager {
 				listener(event)
 			} catch (err) {
 				this.log.error('Agent lifecycle listener error', {
-					eventType: event.type,
-					error: toErrorMessage(err),
+					'namzu.event.type': event.type,
+					'exception.message': toErrorMessage(err),
 				})
 			}
 		}
@@ -1112,9 +1226,9 @@ export class AgentManager {
 			agentTask.runEventListener(event)
 		} catch (err) {
 			this.log.error('RunEvent emission error', {
-				eventType: event.type,
-				taskId: agentTask.taskId,
-				error: toErrorMessage(err),
+				'namzu.event.type': event.type,
+				'namzu.task.id': agentTask.taskId,
+				'exception.message': toErrorMessage(err),
 			})
 		}
 	}