@namzu/sdk 43.0.0 → 44.1.0

package/src/manager/agent/lifecycle.ts

@@ -1,3 +1,4 @@
+import { rm } from 'node:fs/promises'
 import { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js'
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import { GENAI } from '../../constants/telemetry/index.js'
@@ -6,8 +7,14 @@ import {
 	type CapacityValidator,
 	DelegationCapacityExceeded,
 } from '../../session/handoff/capacity.js'
+import type { SessionLocator, SessionPaths } from '../../session/paths.js'
 import type { SessionSummaryMaterializer } from '../../session/summary/materialize.js'
 import type { WorkspaceBackendRegistry } from '../../session/workspace/registry.js'
+import {
+	DiskSessionLog,
+	InMemorySessionLog,
+	type SessionLog,
+} from '../../store/session-log/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from '../../types/agent/base.js'
 import type {
 	AgentLifecycleEvent,
@@ -22,15 +29,16 @@ import type {
 } from '../../types/agent/task.js'
 import { isTerminalAgentTaskState } from '../../types/agent/task.js'
 import { NamzuError } from '../../types/errors/index.js'
-import type { RunId, SessionId, TaskId, TenantId } from '../../types/ids/index.js'
+import type { SessionId, TaskId, TenantId, ToolUseId, TurnId } 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'
 import type { ActorRef } from '../../types/session/actor.js'
+import { type CancelCause, TurnCancelled } from '../../types/session/cancel-cause.js'
+import type { SessionEvent, SessionEventListener } from '../../types/session/events.js'
 import type { SubSessionId } from '../../types/session/ids.js'
+import type { Lineage } from '../../types/session/lineage.js'
+import type { ChildSessionMeta } from '../../types/session/records.js'
 import type { SessionStore } from '../../types/session/store.js'
+import type { TurnExecutionStatus } from '../../types/session/turn.js'
 import type { SessionSummaryOutcome } from '../../types/summary/ref.js'
 import type { WorkspaceRef } from '../../types/workspace/ref.js'
 import { createChildAbortController } from '../../utils/abort.js'
@@ -42,6 +50,7 @@ import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { requireOpenProject } from '../project/lifecycle.js'
 import { type TopicManagerDependency, resolveTopicManager } from '../topic/dependency.js'
 import type { TopicManager } from '../topic/lifecycle.js'
+import { registerChildSessionLog, writeChildSessionMeta } from './child-session.js'
 
 /**
  * Dependencies threaded into {@link AgentManager}. Phase 6 promoted the
@@ -76,10 +85,22 @@ interface AgentManagerBaseDeps {
 	 * 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
+	 * `public-runtime.ts`. Same standing as `TurnConfig.logger` when it was
 	 * first added.
 	 */
 	readonly log?: Logger
+
+	/**
+	 * The project layout child sessions are written into when neither the
+	 * child config (`sessionLog`, `paths`) nor the parent
+	 * (`AgentTaskContext.childStorage`) names one: the child's log at
+	 * `<parent-session-dir>/subagents/<child-id>.jsonl` and its
+	 * `<child-id>.meta.json` beside it, nested under each ancestor. A parent
+	 * on disk hands down its own layout, which wins over this, because a
+	 * child's log nests under its parent's session directory. A parent held
+	 * in memory gives its children in-memory logs whatever this says.
+	 */
+	readonly paths?: SessionPaths
 }
 
 /**
@@ -100,7 +121,7 @@ interface PendingSpawn {
 	readonly task: AgentTask
 	readonly options: SendMessageOptions
 	readonly context: AgentTaskContext
-	readonly listener?: RunEventListener
+	readonly listener?: SessionEventListener
 	readonly removeAbortListener: () => void
 }
 
@@ -109,8 +130,26 @@ interface ChildSpawnRecord {
 	childSessionId: SessionId
 	tenantId: TenantId
 	parentSessionId: SessionId
+	/** The parent turn whose tool call spawned the child. */
+	parentTurnId: TurnId
 	rootSessionId: SessionId
+	/** The parent's ancestors and the parent itself, root first: the child's `SessionLocator.ancestors`. */
+	ancestry: readonly SessionId[]
 	childDepth: number
+	/**
+	 * Where the child's log and meta document were placed, when this manager
+	 * placed them (a layout was known and the child named no storage).
+	 */
+	placement?: {
+		readonly paths: SessionPaths
+		readonly metaPath: string
+		readonly createdAt: string
+		readonly toolCallId: string
+		readonly agentType: string
+		readonly description: string
+	}
+	/** Removes the child's log from the process-local lookup. */
+	releaseLog?: () => void
 	workspaceRef?: WorkspaceRef
 	/**
 	 * What this child was actually granted, after the ancestor union.
@@ -181,7 +220,7 @@ export class AgentManager {
 	async sendMessage(
 		options: SendMessageOptions,
 		context: AgentTaskContext,
-		listener?: RunEventListener,
+		listener?: SessionEventListener,
 	): Promise<AgentTask> {
 		if (this.disposed) throw new Error('Agent manager is disposed')
 		if (this.config.capacityBehavior === 'queue')
@@ -192,7 +231,7 @@ export class AgentManager {
 	private async enqueueMessage(
 		options: SendMessageOptions,
 		context: AgentTaskContext,
-		listener?: RunEventListener,
+		listener?: SessionEventListener,
 	): Promise<AgentTask> {
 		context.parentAbortController.signal.throwIfAborted()
 		if (context.depth >= this.config.maxDepth)
@@ -214,7 +253,7 @@ export class AgentManager {
 			state: 'pending',
 			pendingMessages: [],
 			createdAt: Date.now(),
-			runEventListener: listener,
+			sessionEventListener: listener,
 		}
 		this.instances.set(task.taskId, task)
 		const onAbort = (): void => {
@@ -247,7 +286,8 @@ export class AgentManager {
 		try {
 			await listener?.({
 				type: 'agent_pending',
-				runId: context.parentRunId,
+				sessionId: context.parentSessionId,
+				turnId: context.parentTurnId,
 				taskId: task.taskId,
 				parentAgentId: context.parentAgentId,
 				childAgentId: options.agentId,
@@ -331,8 +371,11 @@ export class AgentManager {
 		if (isTerminalAgentTaskState(task.state)) return
 		task.childAbortController.abort(reason)
 		const error = toErrorMessage(reason)
+		// The child never got a session, so its result names the parent turn
+		// that asked for it.
 		task.result = {
-			runId: entry.context.parentRunId,
+			sessionId: entry.context.parentSessionId,
+			turnId: entry.context.parentTurnId,
 			status: 'failed',
 			usage: { ...EMPTY_TOKEN_USAGE },
 			cost: { ...ZERO_COST },
@@ -344,9 +387,10 @@ export class AgentManager {
 		task.state = 'failed'
 		task.completedAt = Date.now()
 		this.emit({ type: 'failed', taskId: task.taskId, error })
-		this.emitRunEvent(task, {
+		this.emitSessionEvent(task, {
 			type: 'agent_failed',
-			runId: entry.context.parentRunId,
+			sessionId: entry.context.parentSessionId,
+			turnId: entry.context.parentTurnId,
 			taskId: task.taskId,
 			error,
 		})
@@ -357,7 +401,7 @@ export class AgentManager {
 	private async startMessage(
 		options: SendMessageOptions,
 		context: AgentTaskContext,
-		listener?: RunEventListener,
+		listener?: SessionEventListener,
 		queuedTask?: AgentTask,
 	): Promise<AgentTask> {
 		await options.beforeStart?.()
@@ -377,8 +421,8 @@ export class AgentManager {
 		// A shell this task has to itself, not the registry's shared instance.
 		//
 		// `resolve` returns one `typedAgent` per registered id, and an instance
-		// refuses a second concurrent `run` because it holds per-run state. So
-		// a fan-out naming the same `agent_id` four times drove four runs at one
+		// refuses a second concurrent `run` because it holds per-turn state. So
+		// a fan-out naming the same `agent_id` four times drove four turns at one
 		// shell: one worked and three died with `ConcurrentInvocationError` —
 		// while `create_task`'s own description tells the model that this
 		// fan-out is the thing to do. Observed live on 12.0.1, four launches,
@@ -394,7 +438,7 @@ export class AgentManager {
 		// the agent. The shell was the only shared thing left.
 		const definitionForSpawn = this.registry.getOrThrow(options.agentId)
 		const sharedAgent = definitionForSpawn.typedAgent
-		const agent = definitionForSpawn.createAgent?.() ?? sharedAgent.forRun?.() ?? sharedAgent
+		const agent = definitionForSpawn.createAgent?.() ?? sharedAgent.forTurn?.() ?? sharedAgent
 
 		context.parentAbortController.signal.throwIfAborted()
 
@@ -490,7 +534,7 @@ export class AgentManager {
 			// 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.
+			// whether one turn's actor is contained by another's.
 			//
 			// Union, not replace, and not "innermost wins": a descendant may
 			// narrow further and may never widen.
@@ -499,7 +543,8 @@ export class AgentManager {
 			const resolvedDenies = [...new Set([...inheritedDenies, ...ownDenies])]
 
 			const childContext: AgentTaskContext = {
-				parentRunId: context.parentRunId,
+				parentSessionId: context.parentSessionId,
+				parentTurnId: context.parentTurnId,
 				parentAgentId: context.parentAgentId,
 				parentAbortController: context.parentAbortController,
 				depth: context.depth + 1,
@@ -511,6 +556,7 @@ export class AgentManager {
 				projectId: context.projectId,
 				parentActor: childParentActor,
 				...(resolvedDenies.length > 0 ? { toolDenies: resolvedDenies } : {}),
+				...(context.childStorage ? { childStorage: context.childStorage } : {}),
 			}
 
 			agentTask = Object.assign(queuedTask ?? {}, {
@@ -522,7 +568,7 @@ export class AgentManager {
 				state: 'pending',
 				pendingMessages: queuedTask?.pendingMessages ?? [],
 				createdAt: queuedTask?.createdAt ?? Date.now(),
-				runEventListener: listener,
+				sessionEventListener: listener,
 			} satisfies AgentTask)
 
 			childAbortController.signal.throwIfAborted()
@@ -542,7 +588,8 @@ export class AgentManager {
 				if (!queuedTask)
 					await listener({
 						type: 'agent_pending',
-						runId: context.parentRunId,
+						sessionId: context.parentSessionId,
+						turnId: context.parentTurnId,
 						taskId,
 						parentAgentId: context.parentAgentId,
 						childAgentId: options.agentId,
@@ -558,14 +605,25 @@ export class AgentManager {
 					depth: spawnRecord.childDepth,
 				}
 				await listener({
-					type: 'subsession_spawned',
-					runId: context.parentRunId,
-					subSessionId: spawnRecord.subSessionId,
-					parentSessionId: spawnRecord.parentSessionId,
-					spawnedBy: context.parentActor,
+					type: 'child_session_spawned',
+					sessionId: spawnRecord.parentSessionId,
+					turnId: spawnRecord.parentTurnId,
+					childSessionId: spawnRecord.childSessionId,
+					toolCallId: spawnToolCallId(taskId),
+					kind: 'agent_spawn',
+					description: describeSpawn(options),
+					path: childLogPath(spawnRecord.childSessionId),
+					...(options.workflow
+						? {
+								batch: {
+									batchId: options.workflow,
+									name: options.workflow,
+									...(options.phase ? { phase: options.phase } : {}),
+								},
+							}
+						: {}),
+					budgetAccountId: childBudget.accountId,
 					lineage,
-					schemaVersion: RUN_EVENT_SCHEMA_VERSION,
-					at: new Date(),
 				})
 			}
 			this.log.info('Agent task pending', {
@@ -587,7 +645,9 @@ export class AgentManager {
 						...(context.factoryOptions ?? {}),
 						tokenBudget: allocatedTokens,
 						timeoutMs: options.budgetAllocation?.timeoutMs ?? this.config.childTimeoutMs,
-						parentRunId: context.parentRunId as string | undefined,
+						sessionId: spawnRecord.childSessionId,
+						parentSessionId: spawnRecord.parentSessionId,
+						parentTurnId: spawnRecord.parentTurnId,
 						depth: context.depth + 1,
 						...options.configOverrides,
 					})),
@@ -617,7 +677,7 @@ export class AgentManager {
 				//
 				// Without this every delegated child fell through to
 				// `autoApproveHandler`, so a host's "ask before acting" gate
-				// covered the top-level run and nothing it delegated.
+				// covered the top-level turn and nothing it delegated.
 				const inheritedHandler = options.configOverrides?.resumeHandler ?? context.resumeHandler
 				if (inheritedHandler) childConfig.resumeHandler = inheritedHandler
 
@@ -670,18 +730,19 @@ export class AgentManager {
 					topicId: context.topicId,
 					projectId: context.projectId,
 					tenantId: context.tenantId,
-					parentRunId: context.parentRunId,
+					parentSessionId: spawnRecord.parentSessionId,
+					parentTurnId: spawnRecord.parentTurnId,
 					depth: context.depth + 1,
 					resumeHandler: options.configOverrides?.resumeHandler ?? context.resumeHandler,
 				}
 			}
 
-			// The screens in force for the parent run, stamped onto the child
+			// The screens in force for the parent session, stamped onto the child
 			// the way the trace parent and the review handler are — and after
 			// both branches, because the bare-config branch builds its whole
 			// config by hand and would otherwise omit this one field.
 			//
-			// A child run builds its own executor, which installs
+			// A child session builds its own executor, which installs
 			// `DEFAULT_TOOL_RESULT_GUARDRAILS` when nothing said otherwise — so
 			// without this a parent that turned the screens off, or exempted a
 			// tool it knows, had that decision revert the moment it delegated,
@@ -701,8 +762,9 @@ export class AgentManager {
 			// Lineage is assigned by the spawning manager, not proposed by the
 			// child definition. A fixed configBuilder can ignore its inputs and
 			// configOverrides is caller-authored; neither may turn a child back
-			// into depth zero or attach it to a different parent run.
-			childConfig.parentRunId = context.parentRunId
+			// into depth zero or attach it to a different parent session.
+			childConfig.parentSessionId = spawnRecord.parentSessionId
+			childConfig.parentTurnId = spawnRecord.parentTurnId
 			childConfig.depth = context.depth + 1
 			childConfig.budget = childBudget
 			// The reservation is the execution ceiling, regardless of a builder's
@@ -739,7 +801,7 @@ export class AgentManager {
 			// 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()`
+			// against the registry at the turn rather than here — which `query()`
 			// does, and which is why this appends to `deniedTools` rather than
 			// synthesising an allow-list.
 			if (resolvedDenies.length > 0) {
@@ -749,6 +811,33 @@ export class AgentManager {
 			}
 			if (options.personaOverride) childConfig.persona = options.personaOverride
 
+			// Where the child session lives, stamped after the builder for the
+			// same reason as everything above: a `configBuilder` cannot forward
+			// a field it was never told about.
+			//
+			// A parent held in memory gives its child a fresh in-memory log (a
+			// log is one session's, never shared), and its checkpoint store
+			// when it named one, so the child writes nothing under
+			// `NAMZU_HOME`. Otherwise, with a layout known, the child's log goes
+			// under its parent (`<parent>/subagents/<child-id>.jsonl`) with its
+			// meta document beside it. A child config that names a session log
+			// or paths of its own chose where it goes, and keeps it.
+			const childLog = await this.placeChildSession(
+				spawnRecord,
+				childConfig,
+				context,
+				options,
+				taskId,
+			)
+			if (childLog) {
+				await this.startChildSessionLog(childLog, spawnRecord, context, options, taskId, {
+					id: agent.metadata.id,
+					name: agent.metadata.name,
+				})
+				childConfig.sessionLog = childLog
+				spawnRecord.releaseLog = registerChildSessionLog(childLog)
+			}
+
 			// Outside the branch, like the scope above it and for the same reason:
 			// a `configBuilder` cannot forward a field it was never told about.
 			//
@@ -778,6 +867,12 @@ export class AgentManager {
 					} catch (writeError) {
 						failure = writeError
 					}
+					// The child's turn is over either way; its parent hears so first.
+					await this.settleChildSession(
+						runningTask,
+						spawnRecord,
+						runningTask.state === 'canceled' ? 'cancelled' : 'failed',
+					)
 					// Cancellation may already have published a terminal handle. Its
 					// invocation has only NOW stopped; release the persisted edge here.
 					if (!this.instances.has(taskId) || isTerminalAgentTaskState(runningTask.state)) {
@@ -786,7 +881,7 @@ export class AgentManager {
 				})
 				.finally(() => {
 					this.executingTasks.delete(taskId)
-					if (!this.instances.has(taskId)) this.spawnRecords.delete(taskId)
+					if (!this.instances.has(taskId)) this.dropSpawnRecord(taskId)
 					this.pumpAdmissions(options.parentSessionId)
 				})
 				.catch((error) =>
@@ -827,9 +922,10 @@ export class AgentManager {
 			const error = toErrorMessage(reason)
 			this.emit({ type: 'failed', taskId: agentTask.taskId, error })
 			try {
-				await agentTask.runEventListener?.({
+				await agentTask.sessionEventListener?.({
 					type: 'agent_failed',
-					runId: agentTask.context.parentRunId,
+					sessionId: agentTask.context.parentSessionId,
+					turnId: agentTask.context.parentTurnId,
 					taskId: agentTask.taskId,
 					error,
 				})
@@ -843,7 +939,8 @@ export class AgentManager {
 		this.clearEvictionTimer(agentTask.taskId)
 		if (retainHandle) {
 			agentTask.result ??= {
-				runId: agentTask.context.parentRunId,
+				sessionId: agentTask.context.parentSessionId,
+				turnId: agentTask.context.parentTurnId,
 				status: 'failed',
 				usage: { ...EMPTY_TOKEN_USAGE },
 				cost: { ...ZERO_COST },
@@ -855,12 +952,23 @@ export class AgentManager {
 			agentTask.completedAt = Date.now()
 			this.scheduleEviction(agentTask.taskId)
 		} else this.instances.delete(agentTask.taskId)
-		this.spawnRecords.delete(agentTask.taskId)
+		this.dropSpawnRecord(agentTask.taskId)
 		this.resolveCompletionCallbacks(agentTask.taskId)
 		await this.rollbackSpawnResources(spawnRecord)
 	}
 
 	private async rollbackSpawnResources(spawnRecord: ChildSpawnRecord): Promise<void> {
+		spawnRecord.releaseLog?.()
+		// A child that never started leaves no meta document naming it: the
+		// session it describes is being deleted below.
+		if (spawnRecord.placement) {
+			await rm(spawnRecord.placement.metaPath, { force: true }).catch((err) =>
+				this.log.warn('Unstarted child meta removal failed', {
+					'namzu.store.path': spawnRecord.placement?.metaPath,
+					'exception.message': toErrorMessage(err),
+				}),
+			)
+		}
 		await this.disposeChildWorkspace(spawnRecord)
 		try {
 			// The edge must be removed before its child: stores reject deletion
@@ -875,6 +983,139 @@ export class AgentManager {
 		}
 	}
 
+	/** Forget a spawn record, and take its child's log out of the process-local lookup. */
+	private dropSpawnRecord(taskId: TaskId): void {
+		this.spawnRecords.get(taskId)?.releaseLog?.()
+		this.spawnRecords.delete(taskId)
+	}
+
+	/** The parent session's place in the tree: its ancestors, root first. */
+	private parentLocator(spawnRecord: ChildSpawnRecord): SessionLocator {
+		return {
+			sessionId: spawnRecord.parentSessionId,
+			ancestors: spawnRecord.ancestry.slice(0, -1),
+		}
+	}
+
+	/** The meta document for a placed child, as it stands at spawn. */
+	private childMeta(spawnRecord: ChildSpawnRecord): ChildSessionMeta {
+		const placement = spawnRecord.placement
+		if (!placement) throw new Error('A child session placed by no layout has no meta document')
+		return {
+			v: 1,
+			kind: 'child-session',
+			sessionId: spawnRecord.childSessionId,
+			parentSessionId: spawnRecord.parentSessionId,
+			parentTurnId: spawnRecord.parentTurnId,
+			rootSessionId: spawnRecord.rootSessionId,
+			depth: spawnRecord.childDepth,
+			toolCallId: placement.toolCallId,
+			agentType: placement.agentType,
+			description: placement.description,
+			status: 'running',
+			createdAt: placement.createdAt,
+		}
+	}
+
+	/**
+	 * Decide where a child session's log lives, and write its meta document
+	 * when this manager places it.
+	 *
+	 * - A config that names a `sessionLog` keeps it; one that names `paths`
+	 *   gets its log in that layout, under its parent.
+	 * - A parent held in memory gives a fresh `InMemorySessionLog`, plus its
+	 *   checkpoint store when it named one.
+	 * - Otherwise, with {@link AgentManagerDeps.paths} known, the log goes to
+	 *   `<parent-session-dir>/subagents/<child-id>.jsonl`, nested under every
+	 *   ancestor, with `<child-id>.meta.json` beside it.
+	 *
+	 * Returns the log the child should append to, or `undefined` to leave
+	 * the child's config as it is.
+	 */
+	private async placeChildSession(
+		spawnRecord: ChildSpawnRecord,
+		childConfig: BaseAgentConfig,
+		context: AgentTaskContext,
+		options: SendMessageOptions,
+		taskId: TaskId,
+	): Promise<SessionLog | undefined> {
+		if (childConfig.sessionLog !== undefined) return undefined
+		const inherited = context.childStorage
+		if (inherited?.kind === 'memory' && childConfig.paths === undefined) {
+			if (inherited.checkpointStore && childConfig.checkpointStore === undefined) {
+				childConfig.checkpointStore = inherited.checkpointStore
+			}
+			return new InMemorySessionLog({ sessionId: spawnRecord.childSessionId })
+		}
+		// The parent's own layout first: a child's log nests under its
+		// parent's session directory, so it must be the parent's layout.
+		const paths =
+			childConfig.paths ??
+			(inherited?.kind === 'disk' ? inherited.paths : undefined) ??
+			this.deps.paths
+		if (!paths) return undefined
+		childConfig.paths = paths
+		const parent = this.parentLocator(spawnRecord)
+		spawnRecord.placement = {
+			paths,
+			metaPath: paths.subagentMeta(parent, spawnRecord.childSessionId),
+			createdAt: new Date().toISOString(),
+			toolCallId: spawnToolCallId(taskId),
+			agentType: options.agentId,
+			description: describeSpawn(options),
+		}
+		await writeChildSessionMeta(spawnRecord.placement.metaPath, this.childMeta(spawnRecord))
+		return DiskSessionLog.at(paths, {
+			sessionId: spawnRecord.childSessionId,
+			ancestors: spawnRecord.ancestry,
+		})
+	}
+
+	/**
+	 * Open a child session placed by this manager with its `session_started`,
+	 * naming where it sits in the tree (`parent`: the spawning session, turn
+	 * and tool call, the root session, the depth, and the kind of spawn).
+	 *
+	 * Written here, before the child sessions, because only the manager knows all
+	 * of it: a child's config carries its parent session and turn but not the
+	 * tool call or the root. The child's own turn then finds the log started
+	 * and appends after it. A log that already has records is left alone.
+	 */
+	private async startChildSessionLog(
+		log: SessionLog,
+		spawnRecord: ChildSpawnRecord,
+		context: AgentTaskContext,
+		options: SendMessageOptions,
+		taskId: TaskId,
+		agent: { readonly id: string; readonly name: string },
+	): Promise<void> {
+		const lease = await log.claim({ holder: `namzu:agent-manager:${taskId}`, ttlMs: 30_000 })
+		if (lease === null) {
+			throw new Error(`Child session ${spawnRecord.childSessionId} is already leased`)
+		}
+		try {
+			if ((await log.head()) !== null) return
+			await log.append(lease, {
+				type: 'session_started',
+				projectId: context.projectId,
+				tenantId: spawnRecord.tenantId,
+				topicId: context.topicId,
+				cwd: options.input.workingDirectory ?? process.cwd(),
+				agent: { id: agent.id, name: agent.name, type: options.agentId },
+				parent: {
+					sessionId: spawnRecord.parentSessionId,
+					turnId: spawnRecord.parentTurnId,
+					toolCallId: spawnToolCallId(taskId),
+					rootSessionId: spawnRecord.rootSessionId,
+					depth: spawnRecord.childDepth,
+					kind: 'agent_spawn',
+				},
+			})
+		} finally {
+			await log.release(lease)
+		}
+	}
+
 	cancel(taskId: TaskId, cause?: CancelCause): void {
 		if (this.cancelingTasks.has(taskId)) return
 		const agentTask = this.instances.get(taskId)
@@ -882,23 +1123,23 @@ export class AgentManager {
 
 		// 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.
+		// turn saw a cancellation with no attributable origin at all.
 		// Abort listeners run synchronously. A pending task's parent observer
 		// must not reenter this method and replace an explicit user's cause.
 		this.cancelingTasks.add(taskId)
 		try {
-			agentTask.childAbortController.abort(cause ? new RunCancelled(cause) : undefined)
+			agentTask.childAbortController.abort(cause ? new TurnCancelled(cause) : undefined)
 			this.markCanceled(taskId, cause)
 		} finally {
 			this.cancelingTasks.delete(taskId)
 		}
 	}
 
-	cancelAll(parentRunId: RunId, cause: CancelCause = 'parent'): void {
+	cancelAll(parentSessionId: SessionId, 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)) {
+		for (const agentTask of this.listByParent(parentSessionId)) {
 			this.cancel(agentTask.taskId, cause)
 		}
 	}
@@ -960,8 +1201,10 @@ export class AgentManager {
 		return this.spawnRecords.get(taskId)
 	}
 
-	listByParent(parentRunId: RunId): AgentTask[] {
-		return Array.from(this.instances.values()).filter((t) => t.context.parentRunId === parentRunId)
+	listByParent(parentSessionId: SessionId): AgentTask[] {
+		return Array.from(this.instances.values()).filter(
+			(t) => t.context.parentSessionId === parentSessionId,
+		)
 	}
 
 	listActive(): AgentTask[] {
@@ -990,7 +1233,7 @@ export class AgentManager {
 			if (isTerminalAgentTaskState(agentTask.state)) {
 				this.clearEvictionTimer(taskId)
 				this.instances.delete(taskId)
-				if (!this.executingTasks.has(taskId)) this.spawnRecords.delete(taskId)
+				if (!this.executingTasks.has(taskId)) this.dropSpawnRecord(taskId)
 			}
 		}
 	}
@@ -1006,7 +1249,8 @@ export class AgentManager {
 			this.clearEvictionTimer(taskId)
 		}
 		// Every live child, not the children of one parent. This used to call
-		// `cancelAll('' as RunId)`, and `cancelAll` filters by parent run —
+		// `cancelAll` with an invented empty parent id, and `cancelAll` filters
+		// by parent —
 		// no task has an empty parent, so it matched nothing and the lines
 		// below then dropped every reference to work that was still running.
 		for (const taskId of [...this.instances.keys()]) {
@@ -1014,7 +1258,7 @@ export class AgentManager {
 		}
 		this.instances.clear()
 		for (const taskId of this.spawnRecords.keys())
-			if (!this.executingTasks.has(taskId)) this.spawnRecords.delete(taskId)
+			if (!this.executingTasks.has(taskId)) this.dropSpawnRecord(taskId)
 		this.listeners.length = 0
 	}
 
@@ -1227,7 +1471,7 @@ export class AgentManager {
 			// deny-by-default cascade policy (Convention #5): `deleteSession`
 			// throws when any subsession still references it, so the subsession
 			// record must be removed first. No failed-subsession audit row is
-			// kept — the `subsession_spawned` run event never fired (we aborted
+			// kept — the `child_session_spawned` event never fired (we aborted
 			// before `buildSpawnRecord`), so no observer is expecting one, and
 			// leaving a `status: 'failed'` breadcrumb would be a dangling
 			// record with no corresponding emission. The original `err` is the
@@ -1245,7 +1489,9 @@ export class AgentManager {
 			childSessionId: childSession.id,
 			tenantId: context.tenantId,
 			parentSessionId: options.parentSessionId,
+			parentTurnId: context.parentTurnId,
 			rootSessionId,
+			ancestry: parentAncestry,
 			childDepth,
 			workspaceRef,
 		}
@@ -1255,7 +1501,7 @@ export class AgentManager {
 		agentTask: AgentTask,
 		options: SendMessageOptions,
 		childConfig: BaseAgentConfig,
-		listener?: RunEventListener,
+		listener?: SessionEventListener,
 	): Promise<void> {
 		this.updateState(agentTask.taskId, 'running')
 		this.emit({ type: 'running', taskId: agentTask.taskId })
@@ -1269,22 +1515,24 @@ export class AgentManager {
 		const childListener = this.wrapChildListener(listener, spawnRecord)
 
 		const result = await agentTask.agent.run(input, childConfig, childListener)
-		agentTask.context.budget.bindRun(result.runId)
+		agentTask.context.budget.bindTurn(result.sessionId, result.turnId)
 		agentTask.context.budget.settle(result.usage?.totalTokens)
 		await agentTask.context.budget.flush()
 		await this.finalizeChild(agentTask, result)
 	}
 
 	/**
-	 * Wraps the parent listener so every event emitted from the child's run
-	 * carries the session-hierarchy `lineage` + `schemaVersion: 2` stamp.
-	 * Replaces the old `Object.assign({sourceAgentId, parentTaskId}, event)`
-	 * loose-cast pattern entirely — the types now encode the linkage.
+	 * Wraps the parent listener so every event relayed from the child session
+	 * carries its `lineage`. The child's own `seq` is dropped: it is a
+	 * position in the CHILD's log, and a parent listener keeping a reconnect
+	 * cursor per session must not read it as one in the parent's. Replaces the
+	 * old `Object.assign({sourceAgentId, parentTaskId}, event)` loose-cast
+	 * pattern entirely — the types now encode the linkage.
 	 */
 	private wrapChildListener(
-		listener: RunEventListener | undefined,
+		listener: SessionEventListener | undefined,
 		spawnRecord: ChildSpawnRecord | undefined,
-	): RunEventListener | undefined {
+	): SessionEventListener | undefined {
 		if (!listener) return undefined
 		if (!spawnRecord) return listener
 
@@ -1294,13 +1542,9 @@ export class AgentManager {
 			depth: spawnRecord.childDepth,
 		}
 
-		return async (event: RunEvent): Promise<void> => {
-			const stamped: RunEvent = {
-				...(event as RunEvent),
-				lineage,
-				schemaVersion: RUN_EVENT_SCHEMA_VERSION,
-			} as RunEvent
-			await listener(stamped)
+		return async (event: SessionEvent): Promise<void> => {
+			const { seq: _childSeq, ...relayed } = event
+			await listener({ ...relayed, lineage } as SessionEvent)
 		}
 	}
 
@@ -1360,7 +1604,7 @@ export class AgentManager {
 				//
 				// It runs after the summary is sealed and the sub-session flipped
 				// to `idle`, so nothing the terminalization path reads is gone
-				// before it reads it. It also runs BEFORE the `subsession_idled`
+				// before it reads it. It also runs BEFORE the `child_session_idled`
 				// emission below: a listener cannot reach into the workspace from
 				// that event. Stated rather than hedged — no consumer does today,
 				// and holding a worktree open for a hypothetical one is what this
@@ -1374,34 +1618,67 @@ export class AgentManager {
 			}
 		}
 
-		// Emit subsession_idled event on success before marking the task
-		// completed — consumers expect the ordering `run_completed (child) →
-		// subsession_idled → run_completed (parent)` per §10.5.
-		if (spawnRecord && agentTask.runEventListener && result.status === 'completed') {
-			const lineage: Lineage = {
-				parentSessionId: spawnRecord.parentSessionId,
-				rootSessionId: spawnRecord.rootSessionId,
-				depth: spawnRecord.childDepth,
-			}
+		if (spawnRecord) await this.settleChildSession(agentTask, spawnRecord, result.status)
+
+		this.markCompleted(agentTask.taskId, result)
+	}
+
+	/**
+	 * The child's turn is over: its meta document records how, and the
+	 * parent hears `child_session_idled`, before the task is marked settled —
+	 * consumers expect `turn_completed (child) → child_session_idled →
+	 * turn_completed (parent)`.
+	 *
+	 * Idled on every outcome, not only success: the event says the child's
+	 * turn ended and nothing is queued, which a failure is too. It is the
+	 * parent writer's cue to append `child_session_ended`, read from the
+	 * child's own terminal record (`childSessionEnded`).
+	 */
+	private async settleChildSession(
+		agentTask: AgentTask,
+		spawnRecord: ChildSpawnRecord,
+		status: TurnExecutionStatus,
+	): Promise<void> {
+		if (spawnRecord.placement) {
 			try {
-				await agentTask.runEventListener({
-					type: 'subsession_idled',
-					runId: agentTask.context.parentRunId,
-					subSessionId: spawnRecord.subSessionId,
-					parentSessionId: spawnRecord.parentSessionId,
-					lineage,
-					schemaVersion: RUN_EVENT_SCHEMA_VERSION,
-					at: new Date(),
-				})
+				await writeChildSessionMeta(
+					spawnRecord.placement.paths.subagentMeta(
+						this.parentLocator(spawnRecord),
+						spawnRecord.childSessionId,
+					),
+					{
+						...this.childMeta(spawnRecord),
+						status,
+						endedAt: new Date().toISOString(),
+					},
+				)
 			} catch (err) {
-				this.log.error('subsession_idled emission error', {
+				this.log.warn('Child session meta update failed', {
 					'namzu.task.id': agentTask.taskId,
 					'exception.message': toErrorMessage(err),
 				})
 			}
 		}
-
-		this.markCompleted(agentTask.taskId, result)
+		const listener = agentTask.sessionEventListener
+		if (!listener) return
+		try {
+			await listener({
+				type: 'child_session_idled',
+				sessionId: spawnRecord.parentSessionId,
+				turnId: spawnRecord.parentTurnId,
+				childSessionId: spawnRecord.childSessionId,
+				lineage: {
+					parentSessionId: spawnRecord.parentSessionId,
+					rootSessionId: spawnRecord.rootSessionId,
+					depth: spawnRecord.childDepth,
+				},
+			})
+		} catch (err) {
+			this.log.error('child_session_idled emission error', {
+				'namzu.task.id': agentTask.taskId,
+				'exception.message': toErrorMessage(err),
+			})
+		}
 	}
 
 	private markCompleted(taskId: TaskId, result: BaseAgentResult): void {
@@ -1412,9 +1689,10 @@ export class AgentManager {
 		agentTask.completedAt = Date.now()
 		this.updateState(taskId, 'completed')
 		this.emit({ type: 'completed', taskId, result })
-		this.emitRunEvent(agentTask, {
+		this.emitSessionEvent(agentTask, {
 			type: 'agent_completed',
-			runId: agentTask.context.parentRunId,
+			sessionId: agentTask.context.parentSessionId,
+			turnId: agentTask.context.parentTurnId,
 			taskId,
 			result,
 		})
@@ -1427,8 +1705,12 @@ export class AgentManager {
 		const agentTask = this.instances.get(taskId)
 		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return
 
+		// The child's own turn when its budget was bound to one; the parent
+		// turn that asked for it otherwise.
+		const bound = agentTask.context.budget.turn
 		agentTask.result = {
-			runId: agentTask.context.budget.runId ?? agentTask.context.parentRunId,
+			sessionId: bound?.sessionId ?? agentTask.context.parentSessionId,
+			turnId: bound?.turnId ?? agentTask.context.parentTurnId,
 			status: 'failed',
 			usage: agentTask.context.budget.ownUsage,
 			budget: agentTask.context.budget.summary(),
@@ -1441,9 +1723,10 @@ export class AgentManager {
 		agentTask.completedAt = Date.now()
 		this.updateState(taskId, 'failed')
 		this.emit({ type: 'failed', taskId, error })
-		this.emitRunEvent(agentTask, {
+		this.emitSessionEvent(agentTask, {
 			type: 'agent_failed',
-			runId: agentTask.context.parentRunId,
+			sessionId: agentTask.context.parentSessionId,
+			turnId: agentTask.context.parentTurnId,
 			taskId,
 			error,
 		})
@@ -1487,7 +1770,7 @@ export class AgentManager {
 	 *
 	 * Called on every terminal path, success included. `has(backend)` before
 	 * `get(backend)` because the registry is deny-by-default and throws on an
-	 * unknown kind — a driver deregistered mid-run must not turn cleanup into
+	 * unknown kind — a driver deregistered mid-turn must not turn cleanup into
 	 * an exception on a child that already finished.
 	 *
 	 * Never throws. Disposal is cleanup, not part of the child's result: the
@@ -1522,9 +1805,10 @@ export class AgentManager {
 		agentTask.completedAt = Date.now()
 		this.updateState(taskId, 'canceled')
 		this.emit({ type: 'canceled', taskId })
-		this.emitRunEvent(agentTask, {
+		this.emitSessionEvent(agentTask, {
 			type: 'agent_canceled',
-			runId: agentTask.context.parentRunId,
+			sessionId: agentTask.context.parentSessionId,
+			turnId: agentTask.context.parentTurnId,
 			taskId,
 			...(cause ? { cancelCause: cause } : {}),
 		})
@@ -1557,7 +1841,7 @@ export class AgentManager {
 
 		const timer = setTimeout(() => {
 			this.instances.delete(taskId)
-			if (!this.executingTasks.has(taskId)) this.spawnRecords.delete(taskId)
+			if (!this.executingTasks.has(taskId)) this.dropSpawnRecord(taskId)
 			this.evictionTimers.delete(taskId)
 			this.log.info('Agent task evicted', { 'namzu.agent.task_id': taskId })
 		}, this.config.evictionMs)
@@ -1594,10 +1878,11 @@ export class AgentManager {
 		}
 	}
 
-	private emitRunEvent(agentTask: AgentTask, event: RunEvent): void {
-		if (!agentTask.runEventListener) return
+	private emitSessionEvent(agentTask: AgentTask, event: SessionEvent): void {
+		const listener = agentTask.sessionEventListener
+		if (!listener) return
 		const reportFailure = (error: unknown): void => {
-			this.log.error('RunEvent emission error', {
+			this.log.error('SessionEvent emission error', {
 				'namzu.event.type': event.type,
 				'exception.message': toErrorMessage(error),
 			})
@@ -1605,13 +1890,48 @@ export class AgentManager {
 		try {
 			// Terminal observation must not delay completion or leak a rejected
 			// listener promise into the host as an unhandled rejection.
-			void Promise.resolve(agentTask.runEventListener(event)).catch(reportFailure)
+			void Promise.resolve(listener(event)).catch(reportFailure)
 		} catch (error) {
 			reportFailure(error)
 		}
 	}
 }
 
+/**
+ * The id `child_session_spawned` and the meta document name as the call that
+ * spawned the child.
+ *
+ * The provider's tool-call id does not reach this manager: neither
+ * `CreateTaskOptions` nor `SendMessageOptions` carries it. Until it does, the
+ * spawn's task id stands in, which is unique per spawn and is the id every
+ * `agent_*` event for this child already carries.
+ */
+function spawnToolCallId(taskId: TaskId): ToolUseId {
+	return taskId as string as ToolUseId
+}
+
+/** Longest spawn description kept on the record. */
+const SPAWN_DESCRIPTION_MAX_CHARS = 200
+
+/**
+ * One line saying what the child was asked to do: the first line of the last
+ * user message it was handed, or its agent id when there is none.
+ */
+function describeSpawn(options: SendMessageOptions): string {
+	for (let i = options.input.messages.length - 1; i >= 0; i--) {
+		const message = options.input.messages[i]
+		if (message?.role !== 'user' || typeof message.content !== 'string') continue
+		const line = message.content.trim().split('\n', 1)[0]?.trim() ?? ''
+		if (line.length > 0) return line.slice(0, SPAWN_DESCRIPTION_MAX_CHARS)
+	}
+	return options.agentId
+}
+
+/** The child's log, relative to the parent's session directory. */
+function childLogPath(childSessionId: SessionId): string {
+	return `subagents/${childSessionId}.jsonl`
+}
+
 /**
  * The display grouping a host supplied at spawn, in the shape `agent_pending`
  * carries it.