@namzu/sdk 49.0.0 → 50.0.0

package/src/scheduler/completion-inbox.ts

@@ -77,6 +77,11 @@ const OWNED_WORK_DISPLAY_LIMIT = 16
 export class CompletionInbox {
 	private readonly unheard = new Map<TaskId, TaskHandle>()
 	private readonly claimed = new Set<TaskId>()
+	/** Persistence that must settle before an owned result may be delivered. */
+	private readonly deliveryGates = new Map<
+		TaskId,
+		{ settled: Promise<void>; state: 'pending' | 'ready' | 'failed'; error?: unknown }
+	>()
 	/** Launched with nothing waiting on it, and not settled yet. */
 	private readonly outstanding = new Set<TaskId>()
 	/**
@@ -136,6 +141,8 @@ export class CompletionInbox {
 	 */
 	private readonly unowned = new Map<TaskId, TaskHandle>()
 	private readonly arrivals = new Set<() => void>()
+	private readonly drains = new Set<() => void>()
+	private lifecycle = 0
 	private detach?: () => void
 	/** Kept for {@link launched}: the source of truth about a task's state. */
 	private gateway?: TaskScheduler
@@ -173,7 +180,10 @@ export class CompletionInbox {
 			this.markSettled(handle.taskId)
 			if (this.claimed.has(handle.taskId)) return
 			this.unheard.set(handle.taskId, handle)
-			for (const wake of this.arrivals) wake()
+			if (this.hasUnheard) for (const wake of this.arrivals) wake()
+			if (this.deliveryGates.get(handle.taskId)?.state === 'failed') {
+				for (const finish of [...this.drains]) finish()
+			}
 		})
 		return this.detach
 	}
@@ -261,6 +271,47 @@ export class CompletionInbox {
 		for (const wake of [...this.arrivals]) wake()
 	}
 
+	/**
+	 * Hold delivery until this owned task's tracking writes have settled.
+	 *
+	 * Register synchronously after `launched`, before handing control back to
+	 * a consumer. The promise receives no worker output from this inbox.
+	 * Rejections are retained and reported by either drain; the result stays
+	 * queued rather than being announced with stale tracking state.
+	 */
+	deferDelivery(taskId: TaskId, settlement: Promise<void>): void {
+		if (!this.ours.has(taskId) || this.claimed.has(taskId)) {
+			throw new Error('Delivery may only be deferred for an owned, undelivered task')
+		}
+		if (this.deliveryGates.has(taskId)) {
+			throw new Error('This task already has a delivery settlement')
+		}
+		const gate: {
+			settled: Promise<void>
+			state: 'pending' | 'ready' | 'failed'
+			error?: unknown
+		} = { settled: Promise.resolve(), state: 'pending' }
+		gate.settled = settlement
+			.then(
+				() => {
+					gate.state = 'ready'
+				},
+				(error: unknown) => {
+					gate.state = 'failed'
+					gate.error = error
+				},
+			)
+			.then(() => {
+				if (this.deliveryGates.get(taskId) === gate && this.unheard.has(taskId)) {
+					for (const wake of [...this.arrivals]) wake()
+					// A known tracking failure must not wait behind another row's
+					// stalled write. Drains report it without consuming any result.
+					if (gate.state === 'failed') for (const finish of [...this.drains]) finish()
+				}
+			})
+		this.deliveryGates.set(taskId, gate)
+	}
+
 	/**
 	 * Move an owned task from {@link runningOwned} to {@link settledOwned}.
 	 *
@@ -308,8 +359,8 @@ export class CompletionInbox {
 	 */
 	waitForArrival(timeoutMs: number, signal?: AbortSignal): Promise<void> {
 		if (signal?.aborted) return Promise.resolve()
-		if (this.unheard.size > 0) return Promise.resolve()
-		if (this.outstanding.size === 0) return Promise.resolve()
+		if (this.hasUnheard) return Promise.resolve()
+		if (!this.hasPendingWork) return Promise.resolve()
 
 		return new Promise((resolve) => {
 			const finish = (): void => {
@@ -338,6 +389,7 @@ export class CompletionInbox {
 	claim(taskId: TaskId): void {
 		this.claimed.add(taskId)
 		this.unheard.delete(taskId)
+		this.deliveryGates.delete(taskId)
 		this.outstanding.delete(taskId)
 		// A tool only claims a result it is already holding, so a claim is
 		// itself proof of settlement — independent of whether the gateway's
@@ -350,7 +402,9 @@ export class CompletionInbox {
 
 	/** Whether anything is waiting to be told. */
 	get hasUnheard(): boolean {
-		return this.unheard.size > 0
+		return [...this.unheard.keys()].some(
+			(taskId) => this.deliveryGates.get(taskId)?.state !== 'pending',
+		)
 	}
 
 	/**
@@ -410,16 +464,22 @@ export class CompletionInbox {
 	}
 
 	/**
-	 * Take every unheard completion, leaving the inbox empty.
+	 * Take unheard completions whose tracking settlement has succeeded.
+	 * Pending gates stay queued; a rejected gate throws without consuming any
+	 * result. Use `drainAsync` to await tracking for results already in hand.
 	 *
 	 * Draining rather than peeking: a notification that stays queued after
 	 * being delivered is the duplicate-delivery bug in a different costume.
 	 */
 	drain(): TaskHandle[] {
 		if (this.unheard.size === 0) return []
-		const handles = [...this.unheard.values()]
-		this.unheard.clear()
+		this.checkDeliveryFailures()
+		const handles = [...this.unheard.values()].filter(
+			(handle) => this.deliveryGates.get(handle.taskId)?.state !== 'pending',
+		)
 		for (const handle of handles) {
+			this.unheard.delete(handle.taskId)
+			this.deliveryGates.delete(handle.taskId)
 			this.claimed.add(handle.taskId)
 			// A delivered result is not pending WORK, and `outstanding` can
 			// still be holding this id — the listener clears it, but only if
@@ -438,6 +498,43 @@ export class CompletionInbox {
 		return handles
 	}
 
+	private checkDeliveryFailures(): void {
+		for (const taskId of this.unheard.keys()) {
+			const gate = this.deliveryGates.get(taskId)
+			if (gate?.state === 'failed') throw gate.error
+		}
+	}
+
+	/**
+	 * Await tracking for completions already queued, then deliver once.
+	 * Running workers are never awaited here. Concurrent drains share gates
+	 * and the existing claim set, so only one consumer receives each result.
+	 * Aborting releases only this wait and returns no results; tracking and
+	 * queued completions remain available for a later drain.
+	 */
+	async drainAsync(signal?: AbortSignal): Promise<TaskHandle[]> {
+		const lifecycle = this.lifecycle
+		if (signal?.aborted) return []
+		this.checkDeliveryFailures()
+		const settlements = [...this.unheard.keys()].flatMap((taskId) => {
+			const gate = this.deliveryGates.get(taskId)
+			return gate ? [gate.settled] : []
+		})
+		if (settlements.length === 0) return this.drain()
+		await new Promise<void>((resolve) => {
+			const finish = (): void => {
+				signal?.removeEventListener('abort', finish)
+				this.drains.delete(finish)
+				resolve()
+			}
+			this.drains.add(finish)
+			signal?.addEventListener('abort', finish, { once: true })
+			void Promise.all(settlements).then(finish)
+			if (signal?.aborted) finish()
+		})
+		return signal?.aborted || lifecycle !== this.lifecycle ? [] : this.drain()
+	}
+
 	/**
 	 * Stop expecting a task that is never going to arrive.
 	 *
@@ -480,10 +577,12 @@ export class CompletionInbox {
 	 * stops it existing.
 	 */
 	close(): void {
+		this.lifecycle++
 		this.detach?.()
 		this.detach = undefined
 		this.gateway = undefined
 		this.unheard.clear()
+		this.deliveryGates.clear()
 		this.outstanding.clear()
 		this.ours.clear()
 		this.runningOwned.clear()
@@ -494,6 +593,8 @@ export class CompletionInbox {
 		// them to their own deadline for a completion that can no longer come.
 		for (const wake of [...this.arrivals]) wake()
 		this.arrivals.clear()
+		for (const finish of [...this.drains]) finish()
+		this.drains.clear()
 	}
 }
 

package/src/scheduler/delegating.ts

@@ -171,6 +171,11 @@ export class DelegatingTaskScheduler implements TaskScheduler {
 			if (!this.config.local) throw new NoDelegateError({ agentId: options.agentId })
 			return await this.config.local.createTask(options)
 		}
+		if (options.resumeSessionId)
+			throw new DelegateCapabilityError({
+				id: delegate.id,
+				capability: 'child conversation continuation',
+			})
 
 		if (this.budget) {
 			throw new Error(

package/src/scheduler/local.ts

@@ -112,6 +112,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 		const task = await this.agentManager.sendMessage(
 			{
 				agentId: options.agentId,
+				...(options.resumeSessionId ? { resumeSessionId: options.resumeSessionId } : {}),
 				beforeStart: options.beforeStart,
 				...(options.workspace ? { workspace: options.workspace } : {}),
 				...(options.planId ? { planId: options.planId } : {}),
@@ -469,6 +470,7 @@ function toHandle(task: import('../types/agent/task.js').AgentTask): TaskHandle
 		result: task.result,
 		createdAt: task.createdAt,
 		completedAt: task.completedAt,
+		...(task.childSessionId ? { childSessionId: task.childSessionId } : {}),
 		...(task.workspace ? { workspace: task.workspace } : {}),
 	}
 }

package/src/session/summary/materialize.ts

@@ -18,7 +18,7 @@
  * `generateSummaryId` from `utils/id.ts`.
  */
 
-import type { SessionId, TenantId } from '../../types/ids/index.js'
+import type { SessionId, TenantId, TurnId } from '../../types/ids/index.js'
 import type { Session } from '../../types/session/entity.js'
 import type { SummaryId } from '../../types/session/ids.js'
 import type { SessionStore } from '../../types/session/store.js'
@@ -29,6 +29,7 @@ import {
 	type SessionSummaryOutcome,
 	type SessionSummaryRef,
 } from '../../types/summary/ref.js'
+import { StaleSessionError } from '../errors.js'
 import { AgentSummaryTooLongError, SessionAlreadySummarizedError } from './errors.js'
 
 /**
@@ -50,6 +51,10 @@ export interface SessionSummaryMaterializerDeps {
  */
 export interface MaterializeInput {
 	readonly sessionId: SessionId
+	/** Seal this invocation independently of the legacy conversation summary. */
+	readonly turnId?: TurnId
+	/** Keep this terminalization attributed to the admitted owner, if supplied. */
+	readonly expectedOwnerVersion?: number
 	readonly tenantId: TenantId
 	readonly finalOutcome: SessionSummaryOutcome
 	readonly agentSummary: string
@@ -84,19 +89,31 @@ export class SessionSummaryMaterializer {
 	 * - {@link AgentSummaryTooLongError} — `agentSummary` exceeds the max char
 	 *   cap ({@link AGENT_SUMMARY_MAX_CHARS}).
 	 * - `TenantIsolationError` — session is owned by a different tenant.
-	 * - {@link SessionAlreadySummarizedError} — the session already has a
-	 *   persisted summary. Re-materialization would duplicate history; the
-	 *   caller should instead open an intervention sub-session (§4.5).
+	 * - {@link SessionAlreadySummarizedError} — this conversation-summary key
+	 *   or explicit invocation key already has a sealed summary. A new child
+	 *   invocation uses its fresh `turnId`; it never replaces the old summary.
 	 */
 	async materialize(input: MaterializeInput): Promise<SessionSummaryRef> {
 		this.assertSummaryLength(input.agentSummary)
+		if (input.turnId && this.deps.store.supportsInvocationSummaries !== true)
+			throw new Error('Session store does not support invocation summaries')
 
 		const session = await this.deps.store.getSession(input.sessionId, input.tenantId)
 		if (!session) {
 			throw new Error(`Session ${input.sessionId} not found`)
 		}
+		if (input.expectedOwnerVersion !== undefined) {
+			if (this.deps.store.supportsOwnerVersionCas !== true)
+				throw new Error('Session store does not support owner-version CAS')
+			if (session.ownerVersion !== input.expectedOwnerVersion)
+				throw new StaleSessionError({
+					sessionId: input.sessionId,
+					expectedVersion: input.expectedOwnerVersion,
+					actualVersion: session.ownerVersion,
+				})
+		}
 
-		const existing = await this.deps.store.getSummary(input.sessionId, input.tenantId)
+		const existing = await this.deps.store.getSummary(input.sessionId, input.tenantId, input.turnId)
 		if (existing) {
 			throw new SessionAlreadySummarizedError({
 				sessionId: input.sessionId,
@@ -107,6 +124,7 @@ export class SessionSummaryMaterializer {
 		const summary: SessionSummaryRef = {
 			id: this.deps.generateSummaryId(),
 			sessionRef: input.sessionId,
+			...(input.turnId ? { turnRef: input.turnId } : {}),
 			tenantId: input.tenantId,
 			outcome: input.finalOutcome,
 			deliverables: input.declaredDeliverables,
@@ -116,13 +134,29 @@ export class SessionSummaryMaterializer {
 			materializedBy: 'kernel',
 		}
 
-		await this.deps.store.recordSummary(summary, input.tenantId)
+		const legacy = input.turnId
+			? await this.deps.store.getSummary(input.sessionId, input.tenantId)
+			: undefined
+		if (input.expectedOwnerVersion === undefined)
+			await this.deps.store.recordSummary(summary, input.tenantId)
+		else await this.deps.store.recordSummary(summary, input.tenantId, input.expectedOwnerVersion)
+		if (input.turnId) {
+			const stored = await this.deps.store.getSummary(input.sessionId, input.tenantId, input.turnId)
+			const afterLegacy = await this.deps.store.getSummary(input.sessionId, input.tenantId)
+			if (
+				stored?.id !== summary.id ||
+				stored.sessionRef !== input.sessionId ||
+				stored.turnRef !== input.turnId ||
+				afterLegacy?.id !== legacy?.id
+			)
+				throw new Error('Session store did not preserve the invocation summary contract')
+		}
 		return summary
 	}
 
 	/**
 	 * Recovery path. Called at boot (or explicitly by the lifecycle manager)
-	 * for sessions whose `summary.json` is persisted but whose `session.json`
+	 * for sessions whose selected summary is persisted but whose `session.json`
 	 * still reports a non-terminal status — the crash window between the two
 	 * atomic writes on disk.
 	 *
@@ -133,9 +167,17 @@ export class SessionSummaryMaterializer {
 	 * mint a new ID, only re-triggers the store's status flip via
 	 * `recordSummary` when it detects the dangling session.
 	 */
-	async recover(sessionId: SessionId, tenantId: TenantId): Promise<SessionSummaryRef | null> {
-		const summary = await this.deps.store.getSummary(sessionId, tenantId)
+	async recover(
+		sessionId: SessionId,
+		tenantId: TenantId,
+		turnId?: TurnId,
+	): Promise<SessionSummaryRef | null> {
+		if (turnId && this.deps.store.supportsInvocationSummaries !== true)
+			throw new Error('Session store does not support invocation summaries')
+		const summary = await this.deps.store.getSummary(sessionId, tenantId, turnId)
 		if (!summary) return null
+		if (turnId && (summary.turnRef !== turnId || summary.sessionRef !== sessionId))
+			throw new Error('Session store returned a different invocation summary')
 
 		const session = await this.deps.store.getSession(sessionId, tenantId)
 		if (!session) return summary

package/src/store/budget/ledger.ts

@@ -434,7 +434,7 @@ export class SessionTokenBudget {
 		persistence?: SessionTokenBudgetPersistence,
 	): SessionTokenBudget {
 		const state = validateSessionTokenBudgetSnapshot(snapshot)
-		return new SessionTokenBudget(
+		const restored = new SessionTokenBudget(
 			{
 				rootAccountId: state.rootAccountId,
 				scope: { rootSessionId: state.rootSessionId, rootTurnId: state.rootTurnId },
@@ -449,6 +449,27 @@ export class SessionTokenBudget {
 			},
 			state.rootAccountId,
 		)
+		// A request that was in flight when a process stopped has no receipt. On an
+		// unbounded account it stays recorded as unknown spend, but it no longer
+		// counts as work in progress, so the turn can ask again.
+		for (const request of [...restored.ledger.requests.values()]) {
+			if (!restored.account(request.accountId).bounded) restored.retainUnresolved(request)
+		}
+		return restored
+	}
+
+	/**
+	 * Whether this account, or any account above it, carries a finite limit. A bounded
+	 * account cannot be admitted past unknown spend, because the unknown amount may
+	 * already exceed the limit. An unbounded one has no limit to exceed: its unknown
+	 * spend stays recorded (never as zero) and does not stop the next request.
+	 */
+	get bounded(): boolean {
+		for (let cursor: SessionTokenBudgetAccountSnapshot | undefined = this.node; cursor; ) {
+			if (cursor.limit > 0) return true
+			cursor = cursor.parentId === undefined ? undefined : this.requireAccount(cursor.parentId)
+		}
+		return false
 	}
 
 	get limit(): number {
@@ -590,7 +611,16 @@ export class SessionTokenBudget {
 	}
 
 	async finishRequest(requestId: string, usage: TokenUsage): Promise<void> {
-		if (this.hasReceipt(requestId)) return this.flush()
+		if (this.hasReceipt(requestId)) {
+			// A request retained as unknown spend can still be answered late. The
+			// measured usage is evidence and is kept; the unknown marker stays until
+			// an explicit reconciliation clears it.
+			const receipt = this.ledger.finishedRequests.get(
+				requestId,
+			) as SessionTokenBudgetRequestSnapshot
+			if (receipt.unresolved === true) return this.failRequest(requestId, usage)
+			return this.flush()
+		}
 		const request = this.requireRequest(requestId)
 		try {
 			this.recordRequestUsage(request, usage)
@@ -608,7 +638,25 @@ export class SessionTokenBudget {
 
 	/** Unknown spend cannot be converted into a refund, even after cancellation. */
 	async failRequest(requestId: string, usage?: TokenUsage): Promise<void> {
-		if (this.hasReceipt(requestId)) return this.flush()
+		if (this.hasReceipt(requestId)) {
+			// An unbounded account retains a failed request as a receipt; usage that
+			// arrives late is still evidence of spend and is kept.
+			const receipt = this.ledger.finishedRequests.get(
+				requestId,
+			) as SessionTokenBudgetRequestSnapshot
+			if (usage !== undefined && receipt.unresolved === true) {
+				try {
+					this.recordRequestUsage(receipt, usage)
+				} catch (error) {
+					this.ledger.poisoned = true
+					this.persist()
+					await this.flush()
+					throw error
+				}
+				this.persist()
+			}
+			return this.flush()
+		}
 		const request = this.requireRequest(requestId)
 		request.unresolved = true
 		try {
@@ -619,6 +667,7 @@ export class SessionTokenBudget {
 			await this.flush()
 			throw error
 		}
+		if (!this.bounded) this.retainUnresolved(request)
 		this.persist()
 		await this.flush()
 	}
@@ -713,6 +762,12 @@ export class SessionTokenBudget {
 		if (this.ledger.persistenceError !== undefined) throw this.ledger.persistenceError
 	}
 
+	/** Move a request with no receipt out of flight, keeping its unknown-spend marker. */
+	private retainUnresolved(request: SessionTokenBudgetRequestSnapshot): void {
+		request.unresolved = true
+		this.ledger.requests.delete(request.id)
+		this.ledger.finishedRequests.set(request.id, request)
+	}
 	private uncertainRequests(): SessionTokenBudgetRequestSnapshot[] {
 		return [...this.ledger.requests.values(), ...this.ledger.finishedRequests.values()].filter(
 			(request) => request.unresolved === true,
@@ -722,8 +777,8 @@ export class SessionTokenBudget {
 		if (this.ledger.poisoned || this.ledger.persistenceError !== undefined) return true
 		const uncertain = this.uncertainRequests()
 		if (uncertain.length === 0) return false
-		// An account cannot resume its own uncertain request, even without a cap.
-		if (uncertain.some((request) => request.accountId === this.accountId)) return true
+		// Unknown spend blocks only through a finite limit at or above this account,
+		// where it could already have been exceeded; see `bounded`.
 		let cursor = this.node
 		for (;;) {
 			if (cursor.limit > 0) {

package/src/store/session/disk.ts

@@ -36,7 +36,7 @@
 
 import { createHash } from 'node:crypto'
 import { mkdir, rm } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import {
 	ProjectRootPathTakenError,
 	StaleProjectError,
@@ -44,7 +44,7 @@ import {
 	TenantIsolationError,
 } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
-import type { SessionId, TenantId } from '../../types/ids/index.js'
+import type { SessionId, TenantId, TurnId } from '../../types/ids/index.js'
 import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { Session } from '../../types/session/entity.js'
 import type { ProjectId, SubSessionId, SummaryId, TopicId } from '../../types/session/ids.js'
@@ -68,6 +68,7 @@ import {
 	asSessionId,
 	asSubSessionId,
 	asTopicId,
+	asTurnId,
 	generateProjectId,
 	generateSessionId,
 	generateSubSessionId,
@@ -237,6 +238,7 @@ interface PersistedSubSession {
 interface PersistedSummary {
 	id: SummaryId
 	sessionRef: SessionId
+	turnRef?: TurnId
 	tenantId: TenantId
 	outcome: SessionSummaryOutcome
 	deliverables: readonly DeliverableRef[]
@@ -257,6 +259,10 @@ const SUMMARY_TERMINAL_FLIP_STATUSES: ReadonlySet<Session['status']> = new Set([
 	'awaiting_merge',
 ])
 
+// Share the in-process writer guard across store instances addressing the same
+// root. This is not a cross-process lease; external writers remain a host concern.
+const sessionWriters = new Map<string, Promise<void>>()
+
 /**
  * Index of projectId → its directory path. Built lazily on lookup via
  * {@link DiskSessionStore.resolveProjectDir}; populated by create / getProject.
@@ -276,6 +282,8 @@ interface SessionIndexEntry {
 }
 
 export class DiskSessionStore implements SessionStore {
+	readonly supportsInvocationSummaries: boolean = true
+	readonly supportsOwnerVersionCas: boolean = true
 	private readonly rootDir: string
 	private readonly projectIndex = new Map<ProjectId, ProjectIndexEntry>()
 	private readonly sessionIndex = new Map<SessionId, SessionIndexEntry>()
@@ -288,6 +296,24 @@ export class DiskSessionStore implements SessionStore {
 		this.rootDir = config.rootDir
 	}
 
+	private async withSessionWrite<T>(sessionId: SessionId, operation: () => Promise<T>): Promise<T> {
+		const key = resolve(this.rootDir, sessionId)
+		const previous = sessionWriters.get(key) ?? Promise.resolve()
+		let release = () => {}
+		const held = new Promise<void>((resolveWrite) => {
+			release = resolveWrite
+		})
+		const tail = previous.then(() => held)
+		sessionWriters.set(key, tail)
+		await previous
+		try {
+			return await operation()
+		} finally {
+			release()
+			if (sessionWriters.get(key) === tail) sessionWriters.delete(key)
+		}
+	}
+
 	// Project CRUD ------------------------------------------------------------
 
 	async createProject(params: CreateProjectParams, tenantId: TenantId): Promise<Project> {
@@ -654,6 +680,16 @@ export class DiskSessionStore implements SessionStore {
 		session: Session,
 		tenantId: TenantId,
 		expectedOwnerVersion?: number,
+	): Promise<void> {
+		await this.withSessionWrite(session.id, () =>
+			this.updateSessionUnlocked(session, tenantId, expectedOwnerVersion),
+		)
+	}
+
+	private async updateSessionUnlocked(
+		session: Session,
+		tenantId: TenantId,
+		expectedOwnerVersion?: number,
 	): Promise<void> {
 		const located = await this.locateSession(session.id)
 		if (!located) {
@@ -669,10 +705,8 @@ export class DiskSessionStore implements SessionStore {
 		if (existing) {
 			this.assertTenant(existing.tenantId, tenantId, `session(${session.id})`)
 		}
-		// Against what is on disk, not against the payload. The write itself is
-		// atomic; this read-compare-write is NOT a critical section, so two
-		// processes can still both pass — see the contract note on
-		// `SessionStore.updateSession`. In one process it is the real lock.
+		// Against the stored version, under the shared in-process writer guard.
+		// Other processes can still both pass; see SessionStore.updateSession.
 		if (
 			expectedOwnerVersion !== undefined &&
 			existing !== null &&
@@ -862,11 +896,22 @@ export class DiskSessionStore implements SessionStore {
 	 * leaves summary present + session still non-terminal — recovery replays
 	 * the flip via {@link SessionSummaryMaterializer.recover}. Idempotent when
 	 * the same summary is re-presented (recovery path); rejects a *different*
-	 * summary for the same session as {@link SessionAlreadySummarizedError}.
+	 * summary at the same conversation or invocation key as {@link SessionAlreadySummarizedError}.
 	 */
 	async recordSummary(
 		summary: SessionSummaryRef & { materializedBy: 'kernel' },
 		tenantId: TenantId,
+		expectedOwnerVersion?: number,
+	): Promise<void> {
+		await this.withSessionWrite(summary.sessionRef, () =>
+			this.recordSummaryUnlocked(summary, tenantId, expectedOwnerVersion),
+		)
+	}
+
+	private async recordSummaryUnlocked(
+		summary: SessionSummaryRef & { materializedBy: 'kernel' },
+		tenantId: TenantId,
+		expectedOwnerVersion?: number,
 	): Promise<void> {
 		if (summary.tenantId !== tenantId) {
 			throw new TenantIsolationError({
@@ -884,8 +929,15 @@ export class DiskSessionStore implements SessionStore {
 			throw new Error(`Session ${summary.sessionRef} not found on disk`)
 		}
 		this.assertTenant(sessionRaw.tenantId, tenantId, `session(${summary.sessionRef})`)
+		if (expectedOwnerVersion !== undefined && sessionRaw.ownerVersion !== expectedOwnerVersion) {
+			throw new StaleSessionError({
+				sessionId: summary.sessionRef,
+				expectedVersion: expectedOwnerVersion,
+				actualVersion: sessionRaw.ownerVersion,
+			})
+		}
 
-		const summaryPath = join(located.path, 'summary.json')
+		const summaryPath = summaryFile(located.path, summary.turnRef)
 		const existingRaw = await records.read<PersistedSummary>(summaryPath)
 		if (existingRaw) {
 			this.assertTenant(existingRaw.tenantId, tenantId, `summary(${existingRaw.id})`)
@@ -899,6 +951,8 @@ export class DiskSessionStore implements SessionStore {
 			// to the status flip so crash-between-writes is recovered.
 		} else {
 			// Step 1: persist summary.
+			if (summary.turnRef)
+				await mkdir(join(located.path, 'turn-summaries'), { recursive: true, mode: 0o700 })
 			await records.write(summaryPath, serializeSummary(summary))
 		}
 
@@ -913,10 +967,15 @@ export class DiskSessionStore implements SessionStore {
 		}
 	}
 
-	async getSummary(sessionId: SessionId, tenantId: TenantId): Promise<SessionSummaryRef | null> {
+	async getSummary(
+		sessionId: SessionId,
+		tenantId: TenantId,
+		turnId?: TurnId,
+	): Promise<SessionSummaryRef | null> {
+		if (turnId !== undefined) asTurnId(turnId)
 		const located = await this.locateSession(sessionId)
 		if (!located) return null
-		const raw = await records.read<PersistedSummary>(join(located.path, 'summary.json'))
+		const raw = await records.read<PersistedSummary>(summaryFile(located.path, turnId))
 		if (!raw) return null
 		this.assertTenant(raw.tenantId, tenantId, `summary(${raw.id})`)
 		return deserializeSummary(raw)
@@ -1161,6 +1220,7 @@ function serializeSummary(s: SessionSummaryRef): PersistedSummary {
 	return {
 		id: s.id,
 		sessionRef: s.sessionRef,
+		...(s.turnRef ? { turnRef: s.turnRef } : {}),
 		tenantId: s.tenantId,
 		outcome: s.outcome,
 		deliverables: s.deliverables,
@@ -1182,6 +1242,7 @@ function deserializeSummary(s: PersistedSummary): SessionSummaryRef {
 	return {
 		id: s.id,
 		sessionRef: s.sessionRef,
+		...(s.turnRef ? { turnRef: asTurnId(s.turnRef) } : {}),
 		tenantId: s.tenantId,
 		outcome: s.outcome,
 		deliverables: s.deliverables,
@@ -1191,3 +1252,9 @@ function deserializeSummary(s: PersistedSummary): SessionSummaryRef {
 		materializedBy: 'kernel',
 	}
 }
+
+function summaryFile(directory: string, turnId?: TurnId): string {
+	return turnId === undefined
+		? join(directory, 'summary.json')
+		: join(directory, 'turn-summaries', `${asTurnId(turnId)}.json`)
+}