@namzu/sdk 12.2.0 → 13.1.0

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/__tests__/a-workspace-can-be-configured.test.ts

@@ -0,0 +1,210 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { TenantIsolationError } from '../../../session/errors.js'
+import type { TenantId } from '../../../types/ids/index.js'
+import type { SessionStore } from '../../../types/session/store.js'
+import { DiskSessionStore } from '../disk.js'
+import { InMemorySessionStore } from '../memory.js'
+
+/**
+ * Every project in existence ran at depth 4 and width 8.
+ *
+ * The config was hardcoded identically in both stores, `CreateProjectParams`
+ * was `{tenantId, name}`, and there was no `updateProject`. So a tenant with
+ * several workspaces could not give them different limits — which is most of
+ * what having several workspaces is for.
+ *
+ * Only the two fields something READS are settable. `ProjectConfig` declares
+ * eight; five enforcement sites read two of them. Exposing the other six would
+ * make dead fields easier to set, and a host that configures a retention policy
+ * and gets no error believes retention is on. `maxInterventionDepth` looks like
+ * an exception and is not: its three apparent readers are all comments.
+ *
+ * Both stores are driven by the same cases, because a reference implementation
+ * that disagrees with the durable one is worse than having only one.
+ */
+
+const TENANT = 'tnt_cfg' as TenantId
+const OTHER = 'tnt_other' as TenantId
+
+const dirs: string[] = []
+afterEach(async () => {
+	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+	dirs.length = 0
+})
+
+async function diskStore(): Promise<SessionStore> {
+	const rootDir = await mkdtemp(join(tmpdir(), 'namzu-cfg-'))
+	dirs.push(rootDir)
+	return new DiskSessionStore({ rootDir })
+}
+
+const IMPLEMENTATIONS: ReadonlyArray<readonly [string, () => Promise<SessionStore>]> = [
+	['in memory', async () => new InMemorySessionStore()],
+	['on disk', diskStore],
+]
+
+describe.each(IMPLEMENTATIONS)('a workspace carries its own limits (%s)', (_name, build) => {
+	it('takes the limits it was created with', async () => {
+		const store = await build()
+
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 2, maxDelegationWidth: 3 } },
+			TENANT,
+		)
+
+		expect(project.config.maxDelegationDepth).toBe(2)
+		expect(project.config.maxDelegationWidth).toBe(3)
+	})
+
+	it('keeps the defaults for anything not given', async () => {
+		const store = await build()
+
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 2 } },
+			TENANT,
+		)
+
+		expect(project.config.maxDelegationDepth).toBe(2)
+		expect(project.config.maxDelegationWidth).toBe(8)
+	})
+
+	it('lets two workspaces of one tenant differ, which is the point', async () => {
+		const store = await build()
+
+		const narrow = await store.createProject(
+			{ tenantId: TENANT, name: 'narrow', config: { maxDelegationWidth: 1 } },
+			TENANT,
+		)
+		const wide = await store.createProject(
+			{ tenantId: TENANT, name: 'wide', config: { maxDelegationWidth: 16 } },
+			TENANT,
+		)
+
+		expect(narrow.config.maxDelegationWidth).toBe(1)
+		expect(wide.config.maxDelegationWidth).toBe(16)
+	})
+
+	it('changes a limit after the fact, and the change is readable back', async () => {
+		const store = await build()
+		const project = await store.createProject({ tenantId: TENANT, name: 'w' }, TENANT)
+
+		await store.updateProject?.(project.id, { maxDelegationWidth: 12 }, TENANT)
+
+		expect((await store.getProject(project.id, TENANT))?.config.maxDelegationWidth).toBe(12)
+	})
+
+	it('leaves a limit it was not asked to change', async () => {
+		// Per field, not whole-value: raising the width says nothing about the
+		// depth, and resetting it would be an answer to a question nobody asked.
+		const store = await build()
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 2 } },
+			TENANT,
+		)
+
+		await store.updateProject?.(project.id, { maxDelegationWidth: 12 }, TENANT)
+
+		const reloaded = await store.getProject(project.id, TENANT)
+		expect(reloaded?.config.maxDelegationDepth).toBe(2)
+		expect(reloaded?.config.maxDelegationWidth).toBe(12)
+	})
+
+	it('treats an explicitly undefined limit as "leave it", not "clear it"', async () => {
+		// The case the per-field guard exists for, and the one a plain spread
+		// gets wrong: `{...config}` with an explicit `undefined` key writes the
+		// undefined through and erases a limit the caller never mentioned. A
+		// caller building an update object programmatically produces exactly
+		// this shape.
+		const store = await build()
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 3 } },
+			TENANT,
+		)
+
+		await store.updateProject?.(
+			project.id,
+			{ maxDelegationDepth: undefined, maxDelegationWidth: 12 },
+			TENANT,
+		)
+
+		const reloaded = await store.getProject(project.id, TENANT)
+		expect(reloaded?.config.maxDelegationDepth).toBe(3)
+		expect(reloaded?.config.maxDelegationWidth).toBe(12)
+	})
+
+	it('lists what this tenant owns, oldest first', async () => {
+		// Eight, spaced past the millisecond `createdAt` is measured in, so this
+		// is an assertion about age rather than about the tie-break below. With
+		// the sort dropped the disk store returns them in directory order, which
+		// is id-ascending — it matches creation order once in 8!.
+		const store = await build()
+		const created = []
+		for (const name of ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']) {
+			created.push(await store.createProject({ tenantId: TENANT, name }, TENANT))
+			await new Promise((resolve) => setTimeout(resolve, 2))
+		}
+
+		const listed = await store.listProjects?.(TENANT)
+
+		expect(listed?.map((p) => p.id)).toEqual(created.map((p) => p.id))
+	})
+
+	it('stays a total order when several are created in the same millisecond', async () => {
+		// CI found this and a slower machine could not: on a fast filesystem
+		// projects routinely share a `createdAt`, and "oldest first" alone left
+		// the rest to `readdir`. A caller paginating a listing that reorders
+		// under it sees the same project twice and never sees another.
+		const store = await build()
+		for (const name of ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']) {
+			await store.createProject({ tenantId: TENANT, name }, TENANT)
+		}
+
+		const listed = (await store.listProjects?.(TENANT)) ?? []
+
+		expect(listed).toHaveLength(8)
+		for (let i = 1; i < listed.length; i++) {
+			const before = listed[i - 1]
+			const after = listed[i]
+			if (before === undefined || after === undefined) throw new Error('short listing')
+			const olderFirst = before.createdAt.getTime() < after.createdAt.getTime()
+			const tieByName =
+				before.createdAt.getTime() === after.createdAt.getTime() && before.id < after.id
+			expect({ pair: [before.name, after.name], ordered: olderFirst || tieByName }).toEqual({
+				pair: [before.name, after.name],
+				ordered: true,
+			})
+		}
+	})
+
+	it('omits another tenant from the listing rather than refusing', async () => {
+		// A listing is a question about what you own. Refusing would confirm
+		// that somebody else's project is there, which is the leak the tenant
+		// boundary exists to prevent.
+		const store = await build()
+		await store.createProject({ tenantId: TENANT, name: 'mine' }, TENANT)
+		await store.createProject({ tenantId: OTHER, name: 'theirs' }, OTHER)
+
+		expect((await store.listProjects?.(TENANT))?.map((p) => p.name)).toEqual(['mine'])
+	})
+
+	it('refuses to reconfigure another tenant project', async () => {
+		// Reading a listing is a question; writing to somebody else's workspace
+		// is not, so this one throws.
+		const store = await build()
+		const theirs = await store.createProject({ tenantId: OTHER, name: 'theirs' }, OTHER)
+
+		await expect(
+			store.updateProject?.(theirs.id, { maxDelegationWidth: 99 }, TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('returns null for a project that does not exist', async () => {
+		const store = await build()
+
+		expect(await store.updateProject?.('prj_missing' as never, {}, TENANT)).toBeNull()
+	})
+})

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'
@@ -35,6 +35,7 @@ import type {
 	CreateProjectParams,
 	CreateSessionParams,
 	CreateSubSessionParams,
+	ProjectConfigInput,
 	SessionStore,
 	SessionView,
 } from '../../types/session/store.js'
@@ -193,8 +194,8 @@ export class DiskSessionStore implements SessionStore {
 			tenantId,
 			name: params.name,
 			config: {
-				maxDelegationDepth: 4,
-				maxDelegationWidth: 8,
+				maxDelegationDepth: params.config?.maxDelegationDepth ?? 4,
+				maxDelegationWidth: params.config?.maxDelegationWidth ?? 8,
 				maxInterventionDepth: 10,
 			},
 			createdAt: now,
@@ -215,6 +216,66 @@ export class DiskSessionStore implements SessionStore {
 		return deserializeProject(raw)
 	}
 
+	async updateProject(
+		projectId: ProjectId,
+		config: ProjectConfigInput,
+		tenantId: TenantId,
+	): Promise<Project | null> {
+		const existing = await this.getProject(projectId, tenantId)
+		if (!existing) return null
+		// Per field, like the in-memory store: an omitted limit is left alone
+		// rather than reset.
+		const project: Project = {
+			...existing,
+			config: {
+				...existing.config,
+				...(config.maxDelegationDepth !== undefined
+					? { maxDelegationDepth: config.maxDelegationDepth }
+					: {}),
+				...(config.maxDelegationWidth !== undefined
+					? { maxDelegationWidth: config.maxDelegationWidth }
+					: {}),
+			},
+			updatedAt: new Date(),
+		}
+		await atomicWriteJson(
+			join(this.projectDir(projectId), 'project.json'),
+			serializeProject(project),
+		)
+		return project
+	}
+
+	async listProjects(tenantId: TenantId): Promise<readonly Project[]> {
+		// Read from the directory rather than the lazily-built index: the index
+		// only knows about projects this instance has already touched, so a
+		// listing built from it would omit everything written by a previous
+		// process — which for a store whose whole point is durability is the
+		// wrong answer.
+		const projectsRoot = join(this.rootDir, 'projects')
+		let entries: string[]
+		try {
+			entries = await readdir(projectsRoot)
+		} catch {
+			return []
+		}
+
+		const found: Project[] = []
+		for (const entry of entries) {
+			const raw = await readJson<PersistedProject>(join(projectsRoot, entry, 'project.json'))
+			if (!raw) continue
+			// Another tenant's project is absent, not an error — a listing is a
+			// question about what you own, and refusing would leak that
+			// somebody else's project is there.
+			if (raw.tenantId !== tenantId) continue
+			found.push(deserializeProject(raw))
+		}
+		// Tie-broken by id — see the in-memory store. On a fast filesystem two
+		// projects share a millisecond routinely, and without this the order
+		// came from readdir.
+		found.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id))
+		return found
+	}
+
 	// Session CRUD ------------------------------------------------------------
 
 	async createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session> {
@@ -308,7 +369,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 +388,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'
@@ -20,6 +20,7 @@ import type {
 	CreateProjectParams,
 	CreateSessionParams,
 	CreateSubSessionParams,
+	ProjectConfigInput,
 	SessionStore,
 	SessionView,
 } from '../../types/session/store.js'
@@ -88,8 +89,8 @@ export class InMemorySessionStore implements SessionStore {
 			tenantId,
 			name: params.name,
 			config: {
-				maxDelegationDepth: 4,
-				maxDelegationWidth: 8,
+				maxDelegationDepth: params.config?.maxDelegationDepth ?? 4,
+				maxDelegationWidth: params.config?.maxDelegationWidth ?? 8,
 				maxInterventionDepth: 10,
 			},
 			createdAt: now,
@@ -106,6 +107,49 @@ export class InMemorySessionStore implements SessionStore {
 		return record.project
 	}
 
+	async updateProject(
+		projectId: ProjectId,
+		config: ProjectConfigInput,
+		tenantId: TenantId,
+	): Promise<Project | null> {
+		const record = this.projects.get(projectId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `project(${projectId})`)
+		// Per field: an omitted limit is left alone rather than reset, because a
+		// caller raising the width is saying nothing about the depth.
+		const project: Project = {
+			...record.project,
+			config: {
+				...record.project.config,
+				...(config.maxDelegationDepth !== undefined
+					? { maxDelegationDepth: config.maxDelegationDepth }
+					: {}),
+				...(config.maxDelegationWidth !== undefined
+					? { maxDelegationWidth: config.maxDelegationWidth }
+					: {}),
+			},
+			updatedAt: new Date(),
+		}
+		this.projects.set(projectId, { tenantId, project })
+		return project
+	}
+
+	async listProjects(tenantId: TenantId): Promise<readonly Project[]> {
+		const matches: Project[] = []
+		for (const record of this.projects.values()) {
+			if (record.tenantId !== tenantId) continue
+			matches.push(record.project)
+		}
+		// Tie-broken by id, because two projects created in the same
+		// millisecond otherwise fall back to insertion or directory order and
+		// "oldest first" stops being a total order. A caller paginating a
+		// listing that reorders under it sees items move between pages.
+		matches.sort(
+			(a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id),
+		)
+		return matches
+	}
+
 	// Session CRUD ------------------------------------------------------------
 
 	async createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session> {
@@ -151,7 +195,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 +211,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() } })
 	}