@namzu/sdk 0.1.8 → 0.3.0

package/src/session/__tests__/integration/handoff-illegal-transition.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Integration — `active → locked` illegal-transition rejection matrix per
+ * pattern doc §5.1.
+ *
+ * A handoff request against a session whose current Run is `running`,
+ * `awaiting_hitl`, `awaiting_hitl_resolution`, or `awaiting_subsession`
+ * rejects with typed {@link HandoffLockRejected}. The reason enum maps:
+ *   - running              → 'active_run'
+ *   - awaiting_hitl        → 'pending_hitl'
+ *   - awaiting_hitl_resol. → 'pending_hitl'
+ *   - awaiting_subsession  → 'pending_subsession'
+ *
+ * This integration test wires the `RunStatusResolver` seam into a full
+ * single-handoff flow so the rejection triggers from the run-fan-in check
+ * (§5.1), not just from a status precondition.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { ThreadManager } from '../../../manager/thread/lifecycle.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
+import type { ThreadId } from '../../../types/session/ids.js'
+import { generateHandoffId } from '../../../utils/id.js'
+import type { HandoffAssignment } from '../../handoff/assignment.js'
+import { DefaultCapacityValidator } from '../../handoff/capacity.js'
+import type { HandoffEventSink } from '../../handoff/events.js'
+import {
+	type RunStatusResolver,
+	type SingleHandoffDeps,
+	executeSingleHandoff,
+} from '../../handoff/single.js'
+import { HandoffLockRejected } from '../../handoff/version.js'
+import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
+import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
+import { DEFAULT_TENANT, okExec, stubLogger, userActor } from './_fixtures.js'
+
+function buildDeps(
+	store: InMemorySessionStore,
+	threadStore: InMemoryThreadStore,
+	runStatus?: RunStatusResolver,
+): SingleHandoffDeps {
+	const driver = new GitWorktreeDriver({
+		repoRoot: '/repo',
+		logger: stubLogger(),
+		execFile: async () => okExec(),
+	})
+	const workspaceRegistry = new WorkspaceBackendRegistry()
+	workspaceRegistry.register(driver)
+
+	const events: HandoffEventSink = {}
+
+	return {
+		store,
+		workspaceRegistry,
+		capacity: new DefaultCapacityValidator(store),
+		events,
+		threadManager: new ThreadManager({ threadStore, sessionStore: store }),
+		...(runStatus !== undefined && { runStatus }),
+	}
+}
+
+async function seedIdleSession(store: InMemorySessionStore, threadStore: InMemoryThreadStore) {
+	const project = await store.createProject(
+		{ tenantId: DEFAULT_TENANT, name: 'illegal' },
+		DEFAULT_TENANT,
+	)
+	const thread = await threadStore.createThread(
+		{ projectId: project.id, title: 'illegal' },
+		DEFAULT_TENANT,
+	)
+	const session = await store.createSession(
+		{ threadId: thread.id, projectId: project.id, currentActor: userActor('usr_source') },
+		DEFAULT_TENANT,
+	)
+	return { project, thread, session }
+}
+
+function buildAssignment(
+	sourceSessionId: Awaited<ReturnType<InMemorySessionStore['createSession']>>['id'],
+	projectId: Awaited<ReturnType<InMemorySessionStore['createProject']>>['id'],
+	threadId: ThreadId,
+): HandoffAssignment {
+	return {
+		id: generateHandoffId(),
+		mode: 'single',
+		sourceSessionId,
+		tenantId: DEFAULT_TENANT,
+		threadId,
+		projectId,
+		sourceActor: userActor('usr_source'),
+		recipientActor: userActor('usr_target'),
+		expectedOwnerVersion: 0,
+		createdAt: new Date('2026-04-17'),
+	}
+}
+
+describe('Integration — illegal handoff transitions (§5.1)', () => {
+	it('running Run → HandoffLockRejected { reason: active_run }', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const { project, thread, session } = await seedIdleSession(store, threadStore)
+		const deps = buildDeps(store, threadStore, {
+			async blockingRun() {
+				return { reason: 'active_run' }
+			},
+		})
+		const assignment = buildAssignment(session.id, project.id, thread.id)
+
+		try {
+			await executeSingleHandoff(deps, assignment, DEFAULT_TENANT)
+			expect.fail('expected HandoffLockRejected')
+		} catch (err) {
+			expect(err).toBeInstanceOf(HandoffLockRejected)
+			expect((err as HandoffLockRejected).details.reason).toBe('active_run')
+		}
+
+		// Source never locked — still idle with original version.
+		const reloaded = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+		expect(reloaded?.ownerVersion).toBe(0)
+	})
+
+	it('awaiting_hitl → HandoffLockRejected { reason: pending_hitl }', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const { project, thread, session } = await seedIdleSession(store, threadStore)
+		const deps = buildDeps(store, threadStore, {
+			async blockingRun() {
+				return { reason: 'pending_hitl' }
+			},
+		})
+
+		try {
+			await executeSingleHandoff(
+				deps,
+				buildAssignment(session.id, project.id, thread.id),
+				DEFAULT_TENANT,
+			)
+			expect.fail('expected HandoffLockRejected')
+		} catch (err) {
+			expect(err).toBeInstanceOf(HandoffLockRejected)
+			expect((err as HandoffLockRejected).details.reason).toBe('pending_hitl')
+		}
+	})
+
+	it('awaiting_hitl_resolution collapses into pending_hitl reason (timeout variant)', async () => {
+		// §5.2 treats `awaiting_hitl_resolution` as the same non-terminal class
+		// that forces the source into `awaiting_hitl` — the resolver surfaces
+		// `pending_hitl` for both. This keeps the lock-rejection enum
+		// conservative (no new reason variant for a sub-state).
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const { project, thread, session } = await seedIdleSession(store, threadStore)
+		const deps = buildDeps(store, threadStore, {
+			async blockingRun() {
+				return { reason: 'pending_hitl' }
+			},
+		})
+
+		await expect(
+			executeSingleHandoff(
+				deps,
+				buildAssignment(session.id, project.id, thread.id),
+				DEFAULT_TENANT,
+			),
+		).rejects.toBeInstanceOf(HandoffLockRejected)
+	})
+
+	it('awaiting_subsession → HandoffLockRejected { reason: pending_subsession }', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const { project, thread, session } = await seedIdleSession(store, threadStore)
+		const deps = buildDeps(store, threadStore, {
+			async blockingRun() {
+				return { reason: 'pending_subsession' }
+			},
+		})
+
+		try {
+			await executeSingleHandoff(
+				deps,
+				buildAssignment(session.id, project.id, thread.id),
+				DEFAULT_TENANT,
+			)
+			expect.fail('expected HandoffLockRejected')
+		} catch (err) {
+			expect(err).toBeInstanceOf(HandoffLockRejected)
+			expect((err as HandoffLockRejected).details.reason).toBe('pending_subsession')
+		}
+	})
+
+	it('session status precondition: active-status session rejects before resolver fires', async () => {
+		// When the session itself is already non-idle (e.g. `active`), the lock
+		// rejection fires from the status check — no RunStatusResolver invoked.
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const { project, thread, session } = await seedIdleSession(store, threadStore)
+		await store.updateSession({ ...session, status: 'active' }, DEFAULT_TENANT)
+
+		const deps = buildDeps(store, threadStore, {
+			async blockingRun() {
+				return null // resolver would allow, but status guard trips first
+			},
+		})
+
+		await expect(
+			executeSingleHandoff(
+				deps,
+				buildAssignment(session.id, project.id, thread.id),
+				DEFAULT_TENANT,
+			),
+		).rejects.toBeInstanceOf(HandoffLockRejected)
+	})
+})

package/src/session/__tests__/integration/handoff-single-e2e.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Integration — single-recipient handoff wired through the full stack.
+ *
+ * Orthogonal to `handoff/__tests__/single.test.ts` (unit-level): this
+ * exercises the real `InMemorySessionStore` + real `GitWorktreeDriver` (with
+ * stubbed `execFile`) + real {@link DefaultCapacityValidator} so the commit
+ * ordering + workspace provisioning side-effects are verifiable from the
+ * outside.
+ *
+ * Covers roadmap §5 invariants: §4.8 (handoff has no accepted field — commit
+ * is atomic), §6.1 (single-recipient flow: lock → commit), §5.1 (source
+ * transitions back to idle with bumped ownerVersion + appended previousActors).
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { ThreadManager } from '../../../manager/thread/lifecycle.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
+import type { TenantId } from '../../../types/ids/index.js'
+import { generateHandoffId } from '../../../utils/id.js'
+import { TenantIsolationError } from '../../errors.js'
+import type { HandoffAssignment } from '../../handoff/assignment.js'
+import { DefaultCapacityValidator } from '../../handoff/capacity.js'
+import type { HandoffEventSink } from '../../handoff/events.js'
+import { type SingleHandoffDeps, executeSingleHandoff } from '../../handoff/single.js'
+import type { Session } from '../../hierarchy/session.js'
+import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
+import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
+import { DEFAULT_TENANT, OTHER_TENANT, okExec, stubLogger, userActor } from './_fixtures.js'
+
+function buildHandoffDeps(
+	store: InMemorySessionStore,
+	threadStore: InMemoryThreadStore,
+): {
+	deps: SingleHandoffDeps
+	updateCalls: Array<{ status?: string; ownerVersion?: number }>
+} {
+	const driver = new GitWorktreeDriver({
+		repoRoot: '/repo',
+		logger: stubLogger(),
+		execFile: async () => okExec(),
+	})
+	const workspaceRegistry = new WorkspaceBackendRegistry()
+	workspaceRegistry.register(driver)
+
+	const sink: HandoffEventSink = {
+		onLocked: vi.fn(),
+		onUnlocked: vi.fn(),
+		onCommitted: vi.fn(),
+		onBroadcastRollback: vi.fn(),
+	}
+
+	const updateCalls: Array<{ status?: string; ownerVersion?: number }> = []
+	const originalUpdate = store.updateSession.bind(store)
+	store.updateSession = async (session: Session, tenantId) => {
+		updateCalls.push({ status: session.status, ownerVersion: session.ownerVersion })
+		return originalUpdate(session, tenantId)
+	}
+
+	const threadManager = new ThreadManager({ threadStore, sessionStore: store })
+	return {
+		deps: {
+			store,
+			workspaceRegistry,
+			capacity: new DefaultCapacityValidator(store),
+			events: sink,
+			threadManager,
+		},
+		updateCalls,
+	}
+}
+
+describe('Integration — single-recipient handoff E2E', () => {
+	it('idle → locked → commit: source previousActors grew + ownerVersion bumped atomically', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'ho' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'ho' },
+			DEFAULT_TENANT,
+		)
+		const sourceActor = userActor('usr_source')
+		const recipientActor = userActor('usr_target')
+		const session = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: sourceActor },
+			DEFAULT_TENANT,
+		)
+
+		const { deps, updateCalls } = buildHandoffDeps(store, threadStore)
+		const assignment: HandoffAssignment = {
+			id: generateHandoffId(),
+			mode: 'single',
+			sourceSessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			threadId: thread.id,
+			projectId: project.id,
+			sourceActor,
+			recipientActor,
+			expectedOwnerVersion: 0,
+			createdAt: new Date('2026-04-17'),
+		}
+
+		const outcome = await executeSingleHandoff(deps, assignment, DEFAULT_TENANT)
+
+		expect(outcome.committedOwnerVersion).toBe(1)
+
+		const reloaded = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+		expect(reloaded?.ownerVersion).toBe(1)
+		expect(reloaded?.currentActor).toEqual(recipientActor)
+		expect(reloaded?.previousActors).toHaveLength(1)
+		expect(reloaded?.previousActors[0]).toEqual(sourceActor)
+
+		// Wired assertion: updateSession was invoked at least with the lock
+		// transition + the final commit. That sequence is what makes the
+		// handoff "atomic at the store layer".
+		// Expect at minimum locked (v0) followed by committed (v1).
+		expect(updateCalls).toEqual(
+			expect.arrayContaining([
+				{ status: 'locked', ownerVersion: 0 },
+				{ status: 'idle', ownerVersion: 1 },
+			]),
+		)
+	})
+
+	it('cross-tenant assignment rejects at entry (TenantIsolationError)', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'ct' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'ct' },
+			DEFAULT_TENANT,
+		)
+		const session = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: userActor('usr_source') },
+			DEFAULT_TENANT,
+		)
+
+		const { deps } = buildHandoffDeps(store, threadStore)
+		const assignment: HandoffAssignment = {
+			id: generateHandoffId(),
+			mode: 'single',
+			sourceSessionId: session.id,
+			tenantId: OTHER_TENANT,
+			threadId: thread.id,
+			projectId: project.id,
+			sourceActor: userActor('usr_source', OTHER_TENANT),
+			recipientActor: userActor('usr_target', OTHER_TENANT),
+			expectedOwnerVersion: 0,
+			createdAt: new Date('2026-04-17'),
+		}
+
+		await expect(executeSingleHandoff(deps, assignment, OTHER_TENANT)).rejects.toBeInstanceOf(
+			TenantIsolationError,
+		)
+	})
+
+	it('source-owned workspace provisioned for recipient', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'wsp' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'wsp' },
+			DEFAULT_TENANT,
+		)
+		const source = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: userActor('usr_source') },
+			DEFAULT_TENANT,
+		)
+
+		const { deps } = buildHandoffDeps(store, threadStore)
+		const assignment: HandoffAssignment = {
+			id: generateHandoffId(),
+			mode: 'single',
+			sourceSessionId: source.id,
+			tenantId: DEFAULT_TENANT,
+			threadId: thread.id,
+			projectId: project.id,
+			sourceActor: userActor('usr_source'),
+			recipientActor: userActor('usr_target'),
+			expectedOwnerVersion: 0,
+			createdAt: new Date('2026-04-17'),
+		}
+
+		const outcome = await executeSingleHandoff(deps, assignment, DEFAULT_TENANT)
+
+		expect(outcome.workspaceId.startsWith('wsp_')).toBe(true)
+		expect(outcome.newSessionId.startsWith('ses_')).toBe(true)
+
+		// Recipient session exists under the same tenant/project.
+		const recipient = await store.getSession(outcome.newSessionId, DEFAULT_TENANT)
+		expect(recipient).not.toBeNull()
+		expect(recipient?.projectId).toBe(project.id)
+		expect(recipient?.tenantId).toBe(DEFAULT_TENANT)
+		expect(recipient?.currentActor).toEqual(userActor('usr_target'))
+
+		// A sub-session edge links the source to the recipient.
+		const children = await store.getChildren(source.id, DEFAULT_TENANT)
+		expect(children).toHaveLength(1)
+		expect(children[0]?.kind).toBe('user_handoff')
+		expect(children[0]?.childSessionId).toBe(outcome.newSessionId)
+	})
+
+	// Tenant-denormalization-on-record assertion — every persisted entity
+	// carries the tenantId explicitly, which matters for §12 isolation.
+	it('denormalized tenantId stamped on Session + SubSession records', async () => {
+		const _tenantType: TenantId = DEFAULT_TENANT
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'denorm' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'denorm' },
+			DEFAULT_TENANT,
+		)
+		const source = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: userActor('usr_source') },
+			DEFAULT_TENANT,
+		)
+		const { deps } = buildHandoffDeps(store, threadStore)
+
+		const assignment: HandoffAssignment = {
+			id: generateHandoffId(),
+			mode: 'single',
+			sourceSessionId: source.id,
+			tenantId: DEFAULT_TENANT,
+			threadId: thread.id,
+			projectId: project.id,
+			sourceActor: userActor('usr_source'),
+			recipientActor: userActor('usr_target'),
+			expectedOwnerVersion: 0,
+			createdAt: new Date(),
+		}
+		const outcome = await executeSingleHandoff(deps, assignment, DEFAULT_TENANT)
+
+		// Recipient's Session stores tenantId explicitly (not inferred).
+		const recipient = await store.getSession(outcome.newSessionId, DEFAULT_TENANT)
+		expect(recipient?.tenantId).toBe(_tenantType)
+	})
+})

package/src/session/__tests__/integration/hierarchy-lifecycle.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Integration — Tenant → Project → Session → SubSession → Run hierarchy
+ * lifecycle against a real {@link InMemorySessionStore}.
+ *
+ * Covers roadmap §5 invariants §4 (branded IDs), §4.3 (currentActor
+ * immutability), §4.4 (sub-session status fan-in to drill), plus the
+ * `drill()` navigation primitive (§14.3). Orthogonal to `e2e-spawn.test.ts`
+ * (which exercises the full AgentManager spawn path); this file asserts the
+ * raw store contract under direct construction.
+ */
+
+import { describe, expect, it } from 'vitest'
+import type { ThreadId } from '../../../types/session/ids.js'
+import { TenantIsolationError } from '../../errors.js'
+import { DEFAULT_TENANT, agentActor, buildHarness, userActor } from './_fixtures.js'
+
+const TEST_THREAD_ID = 'thd_test' as ThreadId
+
+describe('Integration — hierarchy lifecycle', () => {
+	it('creates Tenant → Project → Session → SubSession with properly branded IDs', async () => {
+		const { store } = buildHarness()
+		const tenant = DEFAULT_TENANT
+
+		const project = await store.createProject({ tenantId: tenant, name: 'p1' }, tenant)
+		expect(project.id.startsWith('prj_')).toBe(true)
+		expect(project.tenantId.startsWith('tnt_')).toBe(true)
+
+		const session = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor('usr_a') },
+			tenant,
+		)
+		expect(session.id.startsWith('ses_')).toBe(true)
+		expect(session.projectId).toBe(project.id)
+		expect(session.tenantId).toBe(tenant)
+		expect(session.status).toBe('idle')
+		expect(session.ownerVersion).toBe(0)
+		expect(session.previousActors).toEqual([])
+
+		const childSession = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor('agt_worker') },
+			tenant,
+		)
+		const subSession = await store.createSubSession(
+			{
+				parentSessionId: session.id,
+				childSessionId: childSession.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor('usr_a'),
+			},
+			tenant,
+		)
+		expect(subSession.id.startsWith('sub_')).toBe(true)
+		expect(subSession.parentSessionId).toBe(session.id)
+		expect(subSession.childSessionId).toBe(childSession.id)
+		expect(subSession.kind).toBe('agent_spawn')
+		expect(subSession.status).toBe('pending')
+	})
+
+	it('drill(parentSessionId) returns a SessionView with children[] and ancestry[]', async () => {
+		const { store } = buildHarness()
+		const tenant = DEFAULT_TENANT
+
+		const project = await store.createProject({ tenantId: tenant, name: 'drill' }, tenant)
+		const parent = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor('usr_root') },
+			tenant,
+		)
+		const childA = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor('agt_a') },
+			tenant,
+		)
+		const childB = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor('agt_b') },
+			tenant,
+		)
+		await store.createSubSession(
+			{
+				parentSessionId: parent.id,
+				childSessionId: childA.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor('usr_root'),
+			},
+			tenant,
+		)
+		await store.createSubSession(
+			{
+				parentSessionId: parent.id,
+				childSessionId: childB.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor('usr_root'),
+			},
+			tenant,
+		)
+
+		const parentView = await store.drill(parent.id, tenant)
+		expect(parentView).not.toBeNull()
+		expect(parentView?.session.id).toBe(parent.id)
+		expect(parentView?.children).toHaveLength(2)
+		expect(parentView?.ancestry).toEqual([parent.id])
+
+		const childAView = await store.drill(childA.id, tenant)
+		expect(childAView).not.toBeNull()
+		expect(childAView?.ancestry).toEqual([parent.id, childA.id])
+		expect(childAView?.children).toHaveLength(0)
+	})
+
+	it('drill returns null for unknown session (deny-by-default)', async () => {
+		const { store } = buildHarness()
+		const view = await store.drill(
+			'ses_missing' as Parameters<typeof store.drill>[0],
+			DEFAULT_TENANT,
+		)
+		expect(view).toBeNull()
+	})
+
+	it('§4.3 currentActor immutable previousActors — append-only on handoff', async () => {
+		const { store } = buildHarness()
+		const tenant = DEFAULT_TENANT
+
+		const project = await store.createProject({ tenantId: tenant, name: 'actors' }, tenant)
+		const userA = userActor('usr_a')
+		const userB = userActor('usr_b')
+		const userC = userActor('usr_c')
+
+		const session = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userA },
+			tenant,
+		)
+
+		// Simulate two successive handoff commits — each pushes the old actor
+		// onto previousActors and increments ownerVersion.
+		const firstHandoff = {
+			...session,
+			currentActor: userB,
+			previousActors: [userA],
+			ownerVersion: 1,
+		}
+		await store.updateSession(firstHandoff, tenant)
+
+		const secondHandoff = {
+			...firstHandoff,
+			currentActor: userC,
+			previousActors: [...firstHandoff.previousActors, userB],
+			ownerVersion: 2,
+		}
+		await store.updateSession(secondHandoff, tenant)
+
+		const reloaded = await store.getSession(session.id, tenant)
+		expect(reloaded?.currentActor).toEqual(userC)
+		expect(reloaded?.previousActors).toEqual([userA, userB])
+		expect(reloaded?.ownerVersion).toBe(2)
+	})
+
+	it('cycle guard via AncestryCycleError: ancestry walk detects corrupted parent linkage', async () => {
+		const { store } = buildHarness()
+		const tenant = DEFAULT_TENANT
+
+		const project = await store.createProject({ tenantId: tenant, name: 'cycle' }, tenant)
+		const sA = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor('usr_a') },
+			tenant,
+		)
+		const sB = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor('usr_b') },
+			tenant,
+		)
+
+		// Valid edge sA → sB.
+		await store.createSubSession(
+			{
+				parentSessionId: sA.id,
+				childSessionId: sB.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor('usr_a'),
+			},
+			tenant,
+		)
+		// Corrupting edge sB → sA closes the cycle. The store layer does not
+		// pre-check parent direction (the pattern doc §4.5 discusses
+		// intervention DAG cycles; ancestry cycles are a store-corruption
+		// detection path per session/errors.ts#AncestryCycleError).
+		await store.createSubSession(
+			{
+				parentSessionId: sB.id,
+				childSessionId: sA.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor('usr_b'),
+			},
+			tenant,
+		)
+
+		await expect(store.getAncestry(sB.id, tenant)).rejects.toThrow(/cycle/i)
+	})
+
+	it('SubSession pending → active → idle lifecycle', async () => {
+		const { store } = buildHarness()
+		const tenant = DEFAULT_TENANT
+
+		const project = await store.createProject({ tenantId: tenant, name: 'lifecycle' }, tenant)
+		const parent = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor('usr_a') },
+			tenant,
+		)
+		const child = await store.createSession(
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor('agt_a') },
+			tenant,
+		)
+		const sub = await store.createSubSession(
+			{
+				parentSessionId: parent.id,
+				childSessionId: child.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor('usr_a'),
+			},
+			tenant,
+		)
+		expect(sub.status).toBe('pending')
+
+		// pending → active.
+		await store.updateSubSession({ ...sub, status: 'active' }, tenant)
+		const active = await store.getSubSession(sub.id, tenant)
+		expect(active?.status).toBe('active')
+
+		// active → idle (§5.3: no 'closed' state — sub-sessions terminate on idle).
+		await store.updateSubSession({ ...sub, status: 'idle' }, tenant)
+		const idle = await store.getSubSession(sub.id, tenant)
+		expect(idle?.status).toBe('idle')
+	})
+
+	it('cross-tenant hierarchy access rejects via TenantIsolationError', async () => {
+		const { store } = buildHarness()
+		const projectA = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'a' },
+			DEFAULT_TENANT,
+		)
+		await expect(
+			store.getProject(projectA.id, 'tnt_other' as typeof DEFAULT_TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+})