@namzu/sdk 12.1.0 → 13.0.0

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)
+	})
+})

package/src/store/session/disk.ts

@@ -23,7 +23,7 @@
 
 import { appendFile, mkdir, readFile, readdir, rm } from 'node:fs/promises'
 import { join } from 'node:path'
-import { TenantIsolationError } from '../../session/errors.js'
+import { StaleSessionError, TenantIsolationError } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
@@ -308,7 +308,11 @@ export class DiskSessionStore implements SessionStore {
 		return results
 	}
 
-	async updateSession(session: Session, tenantId: TenantId): Promise<void> {
+	async updateSession(
+		session: Session,
+		tenantId: TenantId,
+		expectedOwnerVersion?: number,
+	): Promise<void> {
 		const located = await this.locateSession(session.id)
 		if (!located) {
 			throw new Error(`Session ${session.id} not found`)
@@ -323,6 +327,21 @@ export class DiskSessionStore implements SessionStore {
 		if (existing) {
 			this.assertTenant(existing.tenantId, tenantId, `session(${session.id})`)
 		}
+		// Against what is on disk, not against the payload. The write itself is
+		// atomic; this read-compare-write is NOT a critical section, so two
+		// processes can still both pass — see the contract note on
+		// `SessionStore.updateSession`. In one process it is the real lock.
+		if (
+			expectedOwnerVersion !== undefined &&
+			existing !== null &&
+			existing.ownerVersion !== expectedOwnerVersion
+		) {
+			throw new StaleSessionError({
+				sessionId: session.id,
+				expectedVersion: expectedOwnerVersion,
+				actualVersion: existing.ownerVersion,
+			})
+		}
 		const updated: Session = { ...session, updatedAt: new Date() }
 		await atomicWriteJson(join(located.path, 'session.json'), serializeSession(updated))
 	}

package/src/store/session/memory.ts

@@ -8,7 +8,7 @@
  * (Convention #5 deny-by-default, session-hierarchy.md §12.2).
  */
 
-import { TenantIsolationError } from '../../session/errors.js'
+import { StaleSessionError, TenantIsolationError } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
@@ -151,7 +151,11 @@ export class InMemorySessionStore implements SessionStore {
 		return matches
 	}
 
-	async updateSession(session: Session, tenantId: TenantId): Promise<void> {
+	async updateSession(
+		session: Session,
+		tenantId: TenantId,
+		expectedOwnerVersion?: number,
+	): Promise<void> {
 		const record = this.sessions.get(session.id)
 		if (!record) {
 			throw new Error(`Session ${session.id} not found`)
@@ -163,6 +167,20 @@ export class InMemorySessionStore implements SessionStore {
 				resource: `session(${session.id}) payload`,
 			})
 		}
+		// Compared against the STORED version, not against `session.ownerVersion`
+		// — the payload is the caller's copy, and comparing it to itself is
+		// precisely the check the handoff path was already making and getting
+		// nothing from.
+		if (
+			expectedOwnerVersion !== undefined &&
+			record.session.ownerVersion !== expectedOwnerVersion
+		) {
+			throw new StaleSessionError({
+				sessionId: session.id,
+				expectedVersion: expectedOwnerVersion,
+				actualVersion: record.session.ownerVersion,
+			})
+		}
 		this.sessions.set(session.id, { tenantId, session: { ...session, updatedAt: new Date() } })
 	}
 

package/src/tools/coordinator/__tests__/an-approver-is-never-shown-an-impossible-step.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest'
+
+import { PlanManager } from '../../../manager/plan/lifecycle.js'
+import type { TaskGateway } from '../../../types/agent/gateway.js'
+import type { RunId } from '../../../types/ids/index.js'
+import type { PlanApprovalRequest } from '../../../types/plan/index.js'
+import type { ToolContext } from '../../../types/tool/index.js'
+import { buildCoordinatorTools } from '../index.js'
+
+/**
+ * A plan could name an agent the launch would then refuse.
+ *
+ * `create_task` constrains `agent_id` with a closed enum; `approve_plan` typed
+ * the same field as a bare string. So a model could propose, and a human could
+ * approve, "delegate to X" for an X that `create_task` rejects at schema-parse
+ * time — the run then burns a turn on a step a human had already blessed.
+ *
+ * The check lives in `execute`, not in the schema, and that is deliberate.
+ * `approve_plan` is mounted even with an EMPTY roster, because planning with no
+ * delegates and a human channel is a supported configuration — and `z.enum([])`
+ * renders as `{"not":{}}`, the shape `delegateSchema` already refuses because a
+ * strict tool-schema validator rejects the whole request over it rather than
+ * the one tool. `create_task` escapes that by being withheld entirely; this
+ * tool cannot be. Enforcing in `execute` as well is the precedent the canonical
+ * `Agent` tool set for complete mediation.
+ *
+ * It runs BEFORE `startGenerating`, so the refusal costs no half-built plan and
+ * the human is never shown the bad step at all.
+ */
+
+const RUN = 'run_roster' as RunId
+
+function unusedGateway(): TaskGateway {
+	return {
+		async createTask() {
+			throw new Error('this test never launches')
+		},
+		async waitForTask() {
+			throw new Error('this test never waits')
+		},
+		async continueTask() {},
+		cancelTask() {},
+		getTask() {
+			return undefined
+		},
+		listTasks() {
+			return []
+		},
+		onTaskCompleted() {
+			return () => {}
+		},
+	}
+}
+
+function ctx(): ToolContext {
+	return {
+		runId: RUN,
+		workingDirectory: '/tmp/test',
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+/** Run `approve_plan`, reporting both its result and what the approver saw. */
+async function approve(
+	roster: string[],
+	steps: Array<{ description: string; agent_id?: string }>,
+): Promise<{ result: Awaited<ReturnType<ReturnType<typeof build>>>; seen?: PlanApprovalRequest }> {
+	let seen: PlanApprovalRequest | undefined
+	const pm = new PlanManager(RUN, async (request) => {
+		seen = request
+		return { approved: true }
+	})
+	const run = build(roster, pm)
+	const result = await run(steps)
+	return { result, ...(seen ? { seen } : {}) }
+}
+
+function build(roster: string[], pm: PlanManager) {
+	const tools = buildCoordinatorTools({
+		gateway: unusedGateway(),
+		workingDirectory: '/tmp/test',
+		allowedAgentIds: roster,
+		getPlanManager: () => pm,
+	})
+	const approvePlan = tools.find((t) => t.name === 'approve_plan')
+	if (!approvePlan) throw new Error('approve_plan missing from coordinator builder')
+	return (steps: Array<{ description: string; agent_id?: string }>) =>
+		approvePlan.execute({ title: 'do it', summary: 'a plan', steps }, ctx())
+}
+
+describe('a plan may only name an agent the run can actually launch', () => {
+	it('refuses a step naming an agent outside the roster', async () => {
+		const { result } = await approve(
+			['researcher', 'writer'],
+			[{ description: 'audit the deps', agent_id: 'security-auditor' }],
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('security-auditor')
+	})
+
+	it('names the roster, so the model can correct itself in one turn', async () => {
+		const { result } = await approve(
+			['researcher', 'writer'],
+			[{ description: 'audit', agent_id: 'nobody' }],
+		)
+
+		expect(result.error).toContain('researcher')
+		expect(result.error).toContain('writer')
+	})
+
+	it('never shows the approver the step it refused', async () => {
+		// The whole point of checking before `startGenerating`: a human must
+		// not be asked to approve work that cannot run.
+		const { seen } = await approve(
+			['researcher'],
+			[{ description: 'audit', agent_id: 'security-auditor' }],
+		)
+
+		expect(seen).toBeUndefined()
+	})
+
+	it('leaves no half-built plan behind', async () => {
+		const pm = new PlanManager(RUN, async () => ({ approved: true }))
+		const run = build(['researcher'], pm)
+
+		await run([{ description: 'audit', agent_id: 'ghost' }])
+
+		expect(pm.active).toBeNull()
+	})
+
+	it('says something different when the run has no delegates at all', async () => {
+		// `approve_plan` is mounted on an empty roster on purpose — planning
+		// without delegation is supported — so the message has to explain that
+		// rather than list an empty set.
+		const { result } = await approve([], [{ description: 'audit', agent_id: 'anyone' }])
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('no delegates')
+	})
+
+	it('still admits a plan that delegates only within the roster', async () => {
+		const { result, seen } = await approve(
+			['researcher', 'writer'],
+			[{ description: 'gather', agent_id: 'researcher' }, { description: 'summarize' }],
+		)
+
+		expect(result.success).toBe(true)
+		expect(seen?.steps.map((s) => s.agentId)).toEqual(['researcher', undefined])
+	})
+})

package/src/tools/coordinator/index.ts

@@ -1015,6 +1015,46 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					return { success: false, output: '', error: dependencies.error }
 				}
 
+				// The roster, checked here rather than in the schema, and BEFORE
+				// the plan is built — so a human is never shown a step naming an
+				// agent that cannot run it.
+				//
+				// `create_task` constrains the same field with a closed enum, so
+				// a plan could name an agent the launch would then refuse. The
+				// mismatch used to be invisible because the name was dropped on
+				// the way to the approver; now that a step carries it, an
+				// approver could read "delegate to X" for an X that does not
+				// exist.
+				//
+				// NOT closed in the schema, deliberately. `approve_plan` is
+				// mounted even with an empty roster — planning with no delegates
+				// and a human channel is a supported configuration — and
+				// `z.enum([])` renders as `{"not":{}}`, the shape `delegateSchema`
+				// already refuses because a strict tool-schema validator rejects
+				// the whole request over it rather than the one tool.
+				// `create_task` escapes that by being withheld entirely; this
+				// tool cannot be.
+				//
+				// Enforcing in `execute` as well as the schema is the precedent
+				// the canonical `Agent` tool set for complete mediation.
+				const unknownAgents = [
+					...new Set(
+						steps
+							.map((s) => s.agent_id)
+							.filter((id): id is string => Boolean(id) && !agentIds.includes(id as string)),
+					),
+				]
+				if (unknownAgents.length > 0) {
+					return {
+						success: false,
+						output: '',
+						error:
+							agentIds.length === 0
+								? `This plan delegates to ${unknownAgents.join(', ')}, but this run has no delegates. Plan the work as your own steps and omit agent_id.`
+								: `No such agent: ${unknownAgents.join(', ')}. Delegate only to ${agentIds.join(', ')}, or omit agent_id for a step you carry out yourself.`,
+					}
+				}
+
 				pm.startGenerating(title)
 				for (let i = 0; i < steps.length; i++) {
 					const step = steps[i]

package/src/types/hitl/index.ts

@@ -109,6 +109,24 @@ export interface PlanApprovalData {
 		id: string
 		description: string
 		toolName?: string
+
+		/**
+		 * Which agent the step is to be delegated to, when it is delegated.
+		 *
+		 * `PlanStep` gained this so an approver could see WHICH agent a step
+		 * goes to rather than only THAT it delegates — approving "delegate
+		 * this" is not approving "delegate this to the agent with shell
+		 * access". It reached `PlanApprovalRequest`, which is the shape a host
+		 * sees when it installs its own handler on `PlanManager`.
+		 *
+		 * It did not reach here, and this is the ordinary path: every host
+		 * using `resumeHandler` is served by this type, and both mappers that
+		 * build it copy field by field. So the fix landed on one of the two
+		 * approval surfaces and the busier one kept showing
+		 * `toolName: 'create_task'` and nothing else.
+		 */
+		agentId?: string
+
 		dependsOn: string[]
 		order: number
 	}>

package/src/types/session/store.ts

@@ -105,7 +105,34 @@ export interface SessionStore {
 
 	getSession(sessionId: SessionId, tenantId: TenantId): Promise<Session | null>
 
-	updateSession(session: Session, tenantId: TenantId): Promise<void>
+	/**
+	 * Write a Session back, optionally only if nobody else wrote it first.
+	 *
+	 * **`expectedOwnerVersion` is the single-writer lock this level is supposed
+	 * to own, and it did not exist.** `Session.ownerVersion` is documented as
+	 * the CAS counter for handoff, but nothing enforced it: both stores
+	 * overwrote unconditionally, and the handoff's own check compared a
+	 * snapshot it had 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.
+	 *
+	 * Supply it and the store compares against the version it HAS STORED —
+	 * not against the payload, which is the caller's stale copy — and throws
+	 * {@link StaleSessionError} rather than writing. Omit it and the behaviour
+	 * is exactly what it always was, which is the compatibility promise: this
+	 * parameter is optional so that widening the interface stays invisible to
+	 * callers and harmless to hosts implementing their own store. A required
+	 * parameter would break every implementor for a guarantee they can opt
+	 * into.
+	 *
+	 * **In-process only, stated rather than implied.** `DiskSessionStore`
+	 * writes atomically, but its read-compare-write is not a critical section,
+	 * so two PROCESSES can still both pass the check. Closing that needs a
+	 * lease with an expiry — not a PID registry, because a Session is durable
+	 * and written from hosts where a PID is not a checkable fact. The same
+	 * honesty the spawn lock already carries.
+	 */
+	updateSession(session: Session, tenantId: TenantId, expectedOwnerVersion?: number): Promise<void>
 
 	/**
 	 * List every Session that belongs to the given Thread for the caller's