@namzu/sdk 0.1.8 → 0.3.0

package/src/manager/agent/lifecycle.ts

@@ -1,6 +1,17 @@
 import { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js'
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import type { AgentRegistry } from '../../registry/agent/definitions.js'
+import { RUN_EVENT_SCHEMA_VERSION } from '../../session/events/schema-version.js'
+import {
+	type CapacityValidator,
+	DelegationCapacityExceeded,
+} from '../../session/handoff/capacity.js'
+import type { ActorRef } from '../../session/hierarchy/actor.js'
+import type { Lineage } from '../../session/hierarchy/lineage.js'
+import type { SessionSummaryMaterializer } from '../../session/summary/materialize.js'
+import type { SessionSummaryOutcome } from '../../session/summary/ref.js'
+import type { WorkspaceRef } from '../../session/workspace/ref.js'
+import type { WorkspaceBackendRegistry } from '../../session/workspace/registry.js'
 import type { BaseAgentConfig, BaseAgentResult } from '../../types/agent/base.js'
 import type {
 	AgentLifecycleEvent,
@@ -14,33 +25,88 @@ import type {
 	SendMessageOptions,
 } from '../../types/agent/task.js'
 import { isTerminalAgentTaskState } from '../../types/agent/task.js'
-import type { RunId, TaskId } from '../../types/ids/index.js'
+import type { AgentId, RunId, SessionId, TaskId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
+import type { RunEvent, RunEventListener } from '../../types/run/events.js'
+import type { SubSessionId } from '../../types/session/ids.js'
+import type { SessionStore } from '../../types/session/store.js'
 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 type { ThreadManager } from '../thread/lifecycle.js'
+
+/**
+ * Dependencies threaded into {@link AgentManager}. Phase 6 promoted the
+ * SubSession + Session + WorkspaceRef triple to mandatory spawn primitives —
+ * these collaborators replace the old `Object.assign({sourceAgentId,
+ * parentTaskId})` loose-cast cadence with a typed {@link Lineage} +
+ * {@link SessionSummaryMaterializer} closure of the parent→child message gap.
+ *
+ * Phase 9 Known Delta #5: fields are now unconditional required. The legacy
+ * "run without deps" compat branch was removed; every `AgentManager` consumer
+ * (SDK internals, `@namzu/agents`, `@namzu/api`, `@namzu/cli`) MUST wire the
+ * full set before instantiating. Convention #0 (no workarounds): the
+ * partially-wired mode was a migration-window bridge; 0.2.0 closes it.
+ *
+ * `workspaceRegistry` is required but may be empty — spawns without a
+ * registered workspace backend still succeed with `workspaceRef: undefined`
+ * (the runtime uses `.has(backend)` to gate provisioning). This keeps the
+ * registry deny-by-default while matching pattern doc §7.1 (lazy workspace
+ * provisioning).
+ */
+export interface AgentManagerDeps {
+	readonly sessionStore: SessionStore
+	readonly workspaceRegistry: WorkspaceBackendRegistry
+	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
+	 * archive-gate gap flagged by the Phase 2.5 commit: without this,
+	 * `ThreadManager.archive` was best-effort because spawn could still
+	 * attach a live session under an archived Thread.
+	 */
+	readonly threadManager: ThreadManager
+}
+
+interface ChildSpawnRecord {
+	subSessionId: SubSessionId
+	childSessionId: SessionId
+	tenantId: TenantId
+	parentSessionId: SessionId
+	rootSessionId: SessionId
+	childDepth: number
+	workspaceRef?: WorkspaceRef
+}
 
 export class AgentManager {
 	private registry: AgentRegistry
 	private instances: Map<TaskId, AgentTask> = new Map()
+	private spawnRecords: Map<TaskId, ChildSpawnRecord> = new Map()
 	private completionCallbacks: Map<TaskId, Array<() => void>> = new Map()
 	private listeners: AgentLifecycleListener[] = []
 	private log: Logger
 	private config: Readonly<AgentManagerConfig>
 	private evictionTimers: Map<TaskId, ReturnType<typeof setTimeout>> = new Map()
+	private deps: AgentManagerDeps
 
-	constructor(registry: AgentRegistry, config?: Partial<AgentManagerConfig>) {
+	constructor(
+		registry: AgentRegistry,
+		config: Partial<AgentManagerConfig> | undefined,
+		deps: AgentManagerDeps,
+	) {
 		this.registry = registry
 		this.config = { ...AGENT_MANAGER_DEFAULTS, ...config }
 		this.log = getRootLogger().child({ component: 'AgentManager' })
+		this.deps = deps
 	}
 
 	async sendMessage(
 		options: SendMessageOptions,
 		context: AgentTaskContext,
-		listener?: import('../../types/run/events.js').RunEventListener,
+		listener?: RunEventListener,
 	): Promise<AgentTask> {
 		if (context.depth >= this.config.maxDepth) {
 			throw new Error(
@@ -48,6 +114,12 @@ export class AgentManager {
 			)
 		}
 
+		if (options.tenantId !== context.tenantId) {
+			throw new Error(
+				`Tenant mismatch: options.tenantId=${options.tenantId} differs from context.tenantId=${context.tenantId}. Cross-tenant spawn rejected (Convention #17).`,
+			)
+		}
+
 		const agent = this.registry.resolve(options.agentId)
 
 		const childAbortController = createChildAbortController(context.parentAbortController)
@@ -61,13 +133,40 @@ export class AgentManager {
 		)
 		context.budgetTracker.remaining -= allocatedTokens
 
+		// Phase 6: SubSession + child Session + WorkspaceRef triple. Happens
+		// before taskId minting so a capacity failure short-circuits cleanly
+		// with no observable state change.
+		const spawnRecord = await this.provisionSpawn(options, context)
+
 		const taskId = generateTaskId()
+
+		const childParentActor: ActorRef = {
+			kind: 'agent',
+			agentId: context.parentAgentId as AgentId,
+			tenantId: context.tenantId,
+			parentActor: context.parentActor,
+		}
+
+		const childContext: AgentTaskContext = {
+			parentRunId: context.parentRunId,
+			parentAgentId: context.parentAgentId,
+			parentAbortController: context.parentAbortController,
+			depth: context.depth + 1,
+			budgetTracker: context.budgetTracker,
+			factoryOptions: context.factoryOptions,
+			tenantId: context.tenantId,
+			threadId: context.threadId,
+			sessionId: spawnRecord.childSessionId,
+			projectId: context.projectId,
+			parentActor: childParentActor,
+		}
+
 		const agentTask: AgentTask = {
 			taskId,
 			agentId: options.agentId,
 			agent,
 			childAbortController,
-			context,
+			context: childContext,
 			state: 'pending',
 			pendingMessages: [],
 			createdAt: Date.now(),
@@ -75,6 +174,7 @@ export class AgentManager {
 		}
 
 		this.instances.set(taskId, agentTask)
+		this.spawnRecords.set(taskId, spawnRecord)
 		this.emit({
 			type: 'pending',
 			taskId,
@@ -92,17 +192,37 @@ export class AgentManager {
 				childAgentId: options.agentId,
 				depth: context.depth,
 			})
+
+			const lineage: Lineage = {
+				parentSessionId: spawnRecord.parentSessionId,
+				rootSessionId: spawnRecord.rootSessionId,
+				depth: spawnRecord.childDepth,
+			}
+			listener({
+				type: 'subsession_spawned',
+				runId: context.parentRunId,
+				subSessionId: spawnRecord.subSessionId,
+				parentSessionId: spawnRecord.parentSessionId,
+				spawnedBy: context.parentActor,
+				lineage,
+				schemaVersion: RUN_EVENT_SCHEMA_VERSION,
+				at: new Date(),
+			})
 		}
 		this.log.info(`Agent task pending: ${taskId} (${options.agentId}, depth=${context.depth})`)
 
 		const definition = this.registry.getOrThrow(options.agentId)
 		let childConfig: BaseAgentConfig
-		if (definition.configBuilder && context.factoryOptions) {
+		if (definition.configBuilder) {
+			// Call the configBuilder regardless of whether factoryOptions were
+			// supplied. BYO-provider flows (Bedrock IAM, custom ProviderRegistry)
+			// commonly omit factoryOptions because the provider resolves its own
+			// credentials; the builder still needs to run to wire provider+tools.
+			// Defaults: empty factoryOptions when omitted; configOverrides win.
 			childConfig = await definition.configBuilder({
-				...context.factoryOptions,
+				...(context.factoryOptions ?? {}),
 				tokenBudget: allocatedTokens,
 				timeoutMs: options.budgetAllocation?.timeoutMs ?? context.budgetTracker.remaining,
-				threadId: context.threadId as string | undefined,
 				parentRunId: context.parentRunId as string | undefined,
 				depth: context.depth + 1,
 				...options.configOverrides,
@@ -111,8 +231,16 @@ export class AgentManager {
 			if (!childConfig.contextLevel && definition.contextLevel) {
 				childConfig.contextLevel = definition.contextLevel
 			}
+
+			// Propagate session-hierarchy scoping onto the child config. The
+			// 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.projectId = context.projectId
+			childConfig.tenantId = context.tenantId
 		} else {
-			this.log.warn('No configBuilder or factoryOptions, using bare config', {
+			this.log.warn('No configBuilder, using bare config', {
 				agentId: options.agentId,
 			})
 			childConfig = {
@@ -123,7 +251,10 @@ export class AgentManager {
 				maxIterations: options.configOverrides?.maxIterations,
 				maxResponseTokens: options.configOverrides?.maxResponseTokens,
 				env: options.configOverrides?.env,
+				sessionId: spawnRecord.childSessionId,
 				threadId: context.threadId,
+				projectId: context.projectId,
+				tenantId: context.tenantId,
 				parentRunId: context.parentRunId,
 				depth: context.depth + 1,
 			}
@@ -193,6 +324,10 @@ export class AgentManager {
 		return this.instances.get(taskId)
 	}
 
+	getSpawnRecord(taskId: TaskId): ChildSpawnRecord | undefined {
+		return this.spawnRecords.get(taskId)
+	}
+
 	listByParent(parentRunId: RunId): AgentTask[] {
 		return Array.from(this.instances.values()).filter((t) => t.context.parentRunId === parentRunId)
 	}
@@ -223,6 +358,7 @@ export class AgentManager {
 			if (isTerminalAgentTaskState(agentTask.state)) {
 				this.clearEvictionTimer(taskId)
 				this.instances.delete(taskId)
+				this.spawnRecords.delete(taskId)
 			}
 		}
 	}
@@ -233,14 +369,174 @@ export class AgentManager {
 		}
 		this.cancelAll('' as RunId)
 		this.instances.clear()
+		this.spawnRecords.clear()
 		this.listeners.length = 0
 	}
 
+	private async provisionSpawn(
+		options: SendMessageOptions,
+		context: AgentTaskContext,
+	): Promise<ChildSpawnRecord> {
+		// Phase 9: deps are unconditional required. Every spawn produces a
+		// SubSession + Session + WorkspaceRef triple (Convention #0: no
+		// partial/legacy path).
+		const store = this.deps.sessionStore
+
+		// 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
+		// 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
+		// single-responsibility boundary.
+		await this.deps.threadManager.requireOpen(context.threadId, 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`
+		// check in handoff (Phase 2.4).
+		const parentSession = await store.getSession(options.parentSessionId, context.tenantId)
+		if (!parentSession) {
+			throw new Error(
+				`Parent session ${options.parentSessionId} not found for tenant ${context.tenantId} — spawn rejected`,
+			)
+		}
+		if (parentSession.threadId !== context.threadId) {
+			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).`,
+			)
+		}
+		if (parentSession.projectId !== context.projectId) {
+			throw new Error(
+				`Project mismatch on spawn: parent session ${parentSession.id} is on project ${parentSession.projectId}, but context.projectId=${context.projectId}.`,
+			)
+		}
+
+		const project = await store.getProject(context.projectId, context.tenantId)
+		if (!project) {
+			throw new Error(
+				`Project ${context.projectId} not found for tenant ${context.tenantId} — spawn rejected`,
+			)
+		}
+
+		// Capacity: depth + width. Depth uses the parent session's ancestry
+		// chain; width counts existing direct children of the parent.
+		await this.deps.capacity.validateDepth(
+			options.parentSessionId,
+			project.config.maxDelegationDepth,
+			context.tenantId,
+		)
+		await this.deps.capacity.validateWidth(
+			options.parentSessionId,
+			1,
+			project.config.maxDelegationWidth,
+			context.tenantId,
+		)
+
+		// Ancestry walk gives both the child depth and the root session id
+		// attached to every sub-session event from here down.
+		const parentAncestry = await store.getAncestry(options.parentSessionId, context.tenantId)
+		const rootSessionId = parentAncestry[0] ?? options.parentSessionId
+		const childDepth = parentAncestry.length
+
+		const childActor: ActorRef = {
+			kind: 'agent',
+			agentId: options.agentId as AgentId,
+			tenantId: context.tenantId,
+			parentActor: context.parentActor,
+		}
+
+		// Child session inherits the parent's threadId verbatim (cross-thread
+		// 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`.
+		const childSession = await store.createSession(
+			{
+				threadId: context.threadId,
+				projectId: context.projectId,
+				currentActor: childActor,
+			},
+			context.tenantId,
+		)
+
+		// Compensating rollback wraps every mutation after createSession so a
+		// mid-flight failure (status flip, subsession insert, workspace driver)
+		// leaves no orphan child session. Codex SPAWN-ROLLBACK critique (Phase
+		// 2 review, 2026-04-18): without this, `workspaceRegistry.get().create`
+		// throwing — or a concurrent `updateSession` race — strands an
+		// `active` child session with no subsession edge, invisible to the
+		// parent but counted against `maxDelegationWidth`.
+		let subSession: Awaited<ReturnType<typeof store.createSubSession>> | undefined
+		let workspaceRef: WorkspaceRef | undefined
+		try {
+			// Flip to 'active' so the materializer's atomic write + status flip
+			// lands on terminal — §5.3: pending→active→idle.
+			await store.updateSession({ ...childSession, status: 'active' }, context.tenantId)
+
+			subSession = await store.createSubSession(
+				{
+					parentSessionId: options.parentSessionId,
+					childSessionId: childSession.id,
+					kind: 'agent_spawn',
+					spawnedBy: context.parentActor,
+					failureMode: 'delegate',
+					completionMode: 'summary_ref',
+				},
+				context.tenantId,
+			)
+
+			// Workspace provisioning — best-effort. When the requested backend
+			// is registered we create a new workspace for the child; failures
+			// surface as WorkspaceBackendError and abort the spawn (Convention
+			// #0: no silent fallback). Pattern doc §7.1 allows lazy
+			// provisioning: an unregistered backend leaves `workspaceRef:
+			// undefined` on the spawn record, not a hard error — the registry
+			// is the capability surface.
+			const backend = options.workspaceBackend ?? 'git-worktree'
+			if (this.deps.workspaceRegistry.has(backend)) {
+				const driver = this.deps.workspaceRegistry.get(backend)
+				workspaceRef = await driver.create({ label: subSession.id })
+			}
+		} catch (err) {
+			// Compensating rollback order is mandated by the store's
+			// 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
+			// 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
+			// caller-visible signal; cleanup errors are swallowed so they
+			// cannot mask it.
+			if (subSession !== undefined) {
+				await store.deleteSubSession(subSession.id, context.tenantId).catch(() => undefined)
+			}
+			await store.deleteSession(childSession.id, context.tenantId).catch(() => undefined)
+			throw err
+		}
+
+		return {
+			subSessionId: subSession.id,
+			childSessionId: childSession.id,
+			tenantId: context.tenantId,
+			parentSessionId: options.parentSessionId,
+			rootSessionId,
+			childDepth,
+			workspaceRef,
+		}
+	}
+
 	private async runChild(
 		agentTask: AgentTask,
 		options: SendMessageOptions,
 		childConfig: BaseAgentConfig,
-		listener?: import('../../types/run/events.js').RunEventListener,
+		listener?: RunEventListener,
 	): Promise<void> {
 		this.updateState(agentTask.taskId, 'running')
 		this.emit({ type: 'running', taskId: agentTask.taskId })
@@ -250,17 +546,135 @@ export class AgentManager {
 			signal: agentTask.childAbortController.signal,
 		}
 
-		const childListener = listener
-			? async (event: import('../../types/run/events.js').RunEvent): Promise<void> => {
-					const annotated = Object.assign({}, event, {
-						sourceAgentId: agentTask.agentId,
-						parentTaskId: agentTask.taskId,
+		const spawnRecord = this.spawnRecords.get(agentTask.taskId)
+		const childListener = this.wrapChildListener(listener, spawnRecord)
+
+		const result = await agentTask.agent.run(input, childConfig, childListener)
+		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.
+	 */
+	private wrapChildListener(
+		listener: RunEventListener | undefined,
+		spawnRecord: ChildSpawnRecord | undefined,
+	): RunEventListener | undefined {
+		if (!listener) return undefined
+		if (!spawnRecord) return listener
+
+		const lineage: Lineage = {
+			parentSessionId: spawnRecord.parentSessionId,
+			rootSessionId: spawnRecord.rootSessionId,
+			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)
+		}
+	}
+
+	private async finalizeChild(agentTask: AgentTask, result: BaseAgentResult): Promise<void> {
+		const spawnRecord = this.spawnRecords.get(agentTask.taskId)
+
+		// Kernel terminalization (§8.1): Materializer seals the summary and
+		// atomically flips the child session active→idle. Only run when the
+		// child actually succeeded; failed sub-sessions skip materialization
+		// and transition the sub-session record to 'failed' (§5.5).
+		if (spawnRecord) {
+			const store = this.deps.sessionStore
+			try {
+				if (result.status === 'completed') {
+					const outcome: SessionSummaryOutcome = deriveOutcome(result)
+					const agentSummary = deriveAgentSummary(result)
+					const summary = await this.deps.summaryMaterializer.materialize({
+						sessionId: spawnRecord.childSessionId,
+						tenantId: spawnRecord.tenantId,
+						finalOutcome: outcome,
+						agentSummary,
+						declaredDeliverables: [],
+						keyDecisions: [],
 					})
-					await listener(annotated as import('../../types/run/events.js').RunEvent)
+
+					const subSession = await store.getSubSession(
+						spawnRecord.subSessionId,
+						spawnRecord.tenantId,
+					)
+					if (subSession) {
+						await store.updateSubSession(
+							{ ...subSession, status: 'idle', summaryRef: summary.id },
+							spawnRecord.tenantId,
+						)
+					}
+				} else {
+					// Non-success: mark sub-session failed and, when we own a
+					// workspace, dispose it. Dispose errors are logged but not
+					// propagated — the sub-session state is already persisted.
+					const subSession = await store.getSubSession(
+						spawnRecord.subSessionId,
+						spawnRecord.tenantId,
+					)
+					if (subSession) {
+						await store.updateSubSession({ ...subSession, status: 'failed' }, spawnRecord.tenantId)
+					}
+					if (spawnRecord.workspaceRef) {
+						const backend = spawnRecord.workspaceRef.meta.backend
+						if (this.deps.workspaceRegistry.has(backend)) {
+							await this.deps.workspaceRegistry
+								.get(backend)
+								.dispose(spawnRecord.workspaceRef)
+								.catch((disposeErr) => {
+									this.log.warn('Workspace dispose failed', {
+										backend,
+										error: toErrorMessage(disposeErr),
+									})
+								})
+						}
+					}
 				}
-			: undefined
+			} catch (err) {
+				this.log.error('Sub-session finalization failed', {
+					taskId: agentTask.taskId,
+					error: toErrorMessage(err),
+				})
+			}
+		}
+
+		// 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,
+			}
+			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(),
+				})
+			} catch (err) {
+				this.log.error('subsession_idled emission error', {
+					taskId: agentTask.taskId,
+					error: toErrorMessage(err),
+				})
+			}
+		}
 
-		const result = await agentTask.agent.run(input, childConfig, childListener)
 		this.markCompleted(agentTask.taskId, result)
 	}
 
@@ -307,10 +721,45 @@ export class AgentManager {
 			error,
 		})
 		this.log.error(`Agent task failed: ${taskId}`, { error })
+
+		// Best-effort: mark sub-session failed + dispose workspace. The result
+		// emission path already synthesized a failure result above.
+		const spawnRecord = this.spawnRecords.get(taskId)
+		if (spawnRecord) {
+			this.failSubSession(spawnRecord).catch((err) => {
+				this.log.warn('SubSession failure update failed', {
+					taskId,
+					error: toErrorMessage(err),
+				})
+			})
+		}
+
 		this.scheduleEviction(taskId)
 		this.resolveCompletionCallbacks(taskId)
 	}
 
+	private async failSubSession(spawnRecord: ChildSpawnRecord): Promise<void> {
+		const subSession = await this.deps.sessionStore.getSubSession(
+			spawnRecord.subSessionId,
+			spawnRecord.tenantId,
+		)
+		if (subSession && subSession.status !== 'failed') {
+			await this.deps.sessionStore.updateSubSession(
+				{ ...subSession, status: 'failed' },
+				spawnRecord.tenantId,
+			)
+		}
+		if (spawnRecord.workspaceRef) {
+			const backend = spawnRecord.workspaceRef.meta.backend
+			if (this.deps.workspaceRegistry.has(backend)) {
+				await this.deps.workspaceRegistry
+					.get(backend)
+					.dispose(spawnRecord.workspaceRef)
+					.catch(() => undefined)
+			}
+		}
+	}
+
 	private markCanceled(taskId: TaskId): void {
 		const agentTask = this.instances.get(taskId)
 		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return
@@ -351,6 +800,7 @@ export class AgentManager {
 
 		const timer = setTimeout(() => {
 			this.instances.delete(taskId)
+			this.spawnRecords.delete(taskId)
 			this.evictionTimers.delete(taskId)
 			this.log.info(`Agent task evicted: ${taskId}`)
 		}, this.config.evictionMs)
@@ -387,10 +837,7 @@ export class AgentManager {
 		}
 	}
 
-	private emitRunEvent(
-		agentTask: AgentTask,
-		event: import('../../types/run/events.js').RunEvent,
-	): void {
+	private emitRunEvent(agentTask: AgentTask, event: RunEvent): void {
 		if (!agentTask.runEventListener) return
 		try {
 			agentTask.runEventListener(event)
@@ -403,3 +850,50 @@ export class AgentManager {
 		}
 	}
 }
+
+/**
+ * Maps a {@link BaseAgentResult} to {@link SessionSummaryOutcome}. Phase 6
+ * INTERPRETATION: `completed` → `succeeded`; any other status → `failed`.
+ * A dedicated `partial` signal requires structured-output contracts on the
+ * child's terminal turn (§8.1) which lands in a later phase.
+ */
+function deriveOutcome(result: BaseAgentResult): SessionSummaryOutcome {
+	if (result.status === 'completed') {
+		return { status: 'succeeded' }
+	}
+	const verdict = result.lastError ?? String(result.status)
+	return { status: 'failed', verdict }
+}
+
+const SUMMARY_FALLBACK_MAX_CHARS = 4000
+
+/**
+ * Pulls the agent's own narration from the final assistant message. §8.1:
+ * agents may register a structured-output contract for this; when absent
+ * we fall back to the last text block. Bounded by the summary char cap so
+ * the materializer never rejects on length at this seam.
+ */
+function deriveAgentSummary(result: BaseAgentResult): string {
+	const fromResult = result.result?.trim()
+	if (fromResult) {
+		return fromResult.length > SUMMARY_FALLBACK_MAX_CHARS
+			? fromResult.slice(0, SUMMARY_FALLBACK_MAX_CHARS)
+			: fromResult
+	}
+	for (let i = result.messages.length - 1; i >= 0; i--) {
+		const msg = result.messages[i]
+		if (msg?.role === 'assistant') {
+			const content = typeof msg.content === 'string' ? msg.content : ''
+			if (content.trim().length > 0) {
+				return content.length > SUMMARY_FALLBACK_MAX_CHARS
+					? content.slice(0, SUMMARY_FALLBACK_MAX_CHARS)
+					: content
+			}
+		}
+	}
+	return ''
+}
+
+// Re-export the capacity-violation type so downstream consumers that import
+// via the AgentManager module surface don't reach into session/handoff/.
+export { DelegationCapacityExceeded }

package/src/manager/index.ts

@@ -16,4 +16,7 @@ export type {
 export { PlanManager } from './plan/lifecycle.js'
 export type { PlanEvent, PlanEventListener, PlanApprovalHandler } from './plan/lifecycle.js'
 
+export { ThreadManager } from './thread/lifecycle.js'
+export type { ThreadManagerDeps } from './thread/lifecycle.js'
+
 export { AgentManager } from './agent/lifecycle.js'