@namzu/sdk 0.2.0 → 0.4.0

package/src/session/handoff/__tests__/broadcast.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import {
 	type ExecFile,
@@ -7,6 +8,7 @@ import {
 } from '../../../session/workspace/git-worktree.js'
 import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { SessionId, TenantId, UserId } from '../../../types/ids/index.js'
 import type { ProjectId } from '../../../types/session/ids.js'
 import { generateHandoffId } from '../../../utils/id.js'
@@ -56,7 +58,11 @@ interface DepsBundle {
 	events: MockedHandoffEventSink
 }
 
-function buildDeps(store: InMemorySessionStore, execOverride?: ExecFile): DepsBundle {
+function buildDeps(
+	store: InMemorySessionStore,
+	threadStore: InMemoryThreadStore,
+	execOverride?: ExecFile,
+): DepsBundle {
 	const exec: ExecFile = execOverride ? execOverride : async (_file, _args) => okExec()
 	const driver = new GitWorktreeDriver({
 		repoRoot: '/repo',
@@ -73,29 +79,36 @@ function buildDeps(store: InMemorySessionStore, execOverride?: ExecFile): DepsBu
 		onBroadcastRollback: vi.fn<(ev: HandoffBroadcastRollbackEvent) => void>(),
 	}
 
+	const threadManager = new ThreadManager({ threadStore, sessionStore: store })
 	return {
 		deps: {
 			store,
 			workspaceRegistry: registry,
 			capacity: new DefaultCapacityValidator(store),
 			events,
+			threadManager,
 		},
 		events,
 	}
 }
 
-async function seedIdle(store: InMemorySessionStore) {
+async function seedIdle(store: InMemorySessionStore, threadStore: InMemoryThreadStore) {
 	const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant)
+	const thread = await threadStore.createThread(
+		{ projectId: project.id, title: 'handoff-broadcast-test' },
+		tenant,
+	)
 	const session = await store.createSession(
-		{ projectId: project.id, currentActor: user('usr_source') },
+		{ threadId: thread.id, projectId: project.id, currentActor: user('usr_source') },
 		tenant,
 	)
-	return { project, session }
+	return { project, thread, session }
 }
 
 function buildAssignments(
 	sourceSessionId: SessionId,
 	projectId: ProjectId,
+	threadId: Awaited<ReturnType<InMemoryThreadStore['createThread']>>['id'],
 	expectedOwnerVersion: number,
 	recipients: ActorRef[],
 	broadcastId = 'bc_1',
@@ -105,6 +118,7 @@ function buildAssignments(
 		mode: 'broadcast' as const,
 		sourceSessionId,
 		tenantId: tenant,
+		threadId,
 		projectId,
 		sourceActor: user('usr_source'),
 		recipientActor,
@@ -116,16 +130,18 @@ function buildAssignments(
 
 describe('executeBroadcastHandoff', () => {
 	let store: InMemorySessionStore
+	let threadStore: InMemoryThreadStore
 
 	beforeEach(() => {
 		store = new InMemorySessionStore()
+		threadStore = new InMemoryThreadStore()
 	})
 
 	it('happy path: 3 recipients → source ends in awaiting_merge with 3 new children', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps, events } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps, events } = buildDeps(store, threadStore)
 
-		const assignments = buildAssignments(session.id, project.id, 0, [
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
 			user('usr_bob'),
 			user('usr_carol'),
 			user('usr_dan'),
@@ -149,7 +165,7 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('rollback on mid-fan-out failure (2nd recipient worktree add fails): source reverts, rollback emits accurate partialState', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 
 		let addCount = 0
 		const exec: ExecFile = async (_file, args) => {
@@ -159,9 +175,9 @@ describe('executeBroadcastHandoff', () => {
 			}
 			return okExec()
 		}
-		const { deps, events } = buildDeps(store, exec)
+		const { deps, events } = buildDeps(store, threadStore, exec)
 
-		const assignments = buildAssignments(session.id, project.id, 0, [
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
 			user('usr_b'),
 			user('usr_c'),
 			user('usr_d'),
@@ -196,7 +212,7 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('rollback performs full cleanup via deleteSubSession/deleteSession (no status-flip stopgap)', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 
 		let addCount = 0
 		const exec: ExecFile = async (_file, args) => {
@@ -206,9 +222,12 @@ describe('executeBroadcastHandoff', () => {
 			}
 			return okExec()
 		}
-		const { deps } = buildDeps(store, exec)
+		const { deps } = buildDeps(store, threadStore, exec)
 
-		const assignments = buildAssignments(session.id, project.id, 0, [user('usr_b'), user('usr_c')])
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
+			user('usr_b'),
+			user('usr_c'),
+		])
 
 		await expect(executeBroadcastHandoff(deps, assignments, tenant)).rejects.toThrow()
 
@@ -224,7 +243,7 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('rollback idempotency: worktree dispose throwing during rollback does not bubble a secondary failure', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 
 		let addCount = 0
 		let removeCount = 0
@@ -242,9 +261,12 @@ describe('executeBroadcastHandoff', () => {
 			}
 			return okExec()
 		}
-		const { deps, events } = buildDeps(store, exec)
+		const { deps, events } = buildDeps(store, threadStore, exec)
 
-		const assignments = buildAssignments(session.id, project.id, 0, [user('usr_b'), user('usr_c')])
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
+			user('usr_b'),
+			user('usr_c'),
+		])
 
 		// Outer failure is the PRIMARY one — the secondary dispose failure is
 		// swallowed. Primary wraps in WorkspaceBackendError (create op).
@@ -262,11 +284,15 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('dedupe: two assignments targeting same recipient → rejected pre-lock (no side effects)', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps, events } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps, events } = buildDeps(store, threadStore)
 
 		const bob = user('usr_bob')
-		const assignments = buildAssignments(session.id, project.id, 0, [bob, bob, user('usr_dan')])
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [
+			bob,
+			bob,
+			user('usr_dan'),
+		])
 
 		await expect(executeBroadcastHandoff(deps, assignments, tenant)).rejects.toThrow(
 			/duplicate recipient/,
@@ -281,11 +307,11 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('width cap: 9 recipients exceeds default maxWidth=8 → rejected before source lock', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps, events } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps, events } = buildDeps(store, threadStore)
 
 		const recipients = Array.from({ length: 9 }, (_, i) => user(`usr_${i}`))
-		const assignments = buildAssignments(session.id, project.id, 0, recipients)
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, recipients)
 
 		await expect(executeBroadcastHandoff(deps, assignments, tenant)).rejects.toThrow(
 			/Delegation capacity exceeded/,
@@ -298,12 +324,13 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('concurrent broadcast on same source: second attempt rejected with HandoffVersionConflict', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps } = buildDeps(store, threadStore)
 
 		const firstAssignments = buildAssignments(
 			session.id,
 			project.id,
+			thread.id,
 			0,
 			[user('usr_b'), user('usr_c')],
 			'bc_1',
@@ -322,6 +349,7 @@ describe('executeBroadcastHandoff', () => {
 		const second = buildAssignments(
 			session.id,
 			project.id,
+			thread.id,
 			0, // stale — actual is 1
 			[user('usr_d'), user('usr_e')],
 			'bc_2',
@@ -332,16 +360,16 @@ describe('executeBroadcastHandoff', () => {
 	})
 
 	it('empty assignments → throws a descriptive error', async () => {
-		const { deps } = buildDeps(store)
+		const { deps } = buildDeps(store, threadStore)
 		await expect(executeBroadcastHandoff(deps, [], tenant)).rejects.toThrow(
 			/assignments must not be empty/,
 		)
 	})
 
 	it('single-row broadcast → rejected (caller must use executeSingleHandoff)', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps } = buildDeps(store)
-		const assignments = buildAssignments(session.id, project.id, 0, [user('usr_b')])
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps } = buildDeps(store, threadStore)
+		const assignments = buildAssignments(session.id, project.id, thread.id, 0, [user('usr_b')])
 
 		await expect(executeBroadcastHandoff(deps, assignments, tenant)).rejects.toThrow(
 			/single-recipient handoffs must use executeSingleHandoff/,

package/src/session/handoff/__tests__/capacity.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
 import { DefaultCapacityValidator, DelegationCapacityExceeded } from '../capacity.js'
 
 const tenant = 'tnt_alpha' as TenantId
@@ -16,18 +18,22 @@ function agent(): ActorRef {
 
 async function seedProject(store: InMemorySessionStore) {
 	const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant)
-	const root = await store.createSession({ projectId: project.id, currentActor: user() }, tenant)
-	return { project, root }
+	const threadStore = new InMemoryThreadStore()
+	const thread = await threadStore.createThread({ projectId: project.id, title: 'default' }, tenant)
+	const root = await store.createSession(
+		{ threadId: thread.id, projectId: project.id, currentActor: user() },
+		tenant,
+	)
+	return { project, thread, root }
 }
 
 async function spawnChild(
 	store: InMemorySessionStore,
 	parentId: SessionId,
-	projectId: ReturnType<typeof String> extends never
-		? never
-		: Parameters<InMemorySessionStore['createSession']>[0]['projectId'],
+	projectId: ProjectId,
+	threadId: ThreadId,
 ): Promise<{ childId: SessionId }> {
-	const child = await store.createSession({ projectId, currentActor: user() }, tenant)
+	const child = await store.createSession({ threadId, projectId, currentActor: user() }, tenant)
 	await store.createSubSession(
 		{
 			parentSessionId: parentId,
@@ -51,11 +57,11 @@ describe('DefaultCapacityValidator', () => {
 
 	it('depth: chain of 4 (root→c1→c2→c3→c4) allows a 5th (depth 5) to pass when limit = 5', async () => {
 		const store = new InMemorySessionStore()
-		const { project, root } = await seedProject(store)
-		const c1 = await spawnChild(store, root.id, project.id)
-		const c2 = await spawnChild(store, c1.childId, project.id)
-		const c3 = await spawnChild(store, c2.childId, project.id)
-		const c4 = await spawnChild(store, c3.childId, project.id)
+		const { project, thread, root } = await seedProject(store)
+		const c1 = await spawnChild(store, root.id, project.id, thread.id)
+		const c2 = await spawnChild(store, c1.childId, project.id, thread.id)
+		const c3 = await spawnChild(store, c2.childId, project.id, thread.id)
+		const c4 = await spawnChild(store, c3.childId, project.id, thread.id)
 
 		const validator = new DefaultCapacityValidator(store)
 		// Ancestry of c4: root→c1→c2→c3→c4 = length 5. Spawning under c4 = depth 5.
@@ -64,11 +70,11 @@ describe('DefaultCapacityValidator', () => {
 
 	it('depth: over-limit throws DelegationCapacityExceeded with dimension=depth', async () => {
 		const store = new InMemorySessionStore()
-		const { project, root } = await seedProject(store)
-		const c1 = await spawnChild(store, root.id, project.id)
-		const c2 = await spawnChild(store, c1.childId, project.id)
-		const c3 = await spawnChild(store, c2.childId, project.id)
-		const c4 = await spawnChild(store, c3.childId, project.id)
+		const { project, thread, root } = await seedProject(store)
+		const c1 = await spawnChild(store, root.id, project.id, thread.id)
+		const c2 = await spawnChild(store, c1.childId, project.id, thread.id)
+		const c3 = await spawnChild(store, c2.childId, project.id, thread.id)
+		const c4 = await spawnChild(store, c3.childId, project.id, thread.id)
 
 		const validator = new DefaultCapacityValidator(store)
 		try {
@@ -94,9 +100,9 @@ describe('DefaultCapacityValidator', () => {
 
 	it('width: existing 5 + pending 3 = 8 passes exactly at the limit', async () => {
 		const store = new InMemorySessionStore()
-		const { project, root } = await seedProject(store)
+		const { project, thread, root } = await seedProject(store)
 		for (let i = 0; i < 5; i++) {
-			await spawnChild(store, root.id, project.id)
+			await spawnChild(store, root.id, project.id, thread.id)
 		}
 		const validator = new DefaultCapacityValidator(store)
 		await expect(validator.validateWidth(root.id, 3, 8, tenant)).resolves.toBeUndefined()
@@ -104,9 +110,9 @@ describe('DefaultCapacityValidator', () => {
 
 	it('width: existing 6 + pending 3 = 9 exceeds 8, throws dimension=width', async () => {
 		const store = new InMemorySessionStore()
-		const { project, root } = await seedProject(store)
+		const { project, thread, root } = await seedProject(store)
 		for (let i = 0; i < 6; i++) {
-			await spawnChild(store, root.id, project.id)
+			await spawnChild(store, root.id, project.id, thread.id)
 		}
 		const validator = new DefaultCapacityValidator(store)
 		try {

package/src/session/handoff/__tests__/single.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { TenantIsolationError } from '../../../session/errors.js'
 import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import {
@@ -8,6 +9,7 @@ import {
 } from '../../../session/workspace/git-worktree.js'
 import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import type { HandoffAssignment } from '../assignment.js'
@@ -59,6 +61,7 @@ interface MockedHandoffEventSink extends HandoffEventSink {
 
 function buildDeps(
 	store: InMemorySessionStore,
+	threadStore: InMemoryThreadStore,
 	execOverride?: ExecFile,
 	runResolver?: RunStatusResolver,
 ): { deps: SingleHandoffDeps; events: MockedHandoffEventSink; execCalls: string[] } {
@@ -84,29 +87,36 @@ function buildDeps(
 		onBroadcastRollback: vi.fn<(ev: HandoffBroadcastRollbackEvent) => void>(),
 	}
 
+	const threadManager = new ThreadManager({ threadStore, sessionStore: store })
 	const deps: SingleHandoffDeps = {
 		store,
 		workspaceRegistry: registry,
 		capacity: new DefaultCapacityValidator(store),
 		events,
+		threadManager,
 		...(runResolver !== undefined && { runStatus: runResolver }),
 	}
 
 	return { deps, events, execCalls }
 }
 
-async function seedIdle(store: InMemorySessionStore) {
+async function seedIdle(store: InMemorySessionStore, threadStore: InMemoryThreadStore) {
 	const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant)
+	const thread = await threadStore.createThread(
+		{ projectId: project.id, title: 'handoff-single-test' },
+		tenant,
+	)
 	const session = await store.createSession(
-		{ projectId: project.id, currentActor: user('usr_source') },
+		{ threadId: thread.id, projectId: project.id, currentActor: user('usr_source') },
 		tenant,
 	)
-	return { project, session }
+	return { project, thread, session }
 }
 
 function buildAssignment(
 	sourceSessionId: SessionId,
 	projectId: Awaited<ReturnType<InMemorySessionStore['createProject']>>['id'],
+	threadId: Awaited<ReturnType<InMemoryThreadStore['createThread']>>['id'],
 	expectedOwnerVersion: number,
 	recipient: ActorRef = user('usr_target'),
 ): HandoffAssignment {
@@ -115,6 +125,7 @@ function buildAssignment(
 		mode: 'single',
 		sourceSessionId,
 		tenantId: tenant,
+		threadId,
 		projectId,
 		sourceActor: user('usr_source'),
 		recipientActor: recipient,
@@ -125,16 +136,18 @@ function buildAssignment(
 
 describe('executeSingleHandoff', () => {
 	let store: InMemorySessionStore
+	let threadStore: InMemoryThreadStore
 
 	beforeEach(() => {
 		store = new InMemorySessionStore()
+		threadStore = new InMemoryThreadStore()
 	})
 
 	it('happy path: idle source → lock → commit → outcome populated + source mutated', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps, events } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps, events } = buildDeps(store, threadStore)
 
-		const assignment = buildAssignment(session.id, project.id, 0)
+		const assignment = buildAssignment(session.id, project.id, thread.id, 0)
 		const outcome = await executeSingleHandoff(deps, assignment, tenant)
 
 		expect(outcome.assignmentId).toBe(assignment.id)
@@ -155,11 +168,11 @@ describe('executeSingleHandoff', () => {
 	})
 
 	it('rejects when source session is non-idle (active → HandoffLockRejected with active_run)', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 		await store.updateSession({ ...session, status: 'active' }, tenant)
 
-		const { deps } = buildDeps(store)
-		const assignment = buildAssignment(session.id, project.id, 0)
+		const { deps } = buildDeps(store, threadStore)
+		const assignment = buildAssignment(session.id, project.id, thread.id, 0)
 
 		try {
 			await executeSingleHandoff(deps, assignment, tenant)
@@ -171,14 +184,14 @@ describe('executeSingleHandoff', () => {
 	})
 
 	it('rejects when Run resolver reports pending_hitl', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 		const resolver: RunStatusResolver = {
 			async blockingRun() {
 				return { reason: 'pending_hitl' }
 			},
 		}
-		const { deps } = buildDeps(store, undefined, resolver)
-		const assignment = buildAssignment(session.id, project.id, 0)
+		const { deps } = buildDeps(store, threadStore, undefined, resolver)
+		const assignment = buildAssignment(session.id, project.id, thread.id, 0)
 
 		try {
 			await executeSingleHandoff(deps, assignment, tenant)
@@ -190,11 +203,11 @@ describe('executeSingleHandoff', () => {
 	})
 
 	it('rejects on tenant mismatch (TenantIsolationError)', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps } = buildDeps(store, threadStore)
 		// Assignment tenant differs from the call-site tenant.
 		const assignment: HandoffAssignment = {
-			...buildAssignment(session.id, project.id, 0),
+			...buildAssignment(session.id, project.id, thread.id, 0),
 			tenantId: otherTenant,
 		}
 		await expect(executeSingleHandoff(deps, assignment, otherTenant)).rejects.toBeInstanceOf(
@@ -203,13 +216,13 @@ describe('executeSingleHandoff', () => {
 	})
 
 	it('rejects on CAS mismatch (HandoffVersionConflict)', async () => {
-		const { project, session } = await seedIdle(store)
-		const { deps } = buildDeps(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
+		const { deps } = buildDeps(store, threadStore)
 
 		// Simulate a concurrent bump: move ownerVersion to 1 before the assignment
 		// with expectedOwnerVersion=0 is executed.
 		await store.updateSession({ ...session, ownerVersion: 1 }, tenant)
-		const assignment = buildAssignment(session.id, project.id, 0)
+		const assignment = buildAssignment(session.id, project.id, thread.id, 0)
 
 		try {
 			await executeSingleHandoff(deps, assignment, tenant)
@@ -224,18 +237,22 @@ describe('executeSingleHandoff', () => {
 	it('depth cap enforcement rejects with DelegationCapacityExceeded (dimension=depth)', async () => {
 		// Build a chain so the handoff source already sits at max depth.
 		const project = await store.createProject({ tenantId: tenant, name: 'p' }, tenant)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'depth-cap' },
+			tenant,
+		)
 		// Set a tight limit on the project via a second createProject? — no, the
 		// store hardcodes defaults {4,8,10}. Build a depth-4 chain then attempt
 		// handoff on depth-4 node (ancestry length 5 > 4).
 		const root = await store.createSession(
-			{ projectId: project.id, currentActor: user('usr_source') },
+			{ threadId: thread.id, projectId: project.id, currentActor: user('usr_source') },
 			tenant,
 		)
 		let parent = root.id
 		let tail: SessionId = root.id
 		for (let i = 0; i < 4; i++) {
 			const child = await store.createSession(
-				{ projectId: project.id, currentActor: user(`usr_${i}`) },
+				{ threadId: thread.id, projectId: project.id, currentActor: user(`usr_${i}`) },
 				tenant,
 			)
 			await store.createSubSession(
@@ -252,15 +269,15 @@ describe('executeSingleHandoff', () => {
 		}
 
 		// Source is `tail` at ancestry length 5 → depth-capacity with limit 4 rejects.
-		const { deps } = buildDeps(store)
-		const assignment = buildAssignment(tail, project.id, 0)
+		const { deps } = buildDeps(store, threadStore)
+		const assignment = buildAssignment(tail, project.id, thread.id, 0)
 		await expect(executeSingleHandoff(deps, assignment, tenant)).rejects.toBeInstanceOf(
 			DelegationCapacityExceeded,
 		)
 	})
 
 	it('compensating revert: workspace provisioning failure reverts source to idle, version unchanged, onUnlocked fires', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 
 		// Fail only on `worktree add` but pass for everything else. Here we fail
 		// the single worktree add.
@@ -270,8 +287,8 @@ describe('executeSingleHandoff', () => {
 			}
 			return okExec()
 		}
-		const { deps, events } = buildDeps(store, exec)
-		const assignment = buildAssignment(session.id, project.id, 0)
+		const { deps, events } = buildDeps(store, threadStore, exec)
+		const assignment = buildAssignment(session.id, project.id, thread.id, 0)
 
 		await expect(executeSingleHandoff(deps, assignment, tenant)).rejects.toThrow(
 			/Workspace backend git-worktree failed on create/,
@@ -290,7 +307,7 @@ describe('executeSingleHandoff', () => {
 	})
 
 	it('compensating revert: store.createSubSession failure still reverts + archives partial recipient', async () => {
-		const { project, session } = await seedIdle(store)
+		const { project, thread, session } = await seedIdle(store, threadStore)
 
 		// Monkey-patch createSubSession on the store to throw.
 		const original = store.createSubSession.bind(store)
@@ -298,8 +315,8 @@ describe('executeSingleHandoff', () => {
 			throw new Error('simulated createSubSession failure')
 		}
 
-		const { deps, events } = buildDeps(store)
-		const assignment = buildAssignment(session.id, project.id, 0)
+		const { deps, events } = buildDeps(store, threadStore)
+		const assignment = buildAssignment(session.id, project.id, thread.id, 0)
 
 		await expect(executeSingleHandoff(deps, assignment, tenant)).rejects.toThrow(
 			/createSubSession failure/,

package/src/session/handoff/assignment.ts

@@ -9,7 +9,7 @@
  */
 
 import type { SessionId, TenantId } from '../../types/ids/index.js'
-import type { HandoffId, ProjectId, WorkspaceId } from '../../types/session/ids.js'
+import type { HandoffId, ProjectId, ThreadId, WorkspaceId } from '../../types/session/ids.js'
 import type { ActorRef } from '../hierarchy/actor.js'
 
 /**
@@ -32,6 +32,18 @@ export interface HandoffAssignment {
 	mode: HandoffMode
 	sourceSessionId: SessionId
 	tenantId: TenantId
+	/**
+	 * Topic-layer scope the source session belongs to. Handoff recipients
+	 * always land on the same Thread (cross-thread handoff is forbidden —
+	 * a new actor taking over a conversation stays on the same topic).
+	 * Validated against `source.threadId` at execute time.
+	 */
+	threadId: ThreadId
+	/**
+	 * Denormalized from the owning Thread. Kept alongside `threadId` as the
+	 * Session record itself carries both (see `Session` JSDoc). Consistency
+	 * validated against `source.projectId` at execute time.
+	 */
 	projectId: ProjectId
 	/** The actor initiating the handoff (must be the source's current owner). */
 	sourceActor: ActorRef

package/src/session/handoff/broadcast.ts

@@ -21,6 +21,7 @@
  * ```
  */
 
+import type { ThreadManager } from '../../manager/thread/lifecycle.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { SubSessionId } from '../../types/session/ids.js'
 import type { SessionStore } from '../../types/session/store.js'
@@ -41,6 +42,12 @@ export interface BroadcastHandoffDeps {
 	capacity: CapacityValidator
 	events: HandoffEventSink
 	runStatus?: RunStatusResolver
+	/**
+	 * Gate every recipient-session creation on the Thread being `'open'`.
+	 * Added in Phase 2.6; checked once per broadcast (all recipients share
+	 * a threadId by the fan-out invariant validated above).
+	 */
+	threadManager: ThreadManager
 }
 
 /**
@@ -108,6 +115,9 @@ export async function executeBroadcastHandoff(
 		if (a.expectedOwnerVersion !== first.expectedOwnerVersion) {
 			throw new Error('executeBroadcastHandoff: all assignments must share expectedOwnerVersion')
 		}
+		if (a.threadId !== first.threadId) {
+			throw new Error('executeBroadcastHandoff: all assignments must share threadId')
+		}
 		if (a.projectId !== first.projectId) {
 			throw new Error('executeBroadcastHandoff: all assignments must share projectId')
 		}
@@ -130,6 +140,12 @@ export async function executeBroadcastHandoff(
 		seen.add(key)
 	}
 
+	// Thread archive gate (Phase 2.6) — runs BEFORE source load/capacity so an
+	// archived thread fails fastest with `ThreadClosedError`. All assignments
+	// share `threadId` by the shape validation above. Runs BEFORE the CAS
+	// lock so a denied fan-out leaves the source session untouched.
+	await deps.threadManager.requireOpen(first.threadId, tenantId)
+
 	// 3. Load source + tenant check.
 	const source = await deps.store.getSession(first.sourceSessionId, tenantId)
 	if (!source) {
@@ -141,6 +157,11 @@ export async function executeBroadcastHandoff(
 			resource: `session(${source.id})`,
 		})
 	}
+	if (source.threadId !== first.threadId) {
+		throw new Error(
+			`Assignment threadId ${first.threadId} does not match source threadId ${source.threadId}`,
+		)
+	}
 	if (source.projectId !== first.projectId) {
 		throw new Error(
 			`Assignment projectId ${first.projectId} does not match source projectId ${source.projectId}`,
@@ -220,7 +241,11 @@ export async function executeBroadcastHandoff(
 			worktreesProvisioned += 1
 
 			const childSession = await deps.store.createSession(
-				{ projectId: source.projectId, currentActor: assignment.recipientActor },
+				{
+					threadId: source.threadId,
+					projectId: source.projectId,
+					currentActor: assignment.recipientActor,
+				},
 				tenantId,
 			)
 			partial.createdSessionId = childSession.id