@namzu/sdk 12.2.0 → 13.0.0

package/src/manager/agent/lifecycle.ts

@@ -641,6 +641,24 @@ export class AgentManager {
 			if (this.deps.workspaceRegistry.has(backend)) {
 				const driver = this.deps.workspaceRegistry.get(backend)
 				workspaceRef = await driver.create({ label: subSession.id })
+
+				// Write the workspace onto the record that outlives this process.
+				//
+				// The ref was kept only on the in-memory `ChildSpawnRecord`, so
+				// `SubSession.workspaceId` stayed `null` for every spawn-created
+				// child — and `ArchivalManager` resolves a workspace only when
+				// that field is set (`session/retention/archive.ts`). The one
+				// record that could have named the workspace said there was none,
+				// which is why the archival path could never act as a backstop
+				// for a leaked worktree.
+				//
+				// After `create` rather than in `createSubSession`, because the
+				// sub-session id is the workspace's label — the workspace cannot
+				// exist before the record it is named after. Inside the try, so
+				// the compensating rollback below covers it like every other
+				// mutation here.
+				subSession = { ...subSession, workspaceId: workspaceRef.id }
+				await store.updateSubSession(subSession, context.tenantId)
 			}
 		} catch (err) {
 			// Compensating rollback order is mandated by the store's
@@ -764,9 +782,9 @@ export class AgentManager {
 						)
 					}
 				} else {
-					// Non-success: mark sub-session failed and, when we own a
-					// workspace, dispose it. Dispose errors are logged but not
-					// propagated — the sub-session state is already persisted.
+					// Non-success: mark sub-session failed. Disposal is shared with
+					// the success branch below — the workspace was provisioned for
+					// this child either way, and it is this manager that owns it.
 					const subSession = await store.getSubSession(
 						spawnRecord.subSessionId,
 						spawnRecord.tenantId,
@@ -774,21 +792,25 @@ export class AgentManager {
 					if (subSession) {
 						await store.updateSubSession({ ...subSession, status: 'failed' }, spawnRecord.tenantId)
 					}
-					if (spawnRecord.workspaceRef) {
-						const backend = spawnRecord.workspaceRef.meta.backend
-						if (this.deps.workspaceRegistry.has(backend)) {
-							await this.deps.workspaceRegistry
-								.get(backend)
-								.dispose(spawnRecord.workspaceRef)
-								.catch((disposeErr) => {
-									this.log.warn('Workspace dispose failed', {
-										backend,
-										error: toErrorMessage(disposeErr),
-									})
-								})
-						}
-					}
 				}
+
+				// A child is done with its workspace however it ended.
+				//
+				// This used to live only in the branch above, so both dispose
+				// sites in this class were failure paths and a child that
+				// SUCCEEDED released nothing. `.namzu/worktrees/` then grew once
+				// per successful delegation — the more reliable the workers, the
+				// faster it filled, which is the opposite of the signal a leak
+				// usually gives.
+				//
+				// It runs after the summary is sealed and the sub-session flipped
+				// to `idle`, so nothing the terminalization path reads is gone
+				// before it reads it. It also runs BEFORE the `subsession_idled`
+				// emission below: a listener cannot reach into the workspace from
+				// that event. Stated rather than hedged — no consumer does today,
+				// and holding a worktree open for a hypothetical one is what this
+				// is fixing.
+				await this.disposeChildWorkspace(spawnRecord)
 			} catch (err) {
 				this.log.error('Sub-session finalization failed', {
 					taskId: agentTask.taskId,
@@ -937,15 +959,38 @@ export class AgentManager {
 				spawnRecord.tenantId,
 			)
 		}
-		if (spawnRecord.workspaceRef) {
-			const backend = spawnRecord.workspaceRef.meta.backend
-			if (this.deps.workspaceRegistry.has(backend)) {
-				await this.deps.workspaceRegistry
-					.get(backend)
-					.dispose(spawnRecord.workspaceRef)
-					.catch(() => undefined)
-			}
-		}
+		await this.disposeChildWorkspace(spawnRecord)
+	}
+
+	/**
+	 * Release the workspace this manager provisioned for a child.
+	 *
+	 * Called on every terminal path, success included. `has(backend)` before
+	 * `get(backend)` because the registry is deny-by-default and throws on an
+	 * unknown kind — a driver deregistered mid-run must not turn cleanup into
+	 * an exception on a child that already finished.
+	 *
+	 * Never throws. Disposal is cleanup, not part of the child's result: the
+	 * sub-session state is already persisted by the time this runs, and
+	 * failing here would report a delegation that worked as one that did not.
+	 * The failure is logged instead, because a worktree that could not be
+	 * removed is an operator's problem and silence is how it stays one.
+	 */
+	private async disposeChildWorkspace(spawnRecord: ChildSpawnRecord): Promise<void> {
+		if (!spawnRecord.workspaceRef) return
+		const backend = spawnRecord.workspaceRef.meta.backend
+		if (!this.deps.workspaceRegistry.has(backend)) return
+		await this.deps.workspaceRegistry
+			.get(backend)
+			.dispose(spawnRecord.workspaceRef)
+			.catch((disposeErr) => {
+				this.log.warn('Workspace dispose failed', {
+					backend,
+					workspaceId: spawnRecord.workspaceRef?.id,
+					subSessionId: spawnRecord.subSessionId,
+					error: toErrorMessage(disposeErr),
+				})
+			})
 	}
 
 	private markCanceled(taskId: TaskId): void {

package/src/public-runtime.ts

@@ -483,6 +483,12 @@ export {
 
 export {
 	AncestryCycleError,
+	// Exported with the CAS it announces. A host that opts into
+	// `expectedOwnerVersion` has to be able to tell "somebody else took this
+	// session" from any other failure, and string-matching a message is not a
+	// contract — which is the state `ThreadClosedError` and its siblings are
+	// still in, and a reason not to add a fourth.
+	StaleSessionError,
 	TenantIsolationError,
 	WorkspaceBackendError,
 } from './session/errors.js'

package/src/session/__tests__/integration/a-successful-delegation-disposes-its-workspace.test.ts

@@ -0,0 +1,270 @@
+/**
+ * A worktree provisioned for a delegated child outlived the child that used it.
+ *
+ * `finalizeChild` had two dispose sites and both were failure paths — the
+ * non-success branch, and the rollback in `failSubSession`. The success branch
+ * disposed nothing, so `.namzu/worktrees/` grew once per successful delegation:
+ * the more reliable the workers, the faster it filled.
+ *
+ * The backstop could not fire either. `ArchivalManager` resolves a workspace
+ * only when `SubSession.workspaceId` is set, and for a spawn-created
+ * sub-session that field was written `null` and never updated —
+ * `provisionSpawn` kept the ref on the in-memory `ChildSpawnRecord` and nowhere
+ * else. So the one record that could have named the leaked worktree said there
+ * was none.
+ *
+ * Both halves are pinned here, and the failure path is re-asserted alongside
+ * them: a test that only counted disposals would pass on the old code by
+ * reading the failure branch's disposal and calling it the success branch's.
+ */
+
+import { describe, expect, it } 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,
+	BaseAgentConfig,
+	BaseAgentResult,
+} from '../../../types/agent/base.js'
+import type { Agent } from '../../../types/agent/core.js'
+import type { AgentDefinition } from '../../../types/agent/factory.js'
+import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/task.js'
+import type { RunId, TenantId, UserId, WorkspaceId } from '../../../types/ids/index.js'
+import { createAssistantMessage } from '../../../types/message/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
+import type { SummaryId } from '../../../types/session/ids.js'
+import type { WorkspaceRef } from '../../../types/workspace/ref.js'
+import { ZERO_COST } from '../../../utils/cost.js'
+import { DefaultCapacityValidator } from '../../handoff/capacity.js'
+import { SessionSummaryMaterializer } from '../../summary/materialize.js'
+import type {
+	BranchWorkspaceParams,
+	CreateWorkspaceParams,
+	WorkspaceBackendDriver,
+	WorkspaceInspection,
+} from '../../workspace/driver.js'
+import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
+
+const tenant = 'tnt_alpha' as TenantId
+
+const capabilities: AgentCapabilities = {
+	supportsTools: false,
+	supportsStreaming: false,
+	supportsConcurrency: false,
+	supportsSubAgents: false,
+}
+
+/** A child that settles the way `outcome` says, so both branches are reachable. */
+function buildAgent(
+	id: string,
+	outcome: 'completed' | 'failed',
+): Agent<BaseAgentConfig, BaseAgentResult> {
+	return {
+		type: 'reactive',
+		metadata: {
+			type: 'reactive',
+			id,
+			name: id,
+			version: '1.0.0',
+			category: 'test',
+			description: id,
+			capabilities,
+		},
+		run: async (_input: AgentInput, _config: BaseAgentConfig): Promise<BaseAgentResult> => ({
+			runId: 'run_child' as RunId,
+			status: outcome,
+			usage: { ...EMPTY_TOKEN_USAGE },
+			cost: { ...ZERO_COST },
+			iterations: 1,
+			durationMs: 1,
+			messages: [createAssistantMessage('child did the work')],
+			result: 'child did the work',
+		}),
+		cancel: async () => undefined,
+		getCapabilities: () => capabilities,
+	}
+}
+
+function buildDefinition(agent: Agent<BaseAgentConfig, BaseAgentResult>): AgentDefinition {
+	return {
+		info: {
+			id: agent.metadata.id,
+			name: agent.metadata.name,
+			version: agent.metadata.version,
+			category: agent.metadata.category,
+			description: agent.metadata.description,
+			tools: [],
+			defaults: { model: 'test', tokenBudget: 1_000 },
+		},
+		typedAgent: agent,
+	}
+}
+
+/** Provisions successfully and records every ref it is asked to dispose. */
+class RecordingWorkspaceDriver implements WorkspaceBackendDriver {
+	readonly kind = 'git-worktree' as const
+	readonly created: WorkspaceRef[] = []
+	readonly disposed: WorkspaceId[] = []
+	private counter = 0
+
+	async create(params: CreateWorkspaceParams): Promise<WorkspaceRef> {
+		const ref: WorkspaceRef = {
+			id: `wsp_test_${++this.counter}` as WorkspaceId,
+			meta: {
+				backend: 'git-worktree',
+				repoRoot: '/tmp/repo',
+				branch: `namzu/${params.label ?? 'unlabelled'}`,
+				worktreePath: `/tmp/repo/.namzu/worktrees/${params.label ?? 'unlabelled'}`,
+			},
+			createdAt: new Date(),
+		}
+		this.created.push(ref)
+		return ref
+	}
+
+	async branch(_source: WorkspaceRef, _params: BranchWorkspaceParams): Promise<WorkspaceRef> {
+		throw new Error('unused in this test')
+	}
+
+	async dispose(ref: WorkspaceRef): Promise<void> {
+		this.disposed.push(ref.id)
+	}
+
+	async inspect(_ref: WorkspaceRef): Promise<WorkspaceInspection> {
+		throw new Error('unused in this test')
+	}
+}
+
+/**
+ * Stands up a Project → Thread → parent Session and an AgentManager wired to a
+ * recording workspace driver. `outcome` decides how the delegated child ends;
+ * `registerBackend: false` leaves the registry empty, which is the supported
+ * lazy-provisioning configuration rather than an error (pattern doc §7.1).
+ */
+async function harness(
+	outcome: 'completed' | 'failed',
+	{ registerBackend = true }: { registerBackend?: boolean } = {},
+) {
+	const store = new InMemorySessionStore()
+	const threadStore = new InMemoryThreadStore()
+	const project = await store.createProject({ tenantId: tenant, name: 'workspace-project' }, tenant)
+	const thread = await threadStore.createThread(
+		{ projectId: project.id, title: 'workspace-topic' },
+		tenant,
+	)
+
+	const userActor: ActorRef = { kind: 'user', userId: 'usr_root' as UserId, tenantId: tenant }
+
+	const parentSession = await store.createSession(
+		{ threadId: thread.id, projectId: project.id, currentActor: userActor },
+		tenant,
+	)
+	await store.updateSession({ ...parentSession, status: 'active' }, tenant)
+
+	let summaryCounter = 0
+	const materializer = new SessionSummaryMaterializer({
+		store,
+		generateSummaryId: () => `sum_test_${++summaryCounter}` as SummaryId,
+	})
+
+	const registry = new AgentRegistry()
+	registry.register(buildDefinition(buildAgent('worker', outcome)))
+
+	const workspaceRegistry = new WorkspaceBackendRegistry()
+	const driver = new RecordingWorkspaceDriver()
+	if (registerBackend) workspaceRegistry.register(driver)
+
+	const manager = new AgentManager(registry, undefined, {
+		sessionStore: store,
+		summaryMaterializer: materializer,
+		workspaceRegistry,
+		capacity: new DefaultCapacityValidator(store),
+		threadManager: new ThreadManager({ threadStore, sessionStore: store }),
+	})
+
+	const taskContext: AgentTaskContext = {
+		parentRunId: 'run_parent' as RunId,
+		parentAgentId: 'supervisor',
+		parentAbortController: new AbortController(),
+		depth: 0,
+		budgetTracker: { total: 100_000, remaining: 100_000 },
+		tenantId: tenant,
+		threadId: thread.id,
+		sessionId: parentSession.id,
+		projectId: project.id,
+		parentActor: userActor,
+	}
+
+	const options: SendMessageOptions = {
+		agentId: 'worker',
+		input: { messages: [], workingDirectory: '/tmp' },
+		parentSessionId: parentSession.id,
+		tenantId: tenant,
+		projectId: project.id,
+		parentActor: userActor,
+		workspaceBackend: 'git-worktree',
+	}
+
+	return { store, manager, driver, parentSession, options, taskContext }
+}
+
+describe('a delegated child does not outlive its workspace', () => {
+	it('disposes the workspace when the child SUCCEEDS', async () => {
+		const { manager, driver, options, taskContext } = await harness('completed')
+
+		const task = await manager.sendMessage(options, taskContext)
+		await manager.waitForCompletion(task.taskId)
+
+		expect(manager.getState(task.taskId)).toBe('completed')
+		expect(driver.created).toHaveLength(1)
+		// The assertion the leak fails: one workspace made, the same one released.
+		expect(driver.disposed).toEqual([driver.created[0]?.id])
+	})
+
+	it('still disposes the workspace when the child FAILS', async () => {
+		const { manager, driver, options, taskContext } = await harness('failed')
+
+		const task = await manager.sendMessage(options, taskContext)
+		await manager.waitForCompletion(task.taskId)
+
+		expect(driver.created).toHaveLength(1)
+		expect(driver.disposed).toEqual([driver.created[0]?.id])
+	})
+
+	it('records the workspace on the sub-session, so archival can find it', async () => {
+		const { store, manager, driver, parentSession, options, taskContext } =
+			await harness('completed')
+
+		const task = await manager.sendMessage(options, taskContext)
+		await manager.waitForCompletion(task.taskId)
+
+		const [subSession] = await store.getChildren(parentSession.id, tenant)
+		expect(subSession).toBeDefined()
+		// Was `null` on every spawn-created sub-session, which is what made
+		// `ArchivalManager`'s `sub.workspaceId &&` guard unreachable here.
+		expect(subSession?.workspaceId).toBe(driver.created[0]?.id)
+	})
+
+	it('leaves workspaceId null when no backend is registered', async () => {
+		// Lazy provisioning stays legal (pattern doc §7.1): an unregistered
+		// backend is not an error, and the record must not claim a workspace
+		// that was never made.
+		const { store, manager, driver, parentSession, options, taskContext } = await harness(
+			'completed',
+			{ registerBackend: false },
+		)
+
+		const task = await manager.sendMessage(options, taskContext)
+		await manager.waitForCompletion(task.taskId)
+
+		expect(manager.getState(task.taskId)).toBe('completed')
+		expect(driver.created).toHaveLength(0)
+		const [subSession] = await store.getChildren(parentSession.id, tenant)
+		expect(subSession?.workspaceId).toBeNull()
+	})
+})

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

@@ -114,13 +114,22 @@ describe('Integration — single-recipient handoff E2E', () => {
 		expect(reloaded?.previousActors).toHaveLength(1)
 		expect(reloaded?.previousActors[0]).toEqual(sourceActor)
 
-		// Wired assertion: updateSession was invoked at least with the lock
-		// transition + the final commit. That sequence is what makes the
-		// handoff "atomic at the store layer".
-		// Expect at minimum locked (v0) followed by committed (v1).
+		// The lock MOVES the version, and this assertion used to say it did not.
+		//
+		// It expected `locked` at v0 — the version the source was already at —
+		// which is precisely why the lock was not a lock: a second handoff
+		// holding the same snapshot saw an unchanged `ownerVersion`, passed the
+		// check, and locked the session again. Both provisioned a worktree and
+		// one erased the other.
+		//
+		// The bump moved to the lock and the commit now keeps it, so a handoff
+		// still consumes exactly one version and `committedOwnerVersion` is
+		// unchanged at 1 — asserted above, and that is the host-visible
+		// contract. What changed is only the intermediate state, which is the
+		// state that had to become visible.
 		expect(updateCalls).toEqual(
 			expect.arrayContaining([
-				{ status: 'locked', ownerVersion: 0 },
+				{ status: 'locked', ownerVersion: 1 },
 				{ status: 'idle', ownerVersion: 1 },
 			]),
 		)

package/src/session/errors.ts

@@ -94,6 +94,35 @@ export class StaleThreadError extends Error {
 	}
 }
 
+/**
+ * Raised when a Session write names a version the store no longer has.
+ *
+ * The sibling of {@link StaleThreadError}, and it arrived much later: Thread
+ * had a working compare-and-set from the start while `Session.ownerVersion`
+ * was documented as a CAS counter that nothing enforced. Two concurrent
+ * handoffs could both pass, both provision a worktree, and one silently erase
+ * the other.
+ *
+ * `actualVersion` is what the store holds, not what the caller sent — the
+ * caller already knows what it sent, and the useful half of the answer is how
+ * far behind it is.
+ */
+export class StaleSessionError extends Error {
+	readonly details: {
+		sessionId: SessionId
+		expectedVersion: number
+		actualVersion: number
+	}
+
+	constructor(details: { sessionId: SessionId; expectedVersion: number; actualVersion: number }) {
+		super(
+			`Stale Session ${details.sessionId}: expected ownerVersion=${details.expectedVersion}, actual=${details.actualVersion}. Another writer took ownership; re-read the session before retrying.`,
+		)
+		this.name = 'StaleSessionError'
+		this.details = details
+	}
+}
+
 /**
  * Raised by the spawn path (and any caller that enforces the open-thread
  * precondition) when a Thread is in `'archived'` state and would-be mutations

package/src/session/handoff/broadcast.ts

@@ -211,8 +211,12 @@ export async function executeBroadcastHandoff(
 		})
 	}
 
-	const locked: Session = { ...source, status: 'locked' }
-	await deps.store.updateSession(locked, tenantId)
+	// The lock BUMPS the version — see the same change in single.ts. Writing
+	// the lock at the version it read left the locked window invisible, so a
+	// second broadcast holding the same snapshot passed the check above and
+	// fanned out over a session that was already locked.
+	const locked: Session = { ...source, status: 'locked', ownerVersion: source.ownerVersion + 1 }
+	await deps.store.updateSession(locked, tenantId, first.expectedOwnerVersion)
 	emit(deps.events.onLocked, { sessionId: source.id, at: new Date() })
 
 	// 8. Fan-out provisioning. Track per-recipient partial state so rollback
@@ -269,12 +273,13 @@ export async function executeBroadcastHandoff(
 
 		// 9. Commit source: `locked → awaiting_merge` (§5.4 — broadcast source is
 		//    not `idle` until all recipients terminalize; coordinator role).
+		// Keeps the lock's version: one handoff, one ownership change, one
+		// version. The bump moved to the lock where it is load-bearing.
 		const committed: Session = {
-			...source,
+			...locked,
 			status: 'awaiting_merge',
-			ownerVersion: source.ownerVersion + 1,
 		}
-		await deps.store.updateSession(committed, tenantId)
+		await deps.store.updateSession(committed, tenantId, locked.ownerVersion)
 
 		emit(deps.events.onCommitted, {
 			sessionId: source.id,

package/src/session/handoff/single.ts

@@ -160,11 +160,24 @@ export async function executeSingleHandoff(
 		})
 	}
 
+	// The lock BUMPS the version, and that is what makes it a lock.
+	//
+	// It used to write `status: 'locked'` at the version it read, so a second
+	// handoff that had read the same snapshot saw an unchanged `ownerVersion`,
+	// passed the check above, and locked the session a second time. Both then
+	// provisioned a worktree and one silently erased the other. The comparison
+	// above was against a value nothing had moved.
+	//
+	// Passing `expectedOwnerVersion` makes the store the arbiter rather than
+	// this function: the check above is a fast fail on a stale snapshot, and
+	// this is the one that cannot be raced, because the store compares against
+	// what it holds at the instant of the write.
 	const locked: Session = {
 		...source,
 		status: 'locked',
+		ownerVersion: source.ownerVersion + 1,
 	}
-	await deps.store.updateSession(locked, tenantId)
+	await deps.store.updateSession(locked, tenantId, assignment.expectedOwnerVersion)
 	emit(deps.events.onLocked, { sessionId: source.id, at: new Date() })
 
 	// 6. Provision recipient resources. Track partial state for rollback.
@@ -197,16 +210,26 @@ export async function executeSingleHandoff(
 		// 7. Commit source: `locked → idle` with appended actor + bumped version.
 		//    The source transitions ownership to the recipient — the previous
 		//    owner is permanently read-only (§6.1).
+		// Keeps the LOCK's version rather than taking a second one.
+		//
+		// One handoff is one ownership change, so it consumes one version. The
+		// bump moved to the lock — where it has to be, or the locked window is
+		// invisible to a concurrent reader — and the commit finishes the
+		// transition the lock reserved. A host reading `committedOwnerVersion`
+		// sees the same number it always did.
+		//
+		// The expected version is the lock's, so anything that wrote to this
+		// session between the lock and here loses to the store rather than
+		// being overwritten by us.
 		const committed: Session = {
-			...source,
+			...locked,
 			status: 'idle',
 			currentActor: assignment.recipientActor,
 			previousActors: source.currentActor
 				? [...source.previousActors, source.currentActor]
 				: [...source.previousActors],
-			ownerVersion: source.ownerVersion + 1,
 		}
-		await deps.store.updateSession(committed, tenantId)
+		await deps.store.updateSession(committed, tenantId, locked.ownerVersion)
 
 		emit(deps.events.onCommitted, {
 			sessionId: source.id,

package/src/store/session/__tests__/a-session-has-one-writer.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest'
+
+import { StaleSessionError } from '../../../session/errors.js'
+import type { TenantId } from '../../../types/ids/index.js'
+import type { Session } from '../../../types/session/entity.js'
+import { InMemorySessionStore } from '../memory.js'
+
+/**
+ * `Session.ownerVersion` was documented as the CAS counter for handoff, and
+ * nothing enforced it.
+ *
+ * Both stores overwrote unconditionally, so the only check was in the handoff
+ * path — where it compared a snapshot read several awaits earlier against
+ * itself. Two concurrent handoffs on one idle session both passed, both
+ * provisioned a worktree, and one silently erased the other.
+ *
+ * The store is the arbiter now, because it is the only party that can compare
+ * against the value at the instant of the write.
+ */
+
+const TENANT = 'tnt_cas' as TenantId
+
+async function seed(): Promise<{ store: InMemorySessionStore; session: Session }> {
+	const store = new InMemorySessionStore()
+	const project = await store.createProject({ tenantId: TENANT, name: 'cas' }, TENANT)
+	const session = await store.createSession(
+		{ threadId: 'thd_cas' as never, projectId: project.id, currentActor: null },
+		TENANT,
+	)
+	return { store, session }
+}
+
+describe('a session write can require that nobody else wrote first', () => {
+	it('accepts a write naming the version the store holds', async () => {
+		const { store, session } = await seed()
+
+		await store.updateSession({ ...session, status: 'locked' }, TENANT, session.ownerVersion)
+
+		expect((await store.getSession(session.id, TENANT))?.status).toBe('locked')
+	})
+
+	it('refuses a write naming a version that has moved on', async () => {
+		const { store, session } = await seed()
+
+		// Somebody else takes it first.
+		await store.updateSession({ ...session, ownerVersion: 1 }, TENANT, 0)
+
+		await expect(
+			store.updateSession({ ...session, status: 'locked' }, TENANT, 0),
+		).rejects.toBeInstanceOf(StaleSessionError)
+	})
+
+	it('reports what the store holds, not what the caller sent', async () => {
+		// The caller already knows what it sent; the useful half of the answer
+		// is how far behind it is.
+		const { store, session } = await seed()
+		await store.updateSession({ ...session, ownerVersion: 7 }, TENANT, 0)
+
+		await store
+			.updateSession({ ...session, status: 'locked' }, TENANT, 3)
+			.then(() => expect.unreachable('the stale write should have been refused'))
+			.catch((err: StaleSessionError) => {
+				expect(err.details.expectedVersion).toBe(3)
+				expect(err.details.actualVersion).toBe(7)
+			})
+	})
+
+	it('compares against the STORED version, not the payload', async () => {
+		// The payload is the caller's own copy. Comparing it to itself is the
+		// check the handoff path was already making and getting nothing from,
+		// so a write whose payload agrees with itself must still be refused
+		// when the store has moved.
+		const { store, session } = await seed()
+		await store.updateSession({ ...session, ownerVersion: 5 }, TENANT, 0)
+
+		const selfConsistentButStale: Session = { ...session, ownerVersion: 2, status: 'locked' }
+
+		await expect(store.updateSession(selfConsistentButStale, TENANT, 2)).rejects.toBeInstanceOf(
+			StaleSessionError,
+		)
+	})
+
+	it('writes unconditionally when no version is named', async () => {
+		// The compatibility promise: every caller that existed before this
+		// parameter behaves exactly as it did.
+		const { store, session } = await seed()
+		await store.updateSession({ ...session, ownerVersion: 9 }, TENANT, 0)
+
+		await store.updateSession({ ...session, status: 'locked' }, TENANT)
+
+		expect((await store.getSession(session.id, TENANT))?.status).toBe('locked')
+	})
+
+	it('lets exactly one of two concurrent writers win', async () => {
+		// The defect, in the shape it actually took: two writers holding the
+		// same snapshot, racing for the same session.
+		const { store, session } = await seed()
+		const snapshot = session.ownerVersion
+
+		const results = await Promise.allSettled([
+			store.updateSession(
+				{ ...session, status: 'locked', ownerVersion: snapshot + 1 },
+				TENANT,
+				snapshot,
+			),
+			store.updateSession(
+				{ ...session, status: 'locked', ownerVersion: snapshot + 1 },
+				TENANT,
+				snapshot,
+			),
+		])
+
+		expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(1)
+		expect(results.filter((r) => r.status === 'rejected')).toHaveLength(1)
+	})
+})