@namzu/sdk 0.1.8 → 0.3.0

package/src/session/handoff/single.ts

@@ -0,0 +1,310 @@
+/**
+ * Single-recipient handoff flow — `idle → locked → CAS → commit | revert`.
+ *
+ * See session-hierarchy.md §6.1 (single-recipient flow) and §6.4 (concurrent
+ * CAS). Function-based per Convention #9 — dependencies arrive as an
+ * explicit `deps` envelope so tests can inject mocks and production code
+ * composes flows without a class hierarchy.
+ *
+ * Flow (pattern doc §5.1 + §6.1):
+ *   1. Load source session; verify tenant.
+ *   2. Check status (must be `idle`); no non-terminal Runs.
+ *   3. Validate capacity (depth + width).
+ *   4. Transition source `idle → locked` with CAS on `ownerVersion`.
+ *   5. Emit `onLocked`.
+ *   6. Spawn recipient sub-session + provision isolated workspace.
+ *   7. On any step 6 failure: compensating revert (`locked → idle`, version
+ *      unchanged, dispose any partial worktree), emit `onUnlocked`, rethrow.
+ *   8. On success: commit `locked → idle` with updated `currentActor` +
+ *      appended `previousActors` + bumped `ownerVersion`.
+ *   9. Emit `onCommitted` with the new version.
+ */
+
+import type { ThreadManager } from '../../manager/thread/lifecycle.js'
+import type { SessionId, TenantId } from '../../types/ids/index.js'
+import type { SessionStore } from '../../types/session/store.js'
+import { TenantIsolationError } from '../errors.js'
+import type { Session } from '../hierarchy/session.js'
+import type { WorkspaceBackendDriver } from '../workspace/driver.js'
+import type { WorkspaceRef } from '../workspace/ref.js'
+import type { WorkspaceBackendRegistry } from '../workspace/registry.js'
+import type { HandoffAssignment, HandoffOutcome } from './assignment.js'
+import type { CapacityValidator } from './capacity.js'
+import type { HandoffEventSink } from './events.js'
+import { HandoffLockRejected, HandoffVersionConflict } from './version.js'
+
+/**
+ * Minimal surface the handoff flow queries for Run fan-in status. A Run is
+ * considered "blocking" if it is in any non-terminal status that prevents the
+ * source session from transitioning to `locked` (session-hierarchy.md §5.1).
+ *
+ * The flow injects the resolver so Phase 4 stays decoupled from Phase 6's
+ * Run persistence refactor. Production wires the real Run store; tests stub.
+ */
+export interface RunStatusResolver {
+	/**
+	 * Returns the reason the session has a non-terminal Run, or `null` when
+	 * all Runs are terminal and the lock is allowed.
+	 */
+	blockingRun(
+		sessionId: SessionId,
+		tenantId: TenantId,
+	): Promise<{ reason: 'active_run' | 'pending_hitl' | 'pending_subsession' } | null>
+}
+
+/** Null resolver — treats every session as unblocked. Used by tests that do not exercise Run fan-in. */
+export const NOOP_RUN_STATUS_RESOLVER: RunStatusResolver = {
+	async blockingRun(): Promise<null> {
+		return null
+	},
+}
+
+export interface SingleHandoffDeps {
+	store: SessionStore
+	workspaceRegistry: WorkspaceBackendRegistry
+	capacity: CapacityValidator
+	events: HandoffEventSink
+	runStatus?: RunStatusResolver
+	/**
+	 * Gate the recipient-session creation on the Thread being `'open'`.
+	 * Added in Phase 2.6 to mirror spawn — a handoff into an archived
+	 * Thread would otherwise undermine `ThreadManager.archive`.
+	 */
+	threadManager: ThreadManager
+}
+
+/**
+ * Executes a single-recipient handoff against `deps.store`. Throws
+ * {@link HandoffLockRejected}, {@link HandoffVersionConflict},
+ * {@link TenantIsolationError}, or {@link DelegationCapacityExceeded} on
+ * invariant violations. Workspace provisioning failures surface as
+ * {@link WorkspaceBackendError} after the compensating revert.
+ */
+export async function executeSingleHandoff(
+	deps: SingleHandoffDeps,
+	assignment: HandoffAssignment,
+	tenantId: TenantId,
+): Promise<HandoffOutcome> {
+	if (assignment.tenantId !== tenantId) {
+		throw new TenantIsolationError({
+			requested: tenantId,
+			resource: `handoff-assignment(${assignment.id})`,
+		})
+	}
+
+	// Thread archive gate (Phase 2.6) — runs FIRST so an archived thread
+	// fails fastest with `ThreadClosedError` rather than a lock rejection or
+	// capacity error. Checked BEFORE the CAS lock so a denied handoff leaves
+	// the source session untouched.
+	await deps.threadManager.requireOpen(assignment.threadId, tenantId)
+
+	// 1. Load source session + tenant check.
+	const source = await deps.store.getSession(assignment.sourceSessionId, tenantId)
+	if (!source) {
+		throw new Error(`Source session ${assignment.sourceSessionId} not found`)
+	}
+	if (source.tenantId !== tenantId) {
+		throw new TenantIsolationError({
+			requested: tenantId,
+			resource: `session(${source.id})`,
+		})
+	}
+	if (source.threadId !== assignment.threadId) {
+		throw new Error(
+			`Assignment threadId ${assignment.threadId} does not match source session threadId ${source.threadId}`,
+		)
+	}
+	if (source.projectId !== assignment.projectId) {
+		throw new Error(
+			`Assignment projectId ${assignment.projectId} does not match source session projectId ${source.projectId}`,
+		)
+	}
+
+	// 2. Status check — only `idle` sessions may lock. `active`, `awaiting_hitl`,
+	//    `awaiting_merge`, `locked`, `failed`, `archived` all reject.
+	if (source.status !== 'idle') {
+		throw new HandoffLockRejected({
+			sessionId: source.id,
+			reason: statusToLockReason(source.status),
+		})
+	}
+
+	// 3. Non-terminal Run fan-in (§5.1).
+	const runResolver = deps.runStatus ?? NOOP_RUN_STATUS_RESOLVER
+	const blocking = await runResolver.blockingRun(source.id, tenantId)
+	if (blocking) {
+		throw new HandoffLockRejected({
+			sessionId: source.id,
+			reason: blocking.reason,
+		})
+	}
+
+	// 4. Capacity — depth (new child depth = parent ancestry length + 1) and
+	//    width (one new child under the source's *parent* would change — but
+	//    single handoff does NOT create a child under the source; it transfers
+	//    ownership of the same session. Width only applies to broadcast).
+	//    For `single` we still validate depth to future-proof should the flow
+	//    evolve into a branch variant.
+	const project = await deps.store.getProject(source.projectId, tenantId)
+	if (!project) {
+		throw new Error(`Project ${source.projectId} not found`)
+	}
+	await deps.capacity.validateDepth(source.id, project.config.maxDelegationDepth, tenantId)
+
+	// 5. CAS → `idle → locked`.
+	if (source.ownerVersion !== assignment.expectedOwnerVersion) {
+		throw new HandoffVersionConflict({
+			sessionId: source.id,
+			expected: assignment.expectedOwnerVersion,
+			actual: source.ownerVersion,
+		})
+	}
+
+	const locked: Session = {
+		...source,
+		status: 'locked',
+	}
+	await deps.store.updateSession(locked, tenantId)
+	emit(deps.events.onLocked, { sessionId: source.id, at: new Date() })
+
+	// 6. Provision recipient resources. Track partial state for rollback.
+	let provisionedWorkspace: WorkspaceRef | null = null
+	let createdSessionId: SessionId | null = null
+	try {
+		const driver: WorkspaceBackendDriver = deps.workspaceRegistry.get('git-worktree')
+		provisionedWorkspace = await driver.create({ label: `handoff-${assignment.id}` })
+
+		const recipientSession = await deps.store.createSession(
+			{
+				threadId: source.threadId,
+				projectId: source.projectId,
+				currentActor: assignment.recipientActor,
+			},
+			tenantId,
+		)
+		createdSessionId = recipientSession.id
+
+		await deps.store.createSubSession(
+			{
+				parentSessionId: source.id,
+				childSessionId: recipientSession.id,
+				kind: 'user_handoff',
+				spawnedBy: assignment.sourceActor,
+			},
+			tenantId,
+		)
+
+		// 7. Commit source: `locked → idle` with appended actor + bumped version.
+		//    The source transitions ownership to the recipient — the previous
+		//    owner is permanently read-only (§6.1).
+		const committed: Session = {
+			...source,
+			status: 'idle',
+			currentActor: assignment.recipientActor,
+			previousActors: source.currentActor
+				? [...source.previousActors, source.currentActor]
+				: [...source.previousActors],
+			ownerVersion: source.ownerVersion + 1,
+		}
+		await deps.store.updateSession(committed, tenantId)
+
+		emit(deps.events.onCommitted, {
+			sessionId: source.id,
+			newVersion: committed.ownerVersion,
+			handoffIds: [assignment.id],
+			at: new Date(),
+		})
+
+		return {
+			assignmentId: assignment.id,
+			newSessionId: recipientSession.id,
+			workspaceId: provisionedWorkspace.id,
+			committedOwnerVersion: committed.ownerVersion,
+		}
+	} catch (failure) {
+		// Compensating revert — idempotent. Every step tolerates prior success.
+		await revertLock(deps, source, provisionedWorkspace, createdSessionId, tenantId)
+		throw failure
+	}
+}
+
+/**
+ * Reverts a source session from `locked` back to `idle` preserving
+ * `ownerVersion`, disposes any provisioned worktree, and emits `onUnlocked`.
+ *
+ * **Idempotent.** Every sub-op tolerates being called against already-released
+ * state:
+ *   - `updateSession` replays the same payload — last-write-wins (Phase 3
+ *     store uses write-tmp-rename).
+ *   - `dispose` on a missing worktree is a no-op by contract
+ *     (`driver.ts#dispose` + `git-worktree.ts` regex for "not a working tree").
+ */
+async function revertLock(
+	deps: SingleHandoffDeps,
+	source: Session,
+	workspace: WorkspaceRef | null,
+	createdSessionId: SessionId | null,
+	tenantId: TenantId,
+): Promise<void> {
+	const reverted: Session = { ...source, status: 'idle' }
+	try {
+		await deps.store.updateSession(reverted, tenantId)
+	} catch {
+		// Swallow — the flow is already unwinding a primary failure; surfacing
+		// secondary errors would mask root cause. Idempotent per Risk #3.
+	}
+
+	if (workspace) {
+		try {
+			const driver = deps.workspaceRegistry.get('git-worktree')
+			await driver.dispose(workspace)
+		} catch {
+			// Idempotent rollback per Risk #3 — dispose is already tolerant of
+			// missing worktrees, but we still guard the registry lookup path.
+		}
+	}
+
+	if (createdSessionId) {
+		// No `deleteSession` in the Phase 3 store surface — mark the partially
+		// created recipient session as `archived` so it is inert. A later phase
+		// introduces explicit deletion; until then this is the cleanest
+		// compensator that does not add surface area.
+		try {
+			const recipient = await deps.store.getSession(createdSessionId, tenantId)
+			if (recipient) {
+				await deps.store.updateSession({ ...recipient, status: 'archived' }, tenantId)
+			}
+		} catch {
+			// Same rationale as above.
+		}
+	}
+
+	emit(deps.events.onUnlocked, { sessionId: source.id, at: new Date() })
+}
+
+function statusToLockReason(
+	status: Session['status'],
+): 'active_run' | 'pending_hitl' | 'pending_subsession' {
+	switch (status) {
+		case 'active':
+			return 'active_run'
+		case 'awaiting_hitl':
+			return 'pending_hitl'
+		case 'awaiting_merge':
+			return 'pending_subsession'
+		case 'locked':
+			return 'active_run'
+		case 'failed':
+			return 'active_run'
+		case 'archived':
+			return 'active_run'
+		case 'idle':
+			// Unreachable — caller guards. Keep a sentinel value so exhaustiveness
+			// does not force an `assert never` export from this module.
+			return 'active_run'
+	}
+}
+
+function emit<T>(handler: ((ev: T) => void) | undefined, event: T): void {
+	if (handler) handler(event)
+}

package/src/session/handoff/version.ts

@@ -0,0 +1,59 @@
+/**
+ * Typed errors for the handoff state machine.
+ *
+ * See session-hierarchy.md §5.1 (illegal `active → locked` transition) and
+ * §6.4 (concurrent CAS). Both classes carry structured `details` so consumers
+ * can route without string parsing (Convention #5: deny-by-default, fail
+ * fast).
+ */
+
+import type { RunId, SessionId } from '../../types/ids/index.js'
+
+/**
+ * Raised when a handoff's CAS write finds {@link Session.ownerVersion} has
+ * advanced since the assignment was constructed — another actor committed
+ * first (session-hierarchy.md §6.4 concurrent CAS). The caller re-reads and
+ * decides whether to retry.
+ */
+export class HandoffVersionConflict extends Error {
+	readonly details: {
+		sessionId: SessionId
+		expected: number
+		actual: number
+	}
+
+	constructor(details: { sessionId: SessionId; expected: number; actual: number }) {
+		super(
+			`Handoff version conflict on ${details.sessionId}: expected ${details.expected}, actual ${details.actual}`,
+		)
+		this.name = 'HandoffVersionConflict'
+		this.details = details
+	}
+}
+
+/**
+ * Reasons a session cannot transition `* → locked` for handoff. See
+ * session-hierarchy.md §5.1 — lock entry requires an `idle` session with all
+ * runs terminal. The three reasons are the non-terminal Run statuses that
+ * fan in to a non-idle Session.
+ */
+export type HandoffLockRejectedReason = 'active_run' | 'pending_hitl' | 'pending_subsession'
+
+/**
+ * Raised when a handoff targets a session whose current Run is non-terminal.
+ * Callers must wait for the active Run to terminalize (or cancel it) before
+ * re-attempting the handoff (session-hierarchy.md §5.1).
+ */
+export class HandoffLockRejected extends Error {
+	readonly details: {
+		sessionId: SessionId
+		reason: HandoffLockRejectedReason
+		runId?: RunId
+	}
+
+	constructor(details: { sessionId: SessionId; reason: HandoffLockRejectedReason; runId?: RunId }) {
+		super(`Handoff lock rejected on ${details.sessionId}: ${details.reason}`)
+		this.name = 'HandoffLockRejected'
+		this.details = details
+	}
+}

package/src/session/hierarchy/__tests__/session.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import type { RunStatus } from '../../../types/run/status.js'
+import type {
+	ProjectId,
+	SessionId,
+	TenantId,
+	ThreadId,
+	UserId,
+} from '../../../types/session/ids.js'
+import type { ActorRef } from '../actor.js'
+import { type Session, type SessionStatus, deriveStatus } from '../session.js'
+
+const tenant = 'tnt_a' as TenantId
+const project = 'prj_a' as ProjectId
+const thread = 'thd_a' as ThreadId
+
+function user(): ActorRef {
+	return { kind: 'user', userId: 'usr_a' as UserId, tenantId: tenant }
+}
+
+function makeSession(status: SessionStatus): Session {
+	return {
+		id: 'ses_a' as SessionId,
+		threadId: thread,
+		projectId: project,
+		tenantId: tenant,
+		status,
+		currentActor: user(),
+		previousActors: [],
+		workspaceId: null,
+		ownerVersion: 0,
+		createdAt: new Date('2026-01-01'),
+		updatedAt: new Date('2026-01-01'),
+	}
+}
+
+function runs(...statuses: RunStatus[]): readonly { status: RunStatus }[] {
+	return statuses.map((status) => ({ status }))
+}
+
+describe('deriveStatus', () => {
+	it('empty run set → idle', () => {
+		expect(deriveStatus(makeSession('idle'), [])).toBe('idle')
+	})
+
+	it('all succeeded → idle', () => {
+		expect(deriveStatus(makeSession('idle'), runs('succeeded', 'succeeded'))).toBe('idle')
+	})
+
+	it('any running → active (overrides idle session status)', () => {
+		expect(deriveStatus(makeSession('idle'), runs('succeeded', 'running'))).toBe('active')
+	})
+
+	it('any awaiting_subsession → active (delegation-in-flight parent is active)', () => {
+		expect(deriveStatus(makeSession('idle'), runs('succeeded', 'awaiting_subsession'))).toBe(
+			'active',
+		)
+	})
+
+	it('awaiting_subsession alone → active', () => {
+		expect(deriveStatus(makeSession('idle'), runs('awaiting_subsession'))).toBe('active')
+	})
+
+	it('any awaiting_hitl → awaiting_hitl', () => {
+		expect(deriveStatus(makeSession('idle'), runs('succeeded', 'awaiting_hitl'))).toBe(
+			'awaiting_hitl',
+		)
+	})
+
+	it('any awaiting_hitl_resolution → awaiting_hitl (persisted HITL wait)', () => {
+		expect(deriveStatus(makeSession('idle'), runs('awaiting_hitl_resolution'))).toBe(
+			'awaiting_hitl',
+		)
+	})
+
+	it('all failed → failed', () => {
+		expect(deriveStatus(makeSession('idle'), runs('failed', 'failed'))).toBe('failed')
+	})
+
+	it('cancelled + failed + succeeded mix → idle (cancellation is not terminal Session state)', () => {
+		expect(deriveStatus(makeSession('idle'), runs('succeeded', 'cancelled', 'failed'))).toBe('idle')
+	})
+
+	it('locked session-level state wins over derived (even with succeeded runs)', () => {
+		expect(deriveStatus(makeSession('locked'), runs('succeeded'))).toBe('locked')
+	})
+
+	it('awaiting_merge session-level state wins over derived', () => {
+		expect(deriveStatus(makeSession('awaiting_merge'), runs('succeeded'))).toBe('awaiting_merge')
+	})
+
+	it('archived session-level state wins over derived (retention tombstone)', () => {
+		expect(deriveStatus(makeSession('archived'), runs('succeeded'))).toBe('archived')
+	})
+
+	it('running takes precedence over HITL', () => {
+		// Two runs — one running, one HITL. Active is higher priority (§5.1).
+		expect(deriveStatus(makeSession('idle'), runs('running', 'awaiting_hitl'))).toBe('active')
+	})
+})

package/src/session/hierarchy/actor.ts

@@ -0,0 +1,17 @@
+import type { AgentId, TenantId, UserId } from '../../types/ids/index.js'
+
+/**
+ * Discriminated union of actors that can own a {@link Session}.
+ *
+ * See session-hierarchy.md §4.3. The `parentActor` field on the agent variant
+ * pairs with {@link Lineage} (§10.4) — permission audit events walk this
+ * chain to attribute subagent actions back to the originating user. Renamed
+ * from `spawnedBy` during the 0.2.0 design phase (no shim kept).
+ */
+export type ActorRef =
+	| { kind: 'user'; userId: UserId; tenantId: TenantId }
+	| { kind: 'agent'; agentId: AgentId; tenantId: TenantId; parentActor?: ActorRef }
+	| { kind: 'system'; role: SystemRoleId; tenantId: TenantId }
+
+/** Branded id for the {@link ActorRef} `system` variant. */
+export type SystemRoleId = `sys_${string}`

package/src/session/hierarchy/index.ts

@@ -0,0 +1,18 @@
+// Sub-barrel for the session-hierarchy entity model.
+// Convention #4: concrete types live in sibling files; re-export them here.
+
+export type { ActorRef, SystemRoleId } from './actor.js'
+export type { Lineage } from './lineage.js'
+export type { Tenant } from './tenant.js'
+export type { Project, ProjectConfig } from './project.js'
+export type { Thread, ThreadStatus } from './thread.js'
+export type { Session, SessionStatus } from './session.js'
+export { deriveStatus } from './session.js'
+export type {
+	SubSession,
+	SubSessionStatus,
+	SubSessionKind,
+	FailureMode,
+	CompletionMode,
+	DeliverableRef,
+} from './sub-session.js'

package/src/session/hierarchy/lineage.ts

@@ -0,0 +1,15 @@
+import type { SessionId } from '../../types/ids/index.js'
+
+/**
+ * Parent/root linkage carried on every sub-session event.
+ *
+ * Per session-hierarchy.md §10.4 every `RunEvent` emitted from a sub-session
+ * carries a {@link Lineage} so consumers can reconstruct the delegation tree
+ * without walking the store. `depth` is 0 at the root session and grows by 1
+ * per delegation level.
+ */
+export interface Lineage {
+	parentSessionId: SessionId
+	rootSessionId: SessionId
+	depth: number
+}

package/src/session/hierarchy/project.ts

@@ -0,0 +1,41 @@
+import type { KnowledgeBaseRef, MemoryStoreRef, TenantId, VaultRef } from '../../types/ids/index.js'
+import type { ProjectId } from '../../types/session/ids.js'
+import type { RetentionPolicy } from '../retention/policy.js'
+
+/**
+ * Per-project configuration. Defaults per session-hierarchy.md §3 / §4.2 /
+ * §8.2 are applied at instantiation time (not encoded here) so the type
+ * stays declarative:
+ *   - maxDelegationDepth: 4
+ *   - maxDelegationWidth: 8
+ *   - maxInterventionDepth: 10
+ *   - sharedDeliverables: false
+ *
+ * `retentionPolicy` replaces the Phase 1 `RetentionPolicyRef = unknown`
+ * placeholder with the real {@link RetentionPolicy} shape (§12.3). Absent
+ * (deny-by-default per Convention #5) means archival is fully disabled for
+ * the project; explicit configuration is required.
+ */
+export interface ProjectConfig {
+	maxDelegationDepth: number
+	maxDelegationWidth: number
+	maxInterventionDepth: number
+	sharedMemoryStores?: readonly MemoryStoreRef[]
+	sharedVaults?: readonly VaultRef[]
+	sharedKnowledgeBases?: readonly KnowledgeBaseRef[]
+	sharedDeliverables?: boolean
+	retentionPolicy?: RetentionPolicy
+}
+
+/**
+ * Long-lived goal scope that owns shared memory, vaults, knowledge bases,
+ * and deliverables across sessions. See session-hierarchy.md §4.2.
+ */
+export interface Project {
+	id: ProjectId
+	tenantId: TenantId
+	name: string
+	config: ProjectConfig
+	createdAt: Date
+	updatedAt: Date
+}

package/src/session/hierarchy/session.ts

@@ -0,0 +1,109 @@
+import type { SessionId, TenantId } from '../../types/ids/index.js'
+import type { RunStatus } from '../../types/run/status.js'
+import type { ProjectId, ThreadId, WorkspaceId } from '../../types/session/ids.js'
+import type { ActorRef } from './actor.js'
+
+/**
+ * Session lifecycle states. See session-hierarchy.md §4.3 and the state
+ * machine in §5.1. `awaiting_merge` is a sub-state of idle used on the
+ * broadcast source session (§5.4) between fan-out and all recipients
+ * terminalizing.
+ */
+export type SessionStatus =
+	| 'active'
+	| 'idle'
+	| 'locked'
+	| 'awaiting_hitl'
+	| 'awaiting_merge'
+	| 'failed'
+	| 'archived'
+
+/**
+ * Multi-turn work unit owned by exactly one {@link ActorRef} at a time.
+ *
+ * Scope identifiers:
+ *   - `threadId` — the topic-level {@link Thread} this Session lives under.
+ *     Set at creation, immutable; Sessions never move threads.
+ *   - `projectId` — the {@link Project} the owning Thread belongs to.
+ *     **Denormalized** from `thread.projectId` at creation time; immutable.
+ *     Kept on the Session record for ergonomic access (Project-scoped
+ *     consumers — handoff validators, archival, retention — would otherwise
+ *     need a second round-trip to ThreadStore on every read). This is NOT
+ *     a deprecated mirror of a fading field; it is a deliberate
+ *     denormalization of structurally-immutable derived data.
+ *
+ * Other invariants (session-hierarchy.md §4.3):
+ *   - `previousActors` is append-only and publicly read-only; previous
+ *     owners cannot write to the session again.
+ *   - `ownerVersion` is the CAS counter for handoff (§6.1 / §6.2 / §6.4).
+ *   - `workspaceId` is nullable for sessions whose workspace has not yet
+ *     been provisioned (or has been torn down during archival).
+ */
+export interface Session {
+	id: SessionId
+	threadId: ThreadId
+	projectId: ProjectId
+	tenantId: TenantId
+	status: SessionStatus
+	currentActor: ActorRef | null
+	previousActors: readonly ActorRef[]
+	workspaceId: WorkspaceId | null
+	ownerVersion: number
+	createdAt: Date
+	updatedAt: Date
+}
+
+/**
+ * Pure Run→Session fan-in helper per session-hierarchy.md §5.1.
+ *
+ * The precedence (highest first) matches the pattern-doc table:
+ *   1. Session-level states that do not fan in from Run status:
+ *      - `locked` (handoff CAS window) — preserved verbatim
+ *      - `awaiting_merge` (broadcast source post-fan-out, §5.4) — preserved
+ *      - `archived` (retention tombstone, §12.3) — preserved
+ *   2. Any Run `running` or `awaiting_subsession` → Session `active`.
+ *      Delegation-in-flight is an active state of the parent — the parent
+ *      Run is suspended waiting on the child's SessionSummaryMaterializer,
+ *      and the session is NOT idle while that is pending.
+ *   3. Any Run `awaiting_hitl` or `awaiting_hitl_resolution` → Session
+ *      `awaiting_hitl`.
+ *   4. All Runs `failed` and at least one Run present → Session `failed`.
+ *   5. Otherwise (all runs terminal — succeeded/cancelled/failed mix, or no
+ *      runs at all) → Session `idle`.
+ *
+ * `cancelled` does NOT surface a `failed` Session (§5.1 — "Cancellation is
+ * not a terminal Session state"). Only `failed` runs drive the Session to
+ * `failed` when every Run ended that way.
+ */
+export function deriveStatus(
+	session: Session,
+	runs: readonly { status: RunStatus }[],
+): SessionStatus {
+	// Session-level overrides — these states do not fan in from Run status.
+	if (session.status === 'locked') return 'locked'
+	if (session.status === 'awaiting_merge') return 'awaiting_merge'
+	if (session.status === 'archived') return 'archived'
+
+	// Any active Run (in-flight iteration or awaiting a child sub-session) →
+	// `active`. Delegation is an active state: the parent Run is suspended
+	// waiting on the child's Materializer, not idle.
+	const hasActive = runs.some((r) => r.status === 'running' || r.status === 'awaiting_subsession')
+	if (hasActive) return 'active'
+
+	// Any HITL block (synchronous or persisted) → `awaiting_hitl`.
+	const hasHitl = runs.some(
+		(r) => r.status === 'awaiting_hitl' || r.status === 'awaiting_hitl_resolution',
+	)
+	if (hasHitl) return 'awaiting_hitl'
+
+	// All failed (with at least one Run) → `failed`. Note that a `cancelled`
+	// Run does NOT drive the Session to `failed`; §5.1 is explicit that
+	// cancellation leaves the Session `idle`.
+	if (runs.length > 0 && runs.every((r) => r.status === 'failed')) {
+		return 'failed'
+	}
+
+	// Otherwise — empty run set, or all runs terminated (succeeded / cancelled
+	// / mixed with failed) — the Session is `idle`.
+	return 'idle'
+}