@namzu/sdk 0.2.0 → 0.3.0

package/src/runtime/query/context.ts

@@ -11,29 +11,27 @@ import {
 import { DefaultPathBuilder, type PathBuilder } from '../../session/workspace/path-builder.js'
 import { ActivityStore } from '../../store/activity/memory.js'
 import { type ActivityTrackingConfig, resolveActivityTracking } from '../../types/activity/index.js'
-import type { RunId, SessionId, TenantId, ThreadId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { AgentRunConfig } from '../../types/run/index.js'
-import type { ProjectId } from '../../types/session/ids.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import type { ModelPricing } from '../../utils/cost.js'
 import { generateRunId } from '../../utils/id.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 
 /**
- * Config accepted by {@link RunContextFactory.build}. Phase 6 promotes
- * `sessionId`, `projectId`, and `tenantId` to required — runs are scoped
- * under a Session within a Project within a Tenant (session-hierarchy.md
- * §12.1). `threadId` is retained only as a deprecated compat alias of
- * `projectId` — consumers can still pass it, but no new path layout honors it.
+ * Config accepted by {@link RunContextFactory.build}. `sessionId`,
+ * `threadId`, `projectId`, and `tenantId` are required — runs carry the full
+ * five-layer scope (Tenant → Project → Thread → Session → Run) per
+ * Convention #17.
  *
  * `pathBuilder` is optional; when absent a {@link DefaultPathBuilder} is
- * constructed against `{workingDirectory}/.namzu` — no more hardcoded
- * `.namzu/threads` path.
+ * constructed against `{workingDirectory}/.namzu`.
  *
- * Phase 7 adds `filesystemMigrator` + `migrationSink`. These are also
- * optional; when absent a {@link DefaultFilesystemMigrator} wired to the
+ * `filesystemMigrator` + `migrationSink` are optional; when absent a
+ * {@link DefaultFilesystemMigrator} wired to the
  * {@link NOOP_FILESYSTEM_MIGRATION_SINK} is used. Migration runs once per
  * process via {@link RunContextFactory.ensureMigrated}; the static `build`
  * method stays synchronous so existing call sites are not broken — async
@@ -51,6 +49,7 @@ export interface RunContextConfig {
 	signal?: AbortSignal
 
 	sessionId: SessionId
+	threadId: ThreadId
 	projectId: ProjectId
 	tenantId: TenantId
 
@@ -73,21 +72,13 @@ export interface RunContextConfig {
 	depth?: number
 }
 
-/**
- * Result of {@link RunContextFactory.build}. `threadId` remains as a
- * deprecated read-only mirror of `projectId` for consumers still referencing
- * the old name — scheduled for removal in 0.3.0 (session-hierarchy.md §13.1).
- */
+/** Result of {@link RunContextFactory.build}. */
 export interface RunContext {
 	runId: RunId
 	sessionId: SessionId
+	threadId: ThreadId
 	projectId: ProjectId
 	tenantId: TenantId
-	/**
-	 * @deprecated Mirrors `projectId` — remove when callers migrate off the
-	 * legacy name.
-	 */
-	threadId: ThreadId
 	runMgr: RunPersistence
 	activityStore: ActivityStore
 	planManager: PlanManager
@@ -156,6 +147,7 @@ export class RunContextFactory {
 			agent: config.agentName,
 			runId,
 			sessionId: config.sessionId,
+			threadId: config.threadId,
 			projectId: config.projectId,
 			tenantId: config.tenantId,
 		})
@@ -170,6 +162,7 @@ export class RunContextFactory {
 			pricing: config.pricing,
 			log,
 			sessionId: config.sessionId,
+			threadId: config.threadId,
 			tenantId: config.tenantId,
 			projectId: config.projectId,
 			parentRunId: config.parentRunId,
@@ -183,9 +176,9 @@ export class RunContextFactory {
 		return {
 			runId,
 			sessionId: config.sessionId,
+			threadId: config.threadId,
 			projectId: config.projectId,
 			tenantId: config.tenantId,
-			threadId: config.projectId as ThreadId,
 			runMgr,
 			activityStore,
 			planManager,

package/src/runtime/query/index.ts

@@ -21,7 +21,7 @@ import {
 	type ResumeHandler,
 	autoApproveHandler,
 } from '../../types/hitl/index.js'
-import type { RunId, SessionId, TenantId, ThreadId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import { type Message, createSystemMessage } from '../../types/message/index.js'
 import type { AgentPersona } from '../../types/persona/index.js'
@@ -29,7 +29,7 @@ import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
 import type { AgentRun, AgentRunConfig, RunEvent, RunEventListener } from '../../types/run/index.js'
 import type { Sandbox, SandboxProvider } from '../../types/sandbox/index.js'
-import type { ProjectId } from '../../types/session/ids.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import type { Skill } from '../../types/skills/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
@@ -67,30 +67,28 @@ export interface QueryParams {
 	resumeHandler: ResumeHandler
 	resumeFromCheckpoint?: CheckpointId
 
+	/** Session scope for the run. Required — every run is attributed to a Session. */
+	sessionId: SessionId
+
 	/**
-	 * Session scope for the run. Required in 0.2.0 — every run is attributed to
-	 * a Session (session-hierarchy.md §12.1).
+	 * Topic the Session lives under. Required in 0.3.0 — every run carries
+	 * the full five-layer scope (Tenant → Project → Thread → Session →
+	 * Run). Denormalized from `session.threadId`; callers build this
+	 * alongside `sessionId` so the query pipeline never needs a second
+	 * SessionStore round-trip to recover it.
 	 */
-	sessionId: SessionId
+	threadId: ThreadId
 
 	/** Long-lived goal scope for the run. Required. */
 	projectId: ProjectId
 
-	/** Isolation boundary. Required. */
+	/** Isolation boundary (Convention #17). Required. */
 	tenantId: TenantId
 
-	/**
-	 * @deprecated Pass `projectId` instead. When both are present, `projectId`
-	 * wins. During the 0.2.x migration window a caller supplying only
-	 * `threadId` must also supply `projectId` — the kernel no longer infers
-	 * `projectId` from a bare `threadId` on the QueryParams shape.
-	 */
-	threadId?: ThreadId
-
 	/**
 	 * Optional path layout override. Defaults to a {@link DefaultPathBuilder}
-	 * rooted at `{workingDirectory}/.namzu` (§13.4). Phase 7 wires first-call
-	 * filesystem migration onto this same entry point.
+	 * rooted at `{workingDirectory}/.namzu`. First-call filesystem migration
+	 * runs on this same entry point.
 	 */
 	pathBuilder?: PathBuilder
 
@@ -158,6 +156,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Agen
 		messages: params.messages,
 		signal: params.signal,
 		sessionId: params.sessionId,
+		threadId: params.threadId,
 		projectId: params.projectId,
 		tenantId: params.tenantId,
 		pathBuilder: params.pathBuilder,

package/src/session/__tests__/integration/_fixtures.ts

@@ -15,8 +15,10 @@
 import { vi } from 'vitest'
 import { EMPTY_TOKEN_USAGE } from '../../../constants/limits.js'
 import { AgentManager } from '../../../manager/agent/lifecycle.js'
+import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { AgentRegistry } from '../../../registry/agent/definitions.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type {
 	AgentCapabilities,
 	AgentInput,
@@ -28,7 +30,7 @@ import type { AgentDefinition } from '../../../types/agent/factory.js'
 import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/task.js'
 import type { AgentId, RunId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createAssistantMessage } from '../../../types/message/index.js'
-import type { ProjectId, SummaryId } from '../../../types/session/ids.js'
+import type { ProjectId, SummaryId, ThreadId } from '../../../types/session/ids.js'
 import { ZERO_COST } from '../../../utils/cost.js'
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
 import type { ActorRef } from '../../hierarchy/actor.js'
@@ -149,6 +151,8 @@ export function buildDefinition(agent: Agent<BaseAgentConfig, BaseAgentResult>):
 
 export interface IntegrationHarness {
 	readonly store: InMemorySessionStore
+	readonly threadStore: InMemoryThreadStore
+	readonly threadManager: ThreadManager
 	readonly registry: AgentRegistry
 	readonly manager: AgentManager
 	readonly materializer: SessionSummaryMaterializer
@@ -178,6 +182,7 @@ export interface IntegrationHarnessOptions {
 export function buildHarness(options: IntegrationHarnessOptions = {}): IntegrationHarness {
 	const tenantId = options.tenantId ?? DEFAULT_TENANT
 	const store = new InMemorySessionStore()
+	const threadStore = new InMemoryThreadStore()
 
 	const workspaceRegistry = new WorkspaceBackendRegistry()
 	if (options.withWorktreeDriver !== false) {
@@ -200,25 +205,42 @@ export function buildHarness(options: IntegrationHarnessOptions = {}): Integrati
 	})
 
 	const capacity = new DefaultCapacityValidator(store)
+	const threadManager = new ThreadManager({ threadStore, sessionStore: store })
 	const registry = new AgentRegistry()
 	const manager = new AgentManager(registry, undefined, {
 		sessionStore: store,
 		summaryMaterializer: materializer,
 		workspaceRegistry,
 		capacity,
+		threadManager,
 	})
 
-	return { store, registry, manager, materializer, workspaceRegistry, capacity, tenantId }
+	return {
+		store,
+		threadStore,
+		threadManager,
+		registry,
+		manager,
+		materializer,
+		workspaceRegistry,
+		capacity,
+		tenantId,
+	}
 }
 
 /**
- * Seeds a Tenant → Project → Session triple and flips the session into
- * `active` so it is a legal spawn parent. Returns the project + active
- * session for the caller to drive spawns against.
+ * Seeds a Tenant → Project → Thread → Session quadruple and flips the session
+ * into `active` so it is a legal spawn parent. Returns the project, thread,
+ * and active session for the caller to drive spawns against.
  */
 export async function seedActiveParent(
 	harness: IntegrationHarness,
-	options?: { actor?: ActorRef; projectName?: string; tenantId?: TenantId },
+	options?: {
+		actor?: ActorRef
+		projectName?: string
+		tenantId?: TenantId
+		threadTitle?: string
+	},
 ) {
 	const tenantId = options?.tenantId ?? harness.tenantId
 	const actor: ActorRef = options?.actor ?? userActor('usr_root', tenantId)
@@ -226,12 +248,16 @@ export async function seedActiveParent(
 		{ tenantId, name: options?.projectName ?? 'integration-project' },
 		tenantId,
 	)
+	const thread = await harness.threadStore.createThread(
+		{ projectId: project.id, title: options?.threadTitle ?? 'default' },
+		tenantId,
+	)
 	const session = await harness.store.createSession(
-		{ projectId: project.id, currentActor: actor },
+		{ threadId: thread.id, projectId: project.id, currentActor: actor },
 		tenantId,
 	)
 	await harness.store.updateSession({ ...session, status: 'active' as Session['status'] }, tenantId)
-	return { project, session, actor }
+	return { project, thread, session, actor }
 }
 
 /**
@@ -242,6 +268,7 @@ export async function seedActiveParent(
 export function buildTaskContext(params: {
 	sessionId: SessionId
 	projectId: ProjectId
+	threadId: ThreadId
 	tenantId: TenantId
 	parentActor: ActorRef
 	depth?: number
@@ -258,6 +285,7 @@ export function buildTaskContext(params: {
 			remaining: params.budget ?? 100_000,
 		},
 		tenantId: params.tenantId,
+		threadId: params.threadId,
 		sessionId: params.sessionId,
 		projectId: params.projectId,
 		parentActor: params.parentActor,

package/src/session/__tests__/integration/archive-gate.test.ts

@@ -0,0 +1,288 @@
+/**
+ * Integration — Thread archive gate enforced at session-creation ingress
+ * sites (Phase 2.6).
+ *
+ * The Phase 2.5 commit flagged this as a known gap:
+ *   > spawn and handoff paths do not yet invoke `ThreadManager.requireOpen`
+ *   > before creating a child session. Until they do, the archive invariant
+ *   > is best-effort.
+ *
+ * Phase 2.6 wires `requireOpen` into `AgentManager.provisionSpawn` + both
+ * handoff flows. These tests drive the archived-thread-then-attempt-creation
+ * scenarios end-to-end against the real stack.
+ */
+
+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 { AgentId, RunId, UserId } from '../../../types/ids/index.js'
+import { generateHandoffId } from '../../../utils/id.js'
+import { ThreadClosedError } from '../../errors.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 SingleHandoffDeps, executeSingleHandoff } from '../../handoff/single.js'
+import type { ActorRef } from '../../hierarchy/actor.js'
+import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
+import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
+import {
+	DEFAULT_TENANT,
+	buildAgent,
+	buildDefinition,
+	buildHarness,
+	buildSendMessageOptions,
+	buildTaskContext,
+	okExec,
+	seedActiveParent,
+	stubLogger,
+	userActor,
+} from './_fixtures.js'
+
+describe('Integration — archive gate (Phase 2.6)', () => {
+	it('AgentManager spawn: rejects with ThreadClosedError when parent thread is archived', async () => {
+		const harness = buildHarness()
+		const { project, thread, session, actor } = await seedActiveParent(harness)
+
+		// Archive the thread via the manager so the invariant is enforced — no
+		// in-flight sessions under this thread, so archive succeeds.
+		await harness.store.updateSession({ ...session, status: 'idle' }, DEFAULT_TENANT)
+		await harness.threadManager.archive(thread.id, DEFAULT_TENANT)
+		// Flip session back to active so the spawn's capacity path reaches
+		// provisionSpawn (the archive gate should still reject).
+		await harness.store.updateSession({ ...session, status: 'active' }, DEFAULT_TENANT)
+
+		harness.registry.register(buildDefinition(buildAgent('worker')))
+
+		await expect(
+			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,
+				}),
+			),
+		).rejects.toBeInstanceOf(ThreadClosedError)
+
+		// Archive invariant held: no new child sessions under the archived thread.
+		const underThread = await harness.store.listSessions(thread.id, DEFAULT_TENANT)
+		expect(underThread).toHaveLength(1)
+		expect(underThread[0]?.id).toBe(session.id)
+	})
+
+	it('Single handoff: rejects with ThreadClosedError when thread is archived (before CAS lock)', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'archive-single' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'archive-single' },
+			DEFAULT_TENANT,
+		)
+		const sourceActor: ActorRef = {
+			kind: 'user',
+			userId: 'usr_source' as UserId,
+			tenantId: DEFAULT_TENANT,
+		}
+		const session = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: sourceActor },
+			DEFAULT_TENANT,
+		)
+
+		// Archive the thread directly — session is idle, so archive precondition
+		// holds via listSessions.
+		const threadManager = new ThreadManager({ threadStore, sessionStore: store })
+		await threadManager.archive(thread.id, DEFAULT_TENANT)
+
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: async () => okExec(),
+		})
+		const workspaceRegistry = new WorkspaceBackendRegistry()
+		workspaceRegistry.register(driver)
+
+		const events: HandoffEventSink = {
+			onLocked: vi.fn(),
+			onUnlocked: vi.fn(),
+			onCommitted: vi.fn(),
+			onBroadcastRollback: vi.fn(),
+		}
+		const deps: SingleHandoffDeps = {
+			store,
+			workspaceRegistry,
+			capacity: new DefaultCapacityValidator(store),
+			events,
+			threadManager,
+		}
+
+		const assignment: HandoffAssignment = {
+			id: generateHandoffId(),
+			mode: 'single',
+			sourceSessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			threadId: thread.id,
+			projectId: project.id,
+			sourceActor,
+			recipientActor: userActor('usr_target'),
+			expectedOwnerVersion: 0,
+			createdAt: new Date('2026-04-19'),
+		}
+
+		await expect(executeSingleHandoff(deps, assignment, DEFAULT_TENANT)).rejects.toBeInstanceOf(
+			ThreadClosedError,
+		)
+
+		// Critical: source session must still be idle (lock never acquired).
+		const reloaded = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+		expect(reloaded?.ownerVersion).toBe(0)
+		expect(events.onLocked).not.toHaveBeenCalled()
+	})
+
+	it('Broadcast handoff: rejects with ThreadClosedError when thread is archived (no CAS, no worktrees)', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'archive-bc' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'archive-bc' },
+			DEFAULT_TENANT,
+		)
+		const source = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: userActor('usr_source') },
+			DEFAULT_TENANT,
+		)
+
+		const threadManager = new ThreadManager({ threadStore, sessionStore: store })
+		await threadManager.archive(thread.id, DEFAULT_TENANT)
+
+		let worktreeAdds = 0
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: async (_file, args) => {
+				if (args.includes('add')) worktreeAdds += 1
+				return okExec()
+			},
+		})
+		const workspaceRegistry = new WorkspaceBackendRegistry()
+		workspaceRegistry.register(driver)
+
+		const events: HandoffEventSink = {
+			onLocked: vi.fn(),
+			onUnlocked: vi.fn(),
+			onCommitted: vi.fn(),
+			onBroadcastRollback: vi.fn(),
+		}
+		const deps: BroadcastHandoffDeps = {
+			store,
+			workspaceRegistry,
+			capacity: new DefaultCapacityValidator(store),
+			events,
+			threadManager,
+		}
+
+		const assignments: HandoffAssignment[] = [userActor('usr_b'), userActor('usr_c')].map(
+			(recipientActor) => ({
+				id: generateHandoffId(),
+				mode: 'broadcast' as const,
+				sourceSessionId: source.id,
+				tenantId: DEFAULT_TENANT,
+				threadId: thread.id,
+				projectId: project.id,
+				sourceActor: userActor('usr_source'),
+				recipientActor,
+				expectedOwnerVersion: 0,
+				broadcastId: 'bc_archive',
+				createdAt: new Date('2026-04-19'),
+			}),
+		)
+
+		await expect(executeBroadcastHandoff(deps, assignments, DEFAULT_TENANT)).rejects.toBeInstanceOf(
+			ThreadClosedError,
+		)
+
+		// Source never locked, no worktrees provisioned, no rollback event —
+		// the archive gate short-circuited before any side-effect landed.
+		const reloaded = await store.getSession(source.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+		expect(reloaded?.ownerVersion).toBe(0)
+		expect(events.onLocked).not.toHaveBeenCalled()
+		expect(events.onBroadcastRollback).not.toHaveBeenCalled()
+		expect(worktreeAdds).toBe(0)
+	})
+
+	it('Phase 2.6 closure: post-archive spawn via AgentManager rejects (kernel ingress path gated)', async () => {
+		// End-to-end proof that the production ingress path honors the
+		// archive status. Direct `SessionStore.createSession` / `updateSession`
+		// remain ungated at the store layer (by design — the store has no
+		// cross-store awareness), so this test exercises the manager path,
+		// not the store boundary.
+		const harness = buildHarness()
+		const { project, thread, session } = await seedActiveParent(harness)
+
+		await harness.store.updateSession({ ...session, status: 'idle' }, DEFAULT_TENANT)
+		await harness.threadManager.archive(thread.id, DEFAULT_TENANT)
+
+		// Attempt to spawn directly via context threading (bypass the fixture
+		// builder to prove the gate trips from AgentManager, not from the
+		// fixture).
+		harness.registry.register(buildDefinition(buildAgent('leaker')))
+
+		const childActor: ActorRef = {
+			kind: 'agent',
+			agentId: 'leaker' as AgentId,
+			tenantId: DEFAULT_TENANT,
+		}
+
+		// Flip session to active again so capacity checks pass and the
+		// archive-gate is what fails — not an earlier guard.
+		await harness.store.updateSession({ ...session, status: 'active' }, DEFAULT_TENANT)
+
+		await expect(
+			harness.manager.sendMessage(
+				{
+					agentId: 'leaker',
+					input: { messages: [], workingDirectory: '/tmp' },
+					parentSessionId: session.id,
+					tenantId: DEFAULT_TENANT,
+					projectId: project.id,
+					parentActor: childActor,
+				},
+				{
+					parentRunId: 'run_post_archive' as RunId,
+					parentAgentId: 'supervisor',
+					parentAbortController: new AbortController(),
+					depth: 0,
+					budgetTracker: { total: 10_000, remaining: 10_000 },
+					tenantId: DEFAULT_TENANT,
+					threadId: thread.id,
+					sessionId: session.id,
+					projectId: project.id,
+					parentActor: childActor,
+				},
+			),
+		).rejects.toBeInstanceOf(ThreadClosedError)
+
+		// The gate tripped before any observable side effect — listSessions
+		// still shows only the original seeded session, not a smuggled child.
+		const underThread = await harness.store.listSessions(thread.id, DEFAULT_TENANT)
+		expect(underThread).toHaveLength(1)
+		expect(underThread[0]?.id).toBe(session.id)
+	})
+})

package/src/session/__tests__/integration/capacity-caps.test.ts

@@ -28,14 +28,18 @@ import {
 describe('Integration — capacity caps at spawn sites', () => {
 	it('spawn at depth 4 accepted; depth 5 rejected (default maxDelegationDepth=4)', async () => {
 		const harness = buildHarness()
-		const { project } = await seedActiveParent(harness)
+		const { project, thread } = await seedActiveParent(harness)
 
 		// Build a depth-4 ancestry chain under the project. Each layer flips to
 		// `active` so it is a legal spawn parent via the real AgentManager.
 		const chainActors: ActorRef[] = [userActor('usr_root')]
 		let parentSessionId = (
 			await harness.store.createSession(
-				{ projectId: project.id, currentActor: chainActors[0] ?? userActor('usr_root') },
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: chainActors[0] ?? userActor('usr_root'),
+				},
 				DEFAULT_TENANT,
 			)
 		).id
@@ -44,7 +48,7 @@ describe('Integration — capacity caps at spawn sites', () => {
 
 		for (let i = 0; i < 4; i++) {
 			const child = await harness.store.createSession(
-				{ projectId: project.id, currentActor: agentActor(`agt_${i}`) },
+				{ threadId: thread.id, projectId: project.id, currentActor: agentActor(`agt_${i}`) },
 				DEFAULT_TENANT,
 			)
 			await harness.store.createSubSession(
@@ -68,6 +72,7 @@ describe('Integration — capacity caps at spawn sites', () => {
 		const context = buildTaskContext({
 			sessionId: tail,
 			projectId: project.id,
+			threadId: thread.id,
 			tenantId: DEFAULT_TENANT,
 			parentActor: userActor('usr_root'),
 		})
@@ -86,12 +91,12 @@ describe('Integration — capacity caps at spawn sites', () => {
 
 	it('spawn at width 8 accepted; 9th sibling rejected (default maxDelegationWidth=8)', async () => {
 		const harness = buildHarness()
-		const { project, session, actor } = await seedActiveParent(harness)
+		const { project, thread, session, actor } = await seedActiveParent(harness)
 
 		// Seed 8 existing children directly through the store.
 		for (let i = 0; i < 8; i++) {
 			const child = await harness.store.createSession(
-				{ projectId: project.id, currentActor: agentActor(`agt_${i}`) },
+				{ threadId: thread.id, projectId: project.id, currentActor: agentActor(`agt_${i}`) },
 				DEFAULT_TENANT,
 			)
 			await harness.store.createSubSession(
@@ -110,6 +115,7 @@ describe('Integration — capacity caps at spawn sites', () => {
 		const context = buildTaskContext({
 			sessionId: session.id,
 			projectId: project.id,
+			threadId: thread.id,
 			tenantId: DEFAULT_TENANT,
 			parentActor: actor,
 		})
@@ -133,7 +139,7 @@ describe('Integration — capacity caps at spawn sites', () => {
 		// DefaultCapacityValidator(store) so it walks the actual persisted
 		// parent chain — confirms the wiring rather than a direct unit call.
 		const harness = buildHarness()
-		const { project, session, actor } = await seedActiveParent(harness)
+		const { project, thread, session, actor } = await seedActiveParent(harness)
 
 		harness.registry.register(buildDefinition(buildAgent('worker')))
 
@@ -142,6 +148,7 @@ describe('Integration — capacity caps at spawn sites', () => {
 		const context = buildTaskContext({
 			sessionId: session.id,
 			projectId: project.id,
+			threadId: thread.id,
 			tenantId: DEFAULT_TENANT,
 			parentActor: actor,
 		})