@namzu/sdk 0.2.0 → 0.4.0

package/src/session/handoff/single.ts

@@ -20,6 +20,7 @@
  *   9. Emit `onCommitted` with the new version.
  */
 
+import type { ThreadManager } from '../../manager/thread/lifecycle.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { SessionStore } from '../../types/session/store.js'
 import { TenantIsolationError } from '../errors.js'
@@ -64,6 +65,12 @@ export interface SingleHandoffDeps {
 	capacity: CapacityValidator
 	events: HandoffEventSink
 	runStatus?: RunStatusResolver
+	/**
+	 * Gate the recipient-session creation on the Thread being `'open'`.
+	 * Added in Phase 2.6 to mirror spawn — a handoff into an archived
+	 * Thread would otherwise undermine `ThreadManager.archive`.
+	 */
+	threadManager: ThreadManager
 }
 
 /**
@@ -85,6 +92,12 @@ export async function executeSingleHandoff(
 		})
 	}
 
+	// Thread archive gate (Phase 2.6) — runs FIRST so an archived thread
+	// fails fastest with `ThreadClosedError` rather than a lock rejection or
+	// capacity error. Checked BEFORE the CAS lock so a denied handoff leaves
+	// the source session untouched.
+	await deps.threadManager.requireOpen(assignment.threadId, tenantId)
+
 	// 1. Load source session + tenant check.
 	const source = await deps.store.getSession(assignment.sourceSessionId, tenantId)
 	if (!source) {
@@ -96,6 +109,11 @@ export async function executeSingleHandoff(
 			resource: `session(${source.id})`,
 		})
 	}
+	if (source.threadId !== assignment.threadId) {
+		throw new Error(
+			`Assignment threadId ${assignment.threadId} does not match source session threadId ${source.threadId}`,
+		)
+	}
 	if (source.projectId !== assignment.projectId) {
 		throw new Error(
 			`Assignment projectId ${assignment.projectId} does not match source session projectId ${source.projectId}`,
@@ -157,7 +175,11 @@ export async function executeSingleHandoff(
 		provisionedWorkspace = await driver.create({ label: `handoff-${assignment.id}` })
 
 		const recipientSession = await deps.store.createSession(
-			{ projectId: source.projectId, currentActor: assignment.recipientActor },
+			{
+				threadId: source.threadId,
+				projectId: source.projectId,
+				currentActor: assignment.recipientActor,
+			},
 			tenantId,
 		)
 		createdSessionId = recipientSession.id

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

@@ -1,11 +1,18 @@
 import { describe, expect, it } from 'vitest'
 import type { RunStatus } from '../../../types/run/status.js'
-import type { ProjectId, SessionId, TenantId, UserId } from '../../../types/session/ids.js'
+import type {
+	ProjectId,
+	SessionId,
+	TenantId,
+	ThreadId,
+	UserId,
+} from '../../../types/session/ids.js'
 import type { ActorRef } from '../actor.js'
 import { type Session, type SessionStatus, deriveStatus } from '../session.js'
 
 const tenant = 'tnt_a' as TenantId
 const project = 'prj_a' as ProjectId
+const thread = 'thd_a' as ThreadId
 
 function user(): ActorRef {
 	return { kind: 'user', userId: 'usr_a' as UserId, tenantId: tenant }
@@ -14,6 +21,7 @@ function user(): ActorRef {
 function makeSession(status: SessionStatus): Session {
 	return {
 		id: 'ses_a' as SessionId,
+		threadId: thread,
 		projectId: project,
 		tenantId: tenant,
 		status,

package/src/session/hierarchy/index.ts

@@ -5,6 +5,7 @@ export type { ActorRef, SystemRoleId } from './actor.js'
 export type { Lineage } from './lineage.js'
 export type { Tenant } from './tenant.js'
 export type { Project, ProjectConfig } from './project.js'
+export type { Thread, ThreadStatus } from './thread.js'
 export type { Session, SessionStatus } from './session.js'
 export { deriveStatus } from './session.js'
 export type {

package/src/session/hierarchy/session.ts

@@ -1,6 +1,6 @@
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { RunStatus } from '../../types/run/status.js'
-import type { ProjectId, WorkspaceId } from '../../types/session/ids.js'
+import type { ProjectId, ThreadId, WorkspaceId } from '../../types/session/ids.js'
 import type { ActorRef } from './actor.js'
 
 /**
@@ -21,15 +21,27 @@ export type SessionStatus =
 /**
  * Multi-turn work unit owned by exactly one {@link ActorRef} at a time.
  *
- * Fields derived from session-hierarchy.md §4.3:
+ * Scope identifiers:
+ *   - `threadId` — the topic-level {@link Thread} this Session lives under.
+ *     Set at creation, immutable; Sessions never move threads.
+ *   - `projectId` — the {@link Project} the owning Thread belongs to.
+ *     **Denormalized** from `thread.projectId` at creation time; immutable.
+ *     Kept on the Session record for ergonomic access (Project-scoped
+ *     consumers — handoff validators, archival, retention — would otherwise
+ *     need a second round-trip to ThreadStore on every read). This is NOT
+ *     a deprecated mirror of a fading field; it is a deliberate
+ *     denormalization of structurally-immutable derived data.
+ *
+ * Other invariants (session-hierarchy.md §4.3):
  *   - `previousActors` is append-only and publicly read-only; previous
- *     owners cannot write to the session again (Decision #3).
+ *     owners cannot write to the session again.
  *   - `ownerVersion` is the CAS counter for handoff (§6.1 / §6.2 / §6.4).
  *   - `workspaceId` is nullable for sessions whose workspace has not yet
  *     been provisioned (or has been torn down during archival).
  */
 export interface Session {
 	id: SessionId
+	threadId: ThreadId
 	projectId: ProjectId
 	tenantId: TenantId
 	status: SessionStatus

package/src/session/hierarchy/thread.ts

@@ -0,0 +1,55 @@
+import type { TenantId } from '../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+
+/**
+ * Lifecycle state of a Thread.
+ *
+ * - `open` — accepts new Sessions and new Runs under existing Sessions.
+ * - `archived` — read-only tombstone. No new Sessions may be created; existing
+ *   Sessions remain navigable. Transitioning `open → archived` requires that
+ *   no Session under the Thread is in a non-terminal state (guarded at the
+ *   store level by listing + status fan-in).
+ *
+ * There is no `active` variant — Thread does NOT derive status from its child
+ * Sessions the way a Session does from its Runs. Thread is a pure container
+ * (Phase 0 decision B.1: Thread is container-only, no message stream, no
+ * fan-in). Its status is an explicit owner action.
+ */
+export type ThreadStatus = 'open' | 'archived'
+
+/**
+ * Topic-level container sitting between {@link ProjectId Project} and
+ * {@link import('../../types/session/ids.js').SessionId Session} in the
+ * five-layer hierarchy (Project → Thread → Session → SubSession → Run).
+ *
+ * A Thread groups together many Sessions that address the same coherent
+ * topic or line-of-work within a Project (e.g. "auth refactor", "billing
+ * incident"). Sessions under the same Thread share Project-level shared
+ * resources (memory, vaults, knowledge bases) but have independent actor
+ * state, handoff history, and Run streams.
+ *
+ * Design §4 (`docs.local/sessions/ses_001-hierarchy-redesign/design.md`):
+ *   - Container only. No own message stream, no own Run stream. Messages
+ *     live in Sessions (Phase 0 decision B.1).
+ *   - `title` is a user-facing label. **Titles are NOT unique within a
+ *     Project.** Callers disambiguate by {@link ThreadId}; the title is
+ *     freeform display text. If a product surface needs uniqueness (e.g.
+ *     a human-typed slug), that constraint lives at the API layer, not in
+ *     the kernel.
+ *   - `ownerVersion` is the CAS counter for mutations — `updateThread` and
+ *     archival transitions require a matching version and reject
+ *     {@link StaleThreadError} on mismatch. Mirrors the
+ *     {@link import('./session.js').Session} handoff CAS pattern (§6.1).
+ *   - No fan-in `deriveStatus()` helper — status is owner-managed, not
+ *     Run-derived. This is the Thread-vs-Session contract boundary.
+ */
+export interface Thread {
+	id: ThreadId
+	projectId: ProjectId
+	tenantId: TenantId
+	title: string
+	status: ThreadStatus
+	ownerVersion: number
+	createdAt: Date
+	updatedAt: Date
+}

package/src/session/migration/id-prefix.ts

@@ -1,23 +1,18 @@
 /**
  * ID-prefix migration window — read-side compat for legacy `thd_*` IDs.
  *
- * Phase 1 already ships {@link parseThreadId} in `utils/id.ts` that accepts
- * either `thd_*` or `prj_*` silently. This module formalises the warning
- * emission path called out in session-hierarchy.md §13.3.1:
- *
- * | Version | Reader accepts      | Writer emits | Legacy read behaviour         |
- * |---------|---------------------|--------------|-------------------------------|
- * | 0.2.x   | `thd_*` AND `prj_*` | `prj_*` only | emits `MigrationWarning` once |
- * | 0.3.x   | `prj_*` only        | `prj_*` only | rejects `StalePrefixError`    |
- *
  * Consumers that touch raw legacy IDs (filesystem migrator, wire decoders,
  * CLI imports) route through {@link acceptLegacyThreadId} so the warning
  * signal is structured rather than ad-hoc console output (Convention #18).
  *
- * The `WINDOW_OPEN` constant is the single switch that flips this module
- * from soft-accept to hard-reject when 0.3.0 cuts. Convention #0: no silent
- * long-lived compat — the window is explicit, dated, and fails closed when
- * the clock runs out.
+ * | Window state | Reader accepts      | Writer emits | Legacy read behaviour         |
+ * |--------------|---------------------|--------------|-------------------------------|
+ * | OPEN (now)   | `thd_*` AND `prj_*` | `prj_*` only | emits `MigrationWarning` once |
+ * | CLOSED       | `prj_*` only        | `prj_*` only | rejects `StalePrefixError`    |
+ *
+ * The {@link WINDOW_OPEN} constant is the single switch that flips this
+ * module from soft-accept to hard-reject. Convention #0: no silent
+ * long-lived compat — the window is explicit and fails closed when closed.
  */
 
 import type { ProjectId } from '../../types/session/ids.js'

package/src/session/retention/__tests__/archive.test.ts

@@ -10,7 +10,7 @@ import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import type { AgentId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
-import type { WorkspaceId } from '../../../types/session/ids.js'
+import type { ThreadId, WorkspaceId } from '../../../types/session/ids.js'
 import {
 	ArchivalManager,
 	ArchiveNotConfiguredError,
@@ -18,6 +18,8 @@ import {
 } from '../archive.js'
 import { DiskArchiveBackend } from '../disk-backend.js'
 
+const TEST_THREAD_ID = 'thd_test' as ThreadId
+
 const tenantA = 'tnt_alpha' as TenantId
 
 function stubLogger() {
@@ -43,11 +45,11 @@ function agentActor(tenantId: TenantId): ActorRef {
 async function seedIdleSubSession(store: InMemorySessionStore) {
 	const project = await store.createProject({ tenantId: tenantA, name: 'p' }, tenantA)
 	const parent = await store.createSession(
-		{ projectId: project.id, currentActor: userActor(tenantA) },
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor(tenantA) },
 		tenantA,
 	)
 	const child = await store.createSession(
-		{ projectId: project.id, currentActor: agentActor(tenantA) },
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 		tenantA,
 	)
 	const sub = await store.createSubSession(

package/src/session/summary/__tests__/materialize.test.ts

@@ -3,7 +3,7 @@ import { TenantIsolationError } from '../../../session/errors.js'
 import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
-import type { SummaryId } from '../../../types/session/ids.js'
+import type { SummaryId, ThreadId } from '../../../types/session/ids.js'
 import type { DeliverableRef } from '../deliverable.js'
 import { SessionSummaryMaterializer } from '../materialize.js'
 import {
@@ -12,6 +12,8 @@ import {
 	SessionAlreadySummarizedError,
 } from '../ref.js'
 
+const TEST_THREAD_ID = 'thd_test' as ThreadId
+
 const tenantA = 'tnt_alpha' as TenantId
 const tenantB = 'tnt_beta' as TenantId
 
@@ -31,7 +33,7 @@ function makeSummaryIdGenerator(): () => SummaryId {
 async function seedActiveSession(store: InMemorySessionStore, tenantId: TenantId) {
 	const project = await store.createProject({ tenantId, name: 'p1' }, tenantId)
 	const session = await store.createSession(
-		{ projectId: project.id, currentActor: agentActor(tenantId) },
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantId) },
 		tenantId,
 	)
 	// Put the session into `active` so the materializer's status-flip behavior
@@ -232,7 +234,7 @@ describe('SessionSummaryMaterializer.materialize', () => {
 		const store = new InMemorySessionStore()
 		const project = await store.createProject({ tenantId: tenantA, name: 'p1' }, tenantA)
 		const session = await store.createSession(
-			{ projectId: project.id, currentActor: userActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor(tenantA) },
 			tenantA,
 		)
 		// session.status defaults to 'idle'
@@ -255,7 +257,7 @@ describe('SessionSummaryMaterializer.materialize', () => {
 		const store = new InMemorySessionStore()
 		const project = await store.createProject({ tenantId: tenantA, name: 'p1' }, tenantA)
 		const session = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		await store.updateSession({ ...session, status: 'failed' }, tenantA)

package/src/store/index.ts

@@ -10,9 +10,6 @@ export { InMemoryTaskStore } from './task/memory.js'
 export { DiskTaskStore } from './task/disk.js'
 export type { DiskTaskStoreConfig } from './task/disk.js'
 
-export { InMemoryConversationStore } from './conversation/memory.js'
-export type { InMemoryConversationStoreConfig } from './conversation/memory.js'
-
 export { InMemoryMemoryIndex } from './memory/index.js'
 export { InMemoryMemoryStore } from './memory/memory.js'
 export { DiskMemoryStore } from './memory/disk.js'

package/src/store/session/__tests__/disk.test.ts

@@ -23,7 +23,7 @@ function agentActor(tenantId: TenantId): ActorRef {
 async function seed(store: DiskSessionStore, tenantId: TenantId) {
 	const project = await store.createProject({ tenantId, name: 'p1' }, tenantId)
 	const session = await store.createSession(
-		{ projectId: project.id, currentActor: userActor(tenantId) },
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor(tenantId) },
 		tenantId,
 	)
 	return { project, session }
@@ -45,7 +45,7 @@ describe('DiskSessionStore', () => {
 	it('writes the canonical directory layout (projects/.../sessions/.../subsessions)', async () => {
 		const { project, session } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const sub = await store.createSubSession(
@@ -143,7 +143,7 @@ describe('DiskSessionStore', () => {
 	it('drill returns children and ancestry after a cold reload', async () => {
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		await store.createSubSession(
@@ -278,7 +278,7 @@ describe('DiskSessionStore', () => {
 	it('deleteSession rejects if sub-sessions are still attached', async () => {
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		await store.createSubSession(
@@ -297,7 +297,7 @@ describe('DiskSessionStore', () => {
 	it('deleteSubSession removes the sub-session directory and is idempotent', async () => {
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const sub = await store.createSubSession(
@@ -338,9 +338,60 @@ describe('DiskSessionStore', () => {
 
 		await expect(store.getSummary(session.id, tenantB)).rejects.toBeInstanceOf(TenantIsolationError)
 	})
+
+	describe('listSessions(threadId, tenantId)', () => {
+		const threadX = 'thd_x' as ThreadId
+		const threadY = 'thd_y' as ThreadId
+
+		it('returns [] when the projects root is empty', async () => {
+			// Fresh temp root — no projects directory yet.
+			expect(await store.listSessions(threadX, tenantA)).toEqual([])
+		})
+
+		it('filters by threadId and tenant; orders by createdAt ascending', async () => {
+			const project = await store.createProject({ tenantId: tenantA, name: 'p' }, tenantA)
+
+			const first = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			await new Promise((r) => setTimeout(r, 2))
+			const second = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			// Same project, different thread — must not appear.
+			await store.createSession(
+				{ threadId: threadY, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id)).toEqual([first.id, second.id])
+		})
+
+		it('skips cross-tenant sessions even when threadId matches', async () => {
+			const pA = await store.createProject({ tenantId: tenantA, name: 'pa' }, tenantA)
+			const pB = await store.createProject({ tenantId: tenantB, name: 'pb' }, tenantB)
+
+			const own = await store.createSession(
+				{ threadId: threadX, projectId: pA.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			await store.createSession(
+				{ threadId: threadX, projectId: pB.id, currentActor: userActor(tenantB) },
+				tenantB,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id)).toEqual([own.id])
+		})
+	})
 })
 
 import type { SessionSummaryRef } from '../../../session/summary/ref.js'
 // Import after use so tests are self-contained w.r.t. types we already use.
 import type { SessionId } from '../../../types/ids/index.js'
-import type { SummaryId } from '../../../types/session/ids.js'
+import type { SummaryId, ThreadId } from '../../../types/session/ids.js'
+
+const TEST_THREAD_ID = 'thd_test' as ThreadId

package/src/store/session/__tests__/memory.test.ts

@@ -4,8 +4,11 @@ import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import type { SubSession } from '../../../session/hierarchy/sub-session.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
+import type { ThreadId } from '../../../types/session/ids.js'
 import { InMemorySessionStore } from '../memory.js'
 
+const TEST_THREAD_ID = 'thd_test' as ThreadId
+
 function userActor(tenantId: TenantId): ActorRef {
 	return { kind: 'user', userId: 'usr_a' as UserId, tenantId }
 }
@@ -25,7 +28,7 @@ const tenantB = 'tnt_beta' as TenantId
 async function seed(store: InMemorySessionStore, tenantId: TenantId) {
 	const project = await store.createProject({ tenantId, name: 'p1' }, tenantId)
 	const session = await store.createSession(
-		{ projectId: project.id, currentActor: userActor(tenantId) },
+		{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: userActor(tenantId) },
 		tenantId,
 	)
 	return { project, session }
@@ -84,7 +87,7 @@ describe('InMemorySessionStore', () => {
 
 		// Create a child session + link via sub-session.
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const sub = await store.createSubSession(
@@ -139,7 +142,7 @@ describe('InMemorySessionStore', () => {
 		const { project: pB, session: rootB } = await seed(store, tenantB)
 
 		const childA = await store.createSession(
-			{ projectId: pA.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: pA.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		await store.createSubSession(
@@ -153,7 +156,7 @@ describe('InMemorySessionStore', () => {
 		)
 
 		const childB = await store.createSession(
-			{ projectId: pB.id, currentActor: agentActor(tenantB) },
+			{ threadId: TEST_THREAD_ID, projectId: pB.id, currentActor: agentActor(tenantB) },
 			tenantB,
 		)
 		await store.createSubSession(
@@ -186,7 +189,7 @@ describe('InMemorySessionStore', () => {
 		const store = new InMemorySessionStore()
 		const { project, session: rootA } = await seed(store, tenantA)
 		const sessionB = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 
@@ -235,7 +238,7 @@ describe('InMemorySessionStore', () => {
 		const store = new InMemorySessionStore()
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		await store.createSubSession(
@@ -265,7 +268,7 @@ describe('InMemorySessionStore', () => {
 		const store = new InMemorySessionStore()
 		const { project, session: root } = await seed(store, tenantA)
 		const child = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const sub = await store.createSubSession(
@@ -293,11 +296,11 @@ describe('InMemorySessionStore', () => {
 		const { project, session: root } = await seed(store, tenantA)
 
 		const c1 = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 		const c2 = await store.createSession(
-			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			{ threadId: TEST_THREAD_ID, projectId: project.id, currentActor: agentActor(tenantA) },
 			tenantA,
 		)
 
@@ -324,4 +327,76 @@ describe('InMemorySessionStore', () => {
 		const ids = children.map((s: SubSession) => s.id)
 		expect(new Set(ids)).toEqual(new Set([s1.id, s2.id]))
 	})
+
+	describe('listSessions(threadId, tenantId)', () => {
+		const threadX = 'thd_x' as ThreadId
+		const threadY = 'thd_y' as ThreadId
+
+		it('returns [] when the thread has no sessions', async () => {
+			const store = new InMemorySessionStore()
+			expect(await store.listSessions(threadX, tenantA)).toEqual([])
+		})
+
+		it('returns only sessions whose threadId matches, for the caller tenant', async () => {
+			const store = new InMemorySessionStore()
+			const project = await store.createProject({ tenantId: tenantA, name: 'p' }, tenantA)
+
+			const sX1 = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			const sX2 = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			// Same project, different thread — must not appear.
+			await store.createSession(
+				{ threadId: threadY, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id).sort()).toEqual([sX1.id, sX2.id].sort())
+		})
+
+		it('orders results by createdAt ascending', async () => {
+			const store = new InMemorySessionStore()
+			const project = await store.createProject({ tenantId: tenantA, name: 'p' }, tenantA)
+
+			const first = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			// Nudge clock for deterministic ordering; in-memory uses `new Date()`.
+			await new Promise((r) => setTimeout(r, 2))
+			const second = await store.createSession(
+				{ threadId: threadX, projectId: project.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id)).toEqual([first.id, second.id])
+		})
+
+		it('silently skips cross-tenant sessions sharing the same threadId', async () => {
+			// Thread ids are tenant-scoped in practice but nothing at the type
+			// level prevents the same string identifier being reused across
+			// tenants — the listing must filter by tenant without erroring.
+			const store = new InMemorySessionStore()
+			const pA = await store.createProject({ tenantId: tenantA, name: 'pa' }, tenantA)
+			const pB = await store.createProject({ tenantId: tenantB, name: 'pb' }, tenantB)
+
+			const own = await store.createSession(
+				{ threadId: threadX, projectId: pA.id, currentActor: userActor(tenantA) },
+				tenantA,
+			)
+			await store.createSession(
+				{ threadId: threadX, projectId: pB.id, currentActor: userActor(tenantB) },
+				tenantB,
+			)
+
+			const listed = await store.listSessions(threadX, tenantA)
+			expect(listed.map((s) => s.id)).toEqual([own.id])
+		})
+	})
 })