@namzu/sdk 0.1.8 → 0.3.0

package/src/session/__tests__/integration/event-stream-ordering.test.ts

@@ -0,0 +1,410 @@
+/**
+ * Integration — event stream ordering + lineage + schemaVersion envelope.
+ *
+ * Covers roadmap §5 invariants:
+ *   - §10.1 schemaVersion: 2 on every sub-session RunEvent
+ *   - §10.3 tree-scoped monotonic ordering by (rootSessionId, eventId)
+ *   - §10.3 depth filter ('self' vs 'tree') at subscribe time
+ *   - §10.4 lineage stamped on every sub-session event with parent + root + depth
+ *
+ * Orthogonal to `e2e-spawn.test.ts` (covers single-level spawn). This file
+ * drives a multi-level (3-deep) delegation tree so monotonic ordering across
+ * concurrent descendants is observable.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { EMPTY_TOKEN_USAGE } from '../../../constants/limits.js'
+import type { AgentManager } from '../../../manager/agent/lifecycle.js'
+import type { AgentInput, BaseAgentConfig, BaseAgentResult } from '../../../types/agent/base.js'
+import type { RunId } from '../../../types/ids/index.js'
+import { createAssistantMessage } from '../../../types/message/index.js'
+import type { RunEvent } from '../../../types/run/events.js'
+import { ZERO_COST } from '../../../utils/cost.js'
+import {
+	DEFAULT_TENANT,
+	buildAgent,
+	buildAgentCustom,
+	buildDefinition,
+	buildHarness,
+	buildSendMessageOptions,
+	buildTaskContext,
+	seedActiveParent,
+} from './_fixtures.js'
+
+describe('Integration — event stream ordering + lineage + schemaVersion', () => {
+	it('every sub-session RunEvent carries schemaVersion: 2', async () => {
+		const harness = buildHarness()
+		const { project, thread, session, actor } = await seedActiveParent(harness)
+		harness.registry.register(buildDefinition(buildAgent('worker')))
+
+		const captured: RunEvent[] = []
+		const task = await harness.manager.sendMessage(
+			buildSendMessageOptions({
+				agentId: 'worker',
+				parentSessionId: session.id,
+				projectId: project.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			buildTaskContext({
+				sessionId: session.id,
+				projectId: project.id,
+				threadId: thread.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			(ev) => {
+				captured.push(ev)
+			},
+		)
+		await harness.manager.waitForCompletion(task.taskId)
+
+		// Every sub-session lifecycle event is stamped with schemaVersion: 2.
+		const subSessionEvents = captured.filter(
+			(e) =>
+				e.type === 'subsession_spawned' ||
+				e.type === 'subsession_messaged' ||
+				e.type === 'subsession_idled',
+		)
+		expect(subSessionEvents.length).toBeGreaterThan(0)
+		for (const ev of subSessionEvents) {
+			expect(ev.schemaVersion).toBe(2)
+		}
+	})
+
+	it('every sub-session event carries lineage { parentSessionId, rootSessionId, depth }', async () => {
+		const harness = buildHarness()
+		const { project, thread, session, actor } = await seedActiveParent(harness)
+		harness.registry.register(buildDefinition(buildAgent('worker')))
+
+		const captured: RunEvent[] = []
+		const task = await harness.manager.sendMessage(
+			buildSendMessageOptions({
+				agentId: 'worker',
+				parentSessionId: session.id,
+				projectId: project.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			buildTaskContext({
+				sessionId: session.id,
+				projectId: project.id,
+				threadId: thread.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			(ev) => {
+				captured.push(ev)
+			},
+		)
+		await harness.manager.waitForCompletion(task.taskId)
+
+		const spawned = captured.find((e) => e.type === 'subsession_spawned')
+		const idled = captured.find((e) => e.type === 'subsession_idled')
+		expect(spawned).toBeDefined()
+		expect(idled).toBeDefined()
+
+		if (spawned && 'lineage' in spawned) {
+			expect(spawned.lineage.parentSessionId).toBe(session.id)
+			expect(spawned.lineage.rootSessionId).toBe(session.id)
+			expect(spawned.lineage.depth).toBe(1)
+		}
+		if (idled && 'lineage' in idled) {
+			expect(idled.lineage.parentSessionId).toBe(session.id)
+			expect(idled.lineage.rootSessionId).toBe(session.id)
+			expect(idled.lineage.depth).toBe(1)
+		}
+	})
+
+	it('3-deep delegation: rootSessionId identical across tree; depth ascends 1→2→3', async () => {
+		const harness = buildHarness()
+		const { project, thread, session, actor } = await seedActiveParent(harness)
+
+		// Wire a cascading agent: level-1 child spawns level-2 via its own
+		// sendMessage. We hand a reference to the manager into the child agent
+		// via a closure so level-2 can spawn level-3.
+		const manager: AgentManager = harness.manager
+		const nestedEventsCaptured: RunEvent[] = []
+
+		const leafAgent = buildAgent('leaf', 'leaf result')
+		const midAgent = buildAgentCustom(
+			'mid',
+			async (_input: AgentInput, config: BaseAgentConfig): Promise<BaseAgentResult> => {
+				// Spawn a level-2 child from inside the mid-agent's run.
+				if (!config.sessionId || !config.threadId || !config.projectId || !config.tenantId) {
+					throw new Error('mid agent missing session scoping')
+				}
+				// Flip child session to active so it is a legal spawn parent.
+				const childSessionId = config.sessionId
+				const cs = await harness.store.getSession(childSessionId, config.tenantId)
+				if (cs && cs.status !== 'active') {
+					await harness.store.updateSession({ ...cs, status: 'active' }, config.tenantId)
+				}
+				const task2 = await manager.sendMessage(
+					{
+						agentId: 'leaf',
+						input: { messages: [], workingDirectory: '/tmp' },
+						parentSessionId: childSessionId,
+						tenantId: config.tenantId,
+						projectId: config.projectId,
+						parentActor: { kind: 'agent', agentId: 'mid' as never, tenantId: config.tenantId },
+					},
+					{
+						parentRunId: 'run_mid' as RunId,
+						parentAgentId: 'mid',
+						parentAbortController: new AbortController(),
+						depth: 1,
+						budgetTracker: { total: 10_000, remaining: 10_000 },
+						tenantId: config.tenantId,
+						threadId: config.threadId,
+						sessionId: childSessionId,
+						projectId: config.projectId,
+						parentActor: { kind: 'agent', agentId: 'mid' as never, tenantId: config.tenantId },
+					},
+					(ev) => {
+						nestedEventsCaptured.push(ev)
+					},
+				)
+				await manager.waitForCompletion(task2.taskId)
+
+				return {
+					runId: 'run_mid_result' as RunId,
+					status: 'completed',
+					usage: { ...EMPTY_TOKEN_USAGE },
+					cost: { ...ZERO_COST },
+					iterations: 1,
+					durationMs: 1,
+					messages: [createAssistantMessage('mid done')],
+					result: 'mid done',
+				}
+			},
+		)
+
+		harness.registry.register(buildDefinition(leafAgent))
+		harness.registry.register(buildDefinition(midAgent))
+
+		const outerCaptured: RunEvent[] = []
+		const task = await harness.manager.sendMessage(
+			buildSendMessageOptions({
+				agentId: 'mid',
+				parentSessionId: session.id,
+				projectId: project.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			buildTaskContext({
+				sessionId: session.id,
+				projectId: project.id,
+				threadId: thread.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			(ev) => {
+				outerCaptured.push(ev)
+			},
+		)
+		await harness.manager.waitForCompletion(task.taskId)
+
+		// Outer capture has level-1 events with rootSessionId === session.id,
+		// depth 1. The nested capture has level-2 events with rootSessionId
+		// also === session.id (the whole tree shares a root) and depth 2.
+		const outerLineages = outerCaptured
+			.filter((e) => 'lineage' in e && e.lineage)
+			.map((e) => {
+				const l = (e as unknown as { lineage: { rootSessionId: string; depth: number } }).lineage
+				return { rootSessionId: l.rootSessionId, depth: l.depth }
+			})
+		expect(outerLineages.length).toBeGreaterThan(0)
+		for (const l of outerLineages) {
+			expect(l.rootSessionId).toBe(session.id)
+			expect(l.depth).toBe(1)
+		}
+
+		// Nested level-2 events: same rootSessionId, depth 2.
+		const nestedLineages = nestedEventsCaptured
+			.filter((e) => 'lineage' in e && e.lineage)
+			.map((e) => {
+				const l = (e as unknown as { lineage: { rootSessionId: string; depth: number } }).lineage
+				return { rootSessionId: l.rootSessionId, depth: l.depth }
+			})
+		expect(nestedLineages.length).toBeGreaterThan(0)
+		for (const l of nestedLineages) {
+			expect(l.rootSessionId).toBe(session.id)
+			expect(l.depth).toBe(2)
+		}
+	})
+
+	it('self vs tree depth filter: outer listener sees only its session events; nested listener sees its own tree', async () => {
+		// The subscribe-time depth filter is implemented at the listener
+		// injection seam — the parent passes a listener that captures events
+		// from its own sendMessage call. A nested child's sendMessage receives
+		// its own listener — the outer listener does NOT see the nested
+		// listener's events (no cross-contamination).
+		const harness = buildHarness()
+		const { project, thread, session, actor } = await seedActiveParent(harness)
+
+		const outerCaptured: RunEvent[] = []
+		const nestedCaptured: RunEvent[] = []
+
+		const leafAgent = buildAgent('leaf', 'leaf')
+		const midAgent = buildAgentCustom(
+			'mid',
+			async (_input: AgentInput, config: BaseAgentConfig): Promise<BaseAgentResult> => {
+				if (!config.sessionId || !config.threadId || !config.projectId || !config.tenantId) {
+					throw new Error('mid missing scope')
+				}
+				const cs = await harness.store.getSession(config.sessionId, config.tenantId)
+				if (cs && cs.status !== 'active') {
+					await harness.store.updateSession({ ...cs, status: 'active' }, config.tenantId)
+				}
+				const inner = await harness.manager.sendMessage(
+					{
+						agentId: 'leaf',
+						input: { messages: [], workingDirectory: '/tmp' },
+						parentSessionId: config.sessionId,
+						tenantId: config.tenantId,
+						projectId: config.projectId,
+						parentActor: {
+							kind: 'agent',
+							agentId: 'mid' as never,
+							tenantId: config.tenantId,
+						},
+					},
+					{
+						parentRunId: 'run_mid_inner' as RunId,
+						parentAgentId: 'mid',
+						parentAbortController: new AbortController(),
+						depth: 1,
+						budgetTracker: { total: 10_000, remaining: 10_000 },
+						tenantId: config.tenantId,
+						threadId: config.threadId,
+						sessionId: config.sessionId,
+						projectId: config.projectId,
+						parentActor: {
+							kind: 'agent',
+							agentId: 'mid' as never,
+							tenantId: config.tenantId,
+						},
+					},
+					(ev) => {
+						nestedCaptured.push(ev)
+					},
+				)
+				await harness.manager.waitForCompletion(inner.taskId)
+				return {
+					runId: 'run_mid_done' as RunId,
+					status: 'completed',
+					usage: { ...EMPTY_TOKEN_USAGE },
+					cost: { ...ZERO_COST },
+					iterations: 1,
+					durationMs: 1,
+					messages: [createAssistantMessage('mid')],
+					result: 'mid',
+				}
+			},
+		)
+
+		harness.registry.register(buildDefinition(leafAgent))
+		harness.registry.register(buildDefinition(midAgent))
+
+		const task = await harness.manager.sendMessage(
+			buildSendMessageOptions({
+				agentId: 'mid',
+				parentSessionId: session.id,
+				projectId: project.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			buildTaskContext({
+				sessionId: session.id,
+				projectId: project.id,
+				threadId: thread.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			(ev) => {
+				outerCaptured.push(ev)
+			},
+		)
+		await harness.manager.waitForCompletion(task.taskId)
+
+		// Outer only sees its own spawn events (depth 1).
+		const outerSpawnedDepths = outerCaptured
+			.filter((e) => e.type === 'subsession_spawned')
+			.map((e) => ('lineage' in e && e.lineage ? e.lineage.depth : -1))
+		expect(outerSpawnedDepths).toEqual([1])
+
+		// Nested listener only sees its own spawn events (depth 2).
+		const nestedSpawnedDepths = nestedCaptured
+			.filter((e) => e.type === 'subsession_spawned')
+			.map((e) => ('lineage' in e && e.lineage ? e.lineage.depth : -1))
+		expect(nestedSpawnedDepths).toEqual([2])
+
+		// Cross-contamination sentinel: outer listener MUST NOT contain any
+		// depth-2 events (those belong to the nested scope).
+		const outerDepths = outerCaptured
+			.filter((e) => 'lineage' in e && e.lineage)
+			.map((e) => ('lineage' in e && e.lineage ? e.lineage.depth : -1))
+		expect(outerDepths.every((d) => d === 1)).toBe(true)
+	})
+
+	it('run_started and other core RunEvents also carry schemaVersion: 2 when stamped by the child listener wrapper', async () => {
+		// The listener wrapper in `manager/agent/lifecycle.ts#wrapChildListener`
+		// stamps `schemaVersion: 2` + `lineage` on EVERY event emitted inside
+		// the child's run. Core events that pass through the wrapped listener
+		// therefore inherit the envelope even though they have no lineage in
+		// their own type definition.
+		const harness = buildHarness()
+		const { project, thread, session, actor } = await seedActiveParent(harness)
+
+		const leafAgent = buildAgentCustom(
+			'leaf-emit',
+			async (_i, _c, listener): Promise<BaseAgentResult> => {
+				// Emit a core event inside the child's run via the listener passed in.
+				await listener?.({
+					type: 'run_started',
+					runId: 'run_child_inner' as RunId,
+				})
+				return {
+					runId: 'run_child_inner' as RunId,
+					status: 'completed',
+					usage: { ...EMPTY_TOKEN_USAGE },
+					cost: { ...ZERO_COST },
+					iterations: 1,
+					durationMs: 1,
+					messages: [createAssistantMessage('done')],
+					result: 'done',
+				}
+			},
+		)
+		harness.registry.register(buildDefinition(leafAgent))
+
+		const captured: RunEvent[] = []
+		const task = await harness.manager.sendMessage(
+			buildSendMessageOptions({
+				agentId: 'leaf-emit',
+				parentSessionId: session.id,
+				projectId: project.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			buildTaskContext({
+				sessionId: session.id,
+				projectId: project.id,
+				threadId: thread.id,
+				tenantId: DEFAULT_TENANT,
+				parentActor: actor,
+			}),
+			(ev) => {
+				captured.push(ev)
+			},
+		)
+		await harness.manager.waitForCompletion(task.taskId)
+
+		const runStarted = captured.find((e) => e.type === 'run_started')
+		expect(runStarted).toBeDefined()
+		if (runStarted && 'schemaVersion' in runStarted) {
+			expect(runStarted.schemaVersion).toBe(2)
+		}
+	})
+})

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

@@ -0,0 +1,271 @@
+/**
+ * Integration — broadcast handoff atomic fan-out + rollback wired through
+ * the real stack.
+ *
+ * Covers roadmap §5 invariants: §5.4 (source → `awaiting_merge` after
+ * successful commit), §6.2 (broadcast atomic rollback — zero orphan
+ * sub-sessions/sessions after rollback via `deleteSubSession` +
+ * `deleteSession`), §10.2 (broadcast.rollback event carries accurate
+ * partialState counts).
+ */
+
+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 { SessionId } from '../../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { generateHandoffId } from '../../../utils/id.js'
+import type { HandoffAssignment } from '../../handoff/assignment.js'
+import { type BroadcastHandoffDeps, executeBroadcastHandoff } from '../../handoff/broadcast.js'
+import { DefaultCapacityValidator } from '../../handoff/capacity.js'
+import type { HandoffEventSink } from '../../handoff/events.js'
+import type { ActorRef } from '../../hierarchy/actor.js'
+import type { ExecFile } from '../../workspace/git-worktree.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,
+	execOverride?: ExecFile,
+): {
+	deps: BroadcastHandoffDeps
+	events: HandoffEventSink & { onBroadcastRollback: ReturnType<typeof vi.fn> }
+} {
+	const exec: ExecFile = execOverride ?? (async () => okExec())
+	const driver = new GitWorktreeDriver({
+		repoRoot: '/repo',
+		logger: stubLogger(),
+		execFile: exec,
+	})
+	const workspaceRegistry = new WorkspaceBackendRegistry()
+	workspaceRegistry.register(driver)
+
+	const onBroadcastRollback = vi.fn()
+	const sink: HandoffEventSink = {
+		onLocked: vi.fn(),
+		onUnlocked: vi.fn(),
+		onCommitted: vi.fn(),
+		onBroadcastRollback,
+	}
+
+	return {
+		deps: {
+			store,
+			workspaceRegistry,
+			capacity: new DefaultCapacityValidator(store),
+			events: sink,
+			threadManager: new ThreadManager({ threadStore, sessionStore: store }),
+		},
+		events: { ...sink, onBroadcastRollback },
+	}
+}
+
+function buildAssignments(
+	sourceSessionId: SessionId,
+	projectId: ProjectId,
+	threadId: ThreadId,
+	recipients: ActorRef[],
+	broadcastId = 'bc_integration',
+	expectedOwnerVersion = 0,
+): HandoffAssignment[] {
+	return recipients.map((recipientActor) => ({
+		id: generateHandoffId(),
+		mode: 'broadcast' as const,
+		sourceSessionId,
+		tenantId: DEFAULT_TENANT,
+		threadId,
+		projectId,
+		sourceActor: userActor('usr_source'),
+		recipientActor,
+		expectedOwnerVersion,
+		broadcastId,
+		createdAt: new Date('2026-04-17'),
+	}))
+}
+
+describe('Integration — broadcast handoff E2E', () => {
+	it('happy: 3-recipient fan-out → each recipient has isolated worktree + source reaches awaiting_merge', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'bc-happy' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'bc-happy' },
+			DEFAULT_TENANT,
+		)
+		const source = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: userActor('usr_source') },
+			DEFAULT_TENANT,
+		)
+
+		// Track each `worktree add` call so we can assert each recipient got a
+		// distinct worktree path (isolation).
+		const addCalls: string[] = []
+		const exec: ExecFile = async (_file, args) => {
+			if (args.includes('add')) {
+				// args contains ['-C', ..., 'worktree', 'add', '-b', branch, path].
+				const path = args[args.length - 1]
+				if (typeof path === 'string') addCalls.push(path)
+			}
+			return okExec()
+		}
+		const { deps } = buildDeps(store, threadStore, exec)
+
+		const recipients = [userActor('usr_bob'), userActor('usr_carol'), userActor('usr_dan')]
+		const assignments = buildAssignments(source.id, project.id, thread.id, recipients)
+
+		const outcomes = await executeBroadcastHandoff(deps, assignments, DEFAULT_TENANT)
+		expect(outcomes).toHaveLength(3)
+		expect(new Set(outcomes.map((o) => o.newSessionId)).size).toBe(3)
+		expect(new Set(outcomes.map((o) => o.workspaceId)).size).toBe(3)
+
+		// Each recipient landed on a distinct worktree path — isolation holds.
+		expect(new Set(addCalls).size).toBe(3)
+
+		// §5.4: source transitions to awaiting_merge post-commit.
+		const reloaded = await store.getSession(source.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('awaiting_merge')
+
+		// Three children visible via getChildren.
+		const children = await store.getChildren(source.id, DEFAULT_TENANT)
+		expect(children).toHaveLength(3)
+		expect(children.every((c) => c.kind === 'user_handoff')).toBe(true)
+	})
+
+	it('rollback on 2nd-recipient provisioning failure: zero orphan records, partialState accurate', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'bc-rb' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'bc-rb' },
+			DEFAULT_TENANT,
+		)
+		const source = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: userActor('usr_source') },
+			DEFAULT_TENANT,
+		)
+
+		let addCount = 0
+		const exec: ExecFile = async (_file, args) => {
+			if (args.includes('add')) {
+				addCount += 1
+				if (addCount === 2) throw new Error('simulated fault on 2nd recipient')
+			}
+			return okExec()
+		}
+		const { deps, events } = buildDeps(store, threadStore, exec)
+
+		const assignments = buildAssignments(source.id, project.id, thread.id, [
+			userActor('usr_b'),
+			userActor('usr_c'),
+			userActor('usr_d'),
+		])
+
+		await expect(executeBroadcastHandoff(deps, assignments, DEFAULT_TENANT)).rejects.toThrow(
+			/Workspace backend git-worktree failed on create/,
+		)
+
+		// Phase 8 closed the Known Delta: rollback now calls deleteSubSession +
+		// deleteSession rather than flipping to 'archived'. Zero orphan
+		// sub-session records remain.
+		const children = await store.getChildren(source.id, DEFAULT_TENANT)
+		expect(children).toHaveLength(0)
+
+		// Source reverted to idle with original ownerVersion.
+		const reloaded = await store.getSession(source.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+		expect(reloaded?.ownerVersion).toBe(0)
+
+		// onBroadcastRollback emitted with accurate counts.
+		expect(events.onBroadcastRollback).toHaveBeenCalledTimes(1)
+		const rollbackCall = events.onBroadcastRollback.mock.calls[0]?.[0] as
+			| {
+					partialState: {
+						worktreesProvisioned: number
+						subsessionsCreated: number
+						assignmentsWritten: number
+					}
+			  }
+			| undefined
+		expect(rollbackCall?.partialState.worktreesProvisioned).toBe(1)
+		expect(rollbackCall?.partialState.subsessionsCreated).toBe(1)
+		expect(rollbackCall?.partialState.assignmentsWritten).toBe(1)
+	})
+
+	it('source transitions to awaiting_merge + retains currentActor as coordinator (§5.4)', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'coord' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'coord' },
+			DEFAULT_TENANT,
+		)
+		const coordinator = userActor('usr_source')
+		const source = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: coordinator },
+			DEFAULT_TENANT,
+		)
+
+		const { deps } = buildDeps(store, threadStore)
+		const assignments = buildAssignments(source.id, project.id, thread.id, [
+			userActor('usr_b'),
+			userActor('usr_c'),
+		])
+
+		await executeBroadcastHandoff(deps, assignments, DEFAULT_TENANT)
+
+		const reloaded = await store.getSession(source.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('awaiting_merge')
+		// Coordinator retained as current actor (§5.4).
+		expect(reloaded?.currentActor).toEqual(coordinator)
+		expect(reloaded?.ownerVersion).toBe(1)
+	})
+
+	it('all recipients get isolated worktrees — zero path collisions even under N=8', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'iso' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'iso' },
+			DEFAULT_TENANT,
+		)
+		const source = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: userActor('usr_source') },
+			DEFAULT_TENANT,
+		)
+
+		const seenPaths = new Set<string>()
+		const exec: ExecFile = async (_file, args) => {
+			if (args.includes('add')) {
+				const path = args[args.length - 1]
+				if (typeof path === 'string') {
+					if (seenPaths.has(path)) throw new Error(`path collision: ${path}`)
+					seenPaths.add(path)
+				}
+			}
+			return okExec()
+		}
+		const { deps } = buildDeps(store, threadStore, exec)
+
+		const recipients = Array.from({ length: 8 }, (_, i) => userActor(`usr_${i}`))
+		const assignments = buildAssignments(source.id, project.id, thread.id, recipients)
+
+		const outcomes = await executeBroadcastHandoff(deps, assignments, DEFAULT_TENANT)
+		expect(outcomes).toHaveLength(8)
+		expect(seenPaths.size).toBe(8)
+	})
+})