@namzu/sdk 13.0.0 → 14.0.0

package/src/contracts/__tests__/an-id-the-sdk-mints-passes-its-own-schema.test.ts

@@ -0,0 +1,84 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import {
+	DefaultFilesystemMigrator,
+	NOOP_FILESYSTEM_MIGRATION_SINK,
+} from '../../session/migration/filesystem.js'
+import { generateProjectId } from '../../utils/id.js'
+import { ProjectIdSchema } from '../schemas.js'
+
+/**
+ * `ProjectIdSchema` was `/^prj_[a-z0-9]+$/` while the v0.2.0 filesystem
+ * migration minted `prj_legacy_<suffix>`. So the SDK's own public validator
+ * rejected ids the SDK itself had written to disk: a host that validated an
+ * inbound project id — the reason the schema is exported at all — refused
+ * every project it had migrated, with "Invalid project ID format" and no hint
+ * that the id came from the SDK.
+ *
+ * Both minters are driven here rather than restated. A test that spells out
+ * `prj_legacy_abc` as a literal would still pass if the migration changed its
+ * shape tomorrow; running the migration means the two cannot drift apart
+ * without this failing.
+ */
+
+const dirs: string[] = []
+afterEach(async () => {
+	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+	dirs.length = 0
+})
+
+describe('every project id the SDK mints passes the schema the SDK exports', () => {
+	it('accepts what the id generator produces', () => {
+		// 200 draws, because the generator is random over [0-9a-z] and one
+		// sample proves nothing about the alphabet it can reach.
+		for (let i = 0; i < 200; i++) {
+			const id = generateProjectId()
+			const parsed = ProjectIdSchema.safeParse(id)
+			expect({ id, ok: parsed.success }).toEqual({ id, ok: true })
+		}
+	})
+
+	it('accepts what the filesystem migration produces', async () => {
+		const root = await mkdtemp(join(tmpdir(), 'namzu-idschema-'))
+		dirs.push(root)
+		const runDir = join(root, 'threads', 'thd_a1b2c3d4e5f6', 'runs', 'run_seed')
+		await mkdir(runDir, { recursive: true })
+		await writeFile(join(runDir, 'run.json'), JSON.stringify({ id: 'run_seed' }), 'utf-8')
+
+		const result = await new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK).migrate(root)
+
+		expect(result.kind).toBe('migrated')
+		expect(result.migratedThreads).toHaveLength(1)
+		for (const { newProjectId } of result.migratedThreads) {
+			const parsed = ProjectIdSchema.safeParse(newProjectId)
+			expect({ newProjectId, ok: parsed.success }).toEqual({ newProjectId, ok: true })
+		}
+	})
+
+	it('still refuses what no minter produces, because the id is also a directory name', () => {
+		// Widening to accept the legacy form must not widen to accept a path.
+		// Everything here would be joined onto the store root if it got through.
+		const refused = [
+			'prj_../../etc',
+			'prj_..',
+			'prj_a/b',
+			'prj_a\\b',
+			'prj_',
+			'prj_legacy_',
+			'prj_ABC',
+			'prj_a-b',
+			'prj_a b',
+			'proj_abc',
+			'thd_abc',
+			'',
+		]
+
+		for (const candidate of refused) {
+			const parsed = ProjectIdSchema.safeParse(candidate)
+			expect({ candidate, ok: parsed.success }).toEqual({ candidate, ok: false })
+		}
+	})
+})

package/src/contracts/schemas.ts

@@ -1,6 +1,23 @@
 import { z } from 'zod'
 
-export const ProjectIdSchema = z.string().regex(/^prj_[a-z0-9]+$/, 'Invalid project ID format')
+/**
+ * The two shapes the SDK mints, and nothing else.
+ *
+ * `prj_<12 lowercase alphanumerics>` comes from `generateProjectId()`.
+ * `prj_legacy_<suffix>` comes from the v0.2.0 filesystem migration, which
+ * synthesises a project per legacy `thd_*` folder. The `legacy_` segment is
+ * spelled out rather than covered by a permissive character class, because a
+ * project id is also a directory name: everything this accepts is joined to a
+ * path, so the set it accepts is a containment boundary, not a formatting
+ * preference.
+ *
+ * A host that supplies its own `SessionStore` and mints its own ids should
+ * validate with its own schema — `ProjectId` is `prj_${string}` at the type
+ * level and this schema is deliberately narrower.
+ */
+export const ProjectIdSchema = z
+	.string()
+	.regex(/^prj_(legacy_)?[a-z0-9]+$/, 'Invalid project ID format')
 export const RunIdSchema = z.string().regex(/^run_[a-z0-9]+$/, 'Invalid run ID format')
 export const MessageIdSchema = z.string().regex(/^msg_[a-z0-9]+$/, 'Invalid message ID format')
 

package/src/manager/agent/__tests__/an-env-reaches-the-child-it-was-set-for.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from 'vitest'
+
+import { EMPTY_TOKEN_USAGE } from '../../../constants/limits.js'
+import { AgentRegistry } from '../../../registry/agent/definitions.js'
+import { DefaultCapacityValidator } from '../../../session/handoff/capacity.js'
+import { SessionSummaryMaterializer } from '../../../session/summary/materialize.js'
+import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
+import type { 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 } from '../../../types/agent/task.js'
+import type { AgentId, TenantId } from '../../../types/ids/index.js'
+import type { SummaryId } from '../../../types/session/ids.js'
+import { ZERO_COST } from '../../../utils/cost.js'
+import { ThreadManager } from '../../thread/lifecycle.js'
+import { AgentManager } from '../lifecycle.js'
+
+/**
+ * A delegate registered the normal way inherited no environment at all.
+ *
+ * `AgentManager` builds a child's config on two branches. The bare-config
+ * branch — taken only when a definition has NO `configBuilder` — has always
+ * carried `env`. The `configBuilder` branch, which is what a host registering
+ * a real agent actually uses, never stamped it. So a run given an environment
+ * handed its delegates none of it.
+ *
+ * This is the third field to go the same way: `parentSpan` and `resumeHandler`
+ * are both stamped after the builder returns, each with a comment saying the
+ * builder is written by whoever registered the agent and cannot be expected to
+ * forward something it was never told about. `env` was missed, and it went
+ * unnoticed because a missing environment does not fail — the child just runs
+ * somewhere else.
+ *
+ * These drive the real `AgentManager` rather than re-implementing the merge.
+ * A test that restates the logic proves the logic agrees with itself; what has
+ * to hold is that the manager applies it.
+ */
+
+const TENANT = 'tnt_env' as TenantId
+
+/** Records the config it is run with, so the assertion is on what shipped. */
+function recordingAgent(seen: { config?: BaseAgentConfig }) {
+	return {
+		type: 'reactive',
+		metadata: {
+			id: 'worker',
+			name: 'worker',
+			version: '1.0.0',
+			category: 'general',
+			description: 'records its config',
+			type: 'reactive',
+			capabilities: {},
+		},
+		async run(_input: unknown, config: BaseAgentConfig): Promise<BaseAgentResult> {
+			seen.config = config
+			return {
+				runId: 'run_child',
+				status: 'completed',
+				result: 'ok',
+				usage: { ...EMPTY_TOKEN_USAGE },
+				cost: { ...ZERO_COST },
+				iterations: 1,
+				durationMs: 0,
+				messages: [],
+			} as BaseAgentResult
+		},
+		async cancel() {},
+		getCapabilities() {
+			return {} as never
+		},
+	} as unknown as Agent<BaseAgentConfig, BaseAgentResult>
+}
+
+/** A definition WITH a configBuilder — the branch that dropped `env`. */
+function definitionWithBuilder(
+	agent: Agent<BaseAgentConfig, BaseAgentResult>,
+	builderEnv?: Record<string, string>,
+): AgentDefinition {
+	return {
+		info: {
+			id: 'worker',
+			name: 'worker',
+			version: '1.0.0',
+			category: 'general',
+			description: 'a worker',
+			tools: [],
+			defaults: { model: 'test', tokenBudget: 1_000 },
+		},
+		typedAgent: agent,
+		configBuilder: () =>
+			({
+				model: 'test',
+				tokenBudget: 1_000,
+				timeoutMs: 10_000,
+				...(builderEnv ? { env: builderEnv } : {}),
+			}) as BaseAgentConfig,
+	} as AgentDefinition
+}
+
+async function spawnWith(options: {
+	builderEnv?: Record<string, string>
+	overrideEnv?: Record<string, string>
+}): Promise<BaseAgentConfig | undefined> {
+	const seen: { config?: BaseAgentConfig } = {}
+	const store = new InMemorySessionStore()
+	const threadStore = new InMemoryThreadStore()
+	const project = await store.createProject({ tenantId: TENANT, name: 'p' }, TENANT)
+	const thread = await threadStore.createThread({ projectId: project.id, title: 't' }, TENANT)
+	const parentActor = { kind: 'agent', agentId: 'sup' as AgentId, tenantId: TENANT } as const
+	const parentSession = await store.createSession(
+		{ threadId: thread.id, projectId: project.id, currentActor: parentActor },
+		TENANT,
+	)
+	await store.updateSession({ ...parentSession, status: 'active' }, TENANT)
+
+	const registry = new AgentRegistry()
+	registry.register(definitionWithBuilder(recordingAgent(seen), options.builderEnv))
+
+	let n = 0
+	const manager = new AgentManager(registry, undefined, {
+		sessionStore: store,
+		threadManager: new ThreadManager({ threadStore, sessionStore: store }),
+		workspaceRegistry: new WorkspaceBackendRegistry(),
+		capacity: new DefaultCapacityValidator(store),
+		summaryMaterializer: new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: () => `sum_${++n}` as SummaryId,
+		}),
+	})
+
+	const context: AgentTaskContext = {
+		parentRunId: 'run_parent' as never,
+		parentAgentId: 'sup',
+		parentAbortController: new AbortController(),
+		depth: 0,
+		budgetTracker: { total: 100_000, remaining: 100_000 },
+		tenantId: TENANT,
+		threadId: thread.id,
+		sessionId: parentSession.id,
+		projectId: project.id,
+		parentActor,
+	} as AgentTaskContext
+
+	const task = await manager.sendMessage(
+		{
+			agentId: 'worker',
+			input: { messages: [], workingDirectory: '/tmp' } as never,
+			parentSessionId: parentSession.id,
+			tenantId: TENANT,
+			projectId: project.id,
+			parentActor,
+			...(options.overrideEnv ? { configOverrides: { env: options.overrideEnv } } : {}),
+		} as never,
+		context,
+	)
+
+	await manager.waitForCompletion(task.taskId)
+	return seen.config
+}
+
+describe('an environment survives a configBuilder that never heard of it', () => {
+	it('reaches a child whose builder sets none', async () => {
+		const config = await spawnWith({ overrideEnv: { API_BASE: 'https://staging' } })
+
+		expect(config?.env).toEqual({ API_BASE: 'https://staging' })
+	})
+
+	it('keeps the builder keys the caller did not restate', async () => {
+		// Why this is a merge and not an assignment: `configOverrides` is a
+		// Partial, so replacing the map would drop everything the builder set,
+		// and a caller overriding one variable is not saying the rest should
+		// vanish.
+		const config = await spawnWith({
+			builderEnv: { REGION: 'eu', TIER: 'free' },
+			overrideEnv: { TIER: 'paid' },
+		})
+
+		expect(config?.env).toEqual({ REGION: 'eu', TIER: 'paid' })
+	})
+
+	it('leaves the builder environment alone when nothing overrides it', async () => {
+		const config = await spawnWith({ builderEnv: { REGION: 'eu' } })
+
+		expect(config?.env).toEqual({ REGION: 'eu' })
+	})
+
+	it('gives a child with no environment undefined rather than an empty map', async () => {
+		// An agent that never had an environment must not gain an empty object
+		// that every reader then has to tell apart from a real one.
+		const config = await spawnWith({})
+
+		expect(config?.env).toBeUndefined()
+	})
+})

package/src/manager/agent/lifecycle.ts

@@ -36,6 +36,7 @@ import { ZERO_COST } from '../../utils/cost.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { generateTaskId } from '../../utils/id.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
+import { requireOpenProject } from '../project/lifecycle.js'
 import type { ThreadManager } from '../thread/lifecycle.js'
 
 /**
@@ -82,6 +83,25 @@ interface ChildSpawnRecord {
 	workspaceRef?: WorkspaceRef
 }
 
+/**
+ * Combine a child's own environment with what its parent passed down.
+ *
+ * Per key, override winning — not whole-value replacement, which would drop
+ * every key a `configBuilder` set and the caller did not happen to restate.
+ * `configOverrides` is a `Partial`, so replacement reads as "the caller
+ * supplied an environment" when what they supplied was one variable.
+ *
+ * Returns `undefined` when both sides are empty, so an agent that never had an
+ * environment does not gain an empty object it then has to be checked for.
+ */
+function mergeEnv(
+	base: Readonly<Record<string, string>> | undefined,
+	override: Readonly<Record<string, string>> | undefined,
+): Record<string, string> | undefined {
+	if (!base && !override) return undefined
+	return { ...base, ...override }
+}
+
 export class AgentManager {
 	private registry: AgentRegistry
 	private instances: Map<TaskId, AgentTask> = new Map()
@@ -289,6 +309,23 @@ export class AgentManager {
 			// covered the top-level run and nothing it delegated.
 			const inheritedHandler = options.configOverrides?.resumeHandler ?? context.resumeHandler
 			if (inheritedHandler) childConfig.resumeHandler = inheritedHandler
+
+			// And the environment, for the third time and the same reason.
+			//
+			// The bare-config branch below has always carried `env`; this one
+			// never did, so a delegate registered WITH a `configBuilder` — the
+			// normal way, and what every host in this repo does — silently ran
+			// with none of the environment its parent had been given. The
+			// builder is written by whoever registered the agent and cannot be
+			// expected to forward a field it was never told about, which is
+			// exactly why `parentSpan` and `resumeHandler` are stamped here too.
+			//
+			// Merged per key rather than replaced. `configOverrides` is a
+			// `Partial`, so assigning the whole map would drop every key the
+			// builder set and the caller did not restate — the override wins per
+			// key, the same direction it already wins for `model` and `effort`.
+			const inheritedEnv = mergeEnv(childConfig.env, options.configOverrides?.env)
+			if (inheritedEnv) childConfig.env = inheritedEnv
 		} else {
 			this.log.warn('No configBuilder, using bare config', {
 				agentId: options.agentId,
@@ -557,12 +594,11 @@ export class AgentManager {
 			)
 		}
 
-		const project = await store.getProject(context.projectId, context.tenantId)
-		if (!project) {
-			throw new Error(
-				`Project ${context.projectId} not found for tenant ${context.tenantId} — spawn rejected`,
-			)
-		}
+		// Same read that loads the limits, now also the gate: an archived
+		// workspace accepts no new session. It replaces a bare `getProject` +
+		// null check rather than adding a round-trip, because a gate that costs
+		// something is a gate someone eventually moves.
+		const project = await requireOpenProject(store, context.projectId, context.tenantId, 'spawn')
 
 		// Capacity: depth + width. Depth uses the parent session's ancestry
 		// chain; width counts existing direct children of the parent.

package/src/manager/index.ts

@@ -20,3 +20,6 @@ export { ThreadManager } from './thread/lifecycle.js'
 export type { ThreadManagerDeps } from './thread/lifecycle.js'
 
 export { AgentManager } from './agent/lifecycle.js'
+
+export { ProjectManager, requireOpenProject } from './project/lifecycle.js'
+export type { ProjectManagerDeps } from './project/lifecycle.js'

package/src/manager/project/__tests__/a-closed-workspace-takes-no-work.test.ts

@@ -0,0 +1,268 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { EMPTY_TOKEN_USAGE } from '../../../constants/limits.js'
+import { AgentRegistry } from '../../../registry/agent/definitions.js'
+import {
+	ProjectClosedError,
+	ProjectNotEmptyError,
+	StaleProjectError,
+} from '../../../session/errors.js'
+import { DefaultCapacityValidator } from '../../../session/handoff/capacity.js'
+import { SessionSummaryMaterializer } from '../../../session/summary/materialize.js'
+import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js'
+import { DiskSessionStore } from '../../../store/session/disk.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
+import type { 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 } from '../../../types/agent/task.js'
+import type { AgentId, TenantId } from '../../../types/ids/index.js'
+import type { SummaryId } from '../../../types/session/ids.js'
+import { ZERO_COST } from '../../../utils/cost.js'
+import { AgentManager } from '../../agent/lifecycle.js'
+import { ThreadManager } from '../../thread/lifecycle.js'
+import { ProjectManager } from '../lifecycle.js'
+
+/**
+ * Archiving a workspace meant nothing to the code.
+ *
+ * `Thread` carried a status and a gate; `Project` — the thing a tenant owns,
+ * configures, gives an environment, and actually closes — carried neither. So
+ * a host could archive a workspace and the kernel would keep spawning agents
+ * into it, because there was no state for the spawn path to read.
+ *
+ * The spawn case drives the real `AgentManager` rather than calling the gate
+ * directly. A test that calls `requireOpenProject` proves the function throws;
+ * what has to hold is that the spawn path reaches it, and the only assertion
+ * that cannot pass with the call deleted is one made through the front door.
+ */
+
+const TENANT = 'tnt_close' as TenantId
+
+function silentAgent(): Agent<BaseAgentConfig, BaseAgentResult> {
+	return {
+		type: 'reactive',
+		metadata: {
+			id: 'worker',
+			name: 'worker',
+			version: '1.0.0',
+			category: 'general',
+			description: 'does nothing',
+			type: 'reactive',
+			capabilities: {},
+		},
+		async run(): Promise<BaseAgentResult> {
+			return {
+				runId: 'run_child',
+				status: 'completed',
+				result: 'ok',
+				usage: { ...EMPTY_TOKEN_USAGE },
+				cost: { ...ZERO_COST },
+				iterations: 1,
+				durationMs: 0,
+				messages: [],
+			} as BaseAgentResult
+		},
+		async cancel() {},
+		getCapabilities() {
+			return {} as never
+		},
+	} as unknown as Agent<BaseAgentConfig, BaseAgentResult>
+}
+
+function definition(): AgentDefinition {
+	return {
+		info: {
+			id: 'worker',
+			name: 'worker',
+			version: '1.0.0',
+			category: 'general',
+			description: 'a worker',
+			tools: [],
+			defaults: { model: 'test', tokenBudget: 1_000 },
+		},
+		typedAgent: silentAgent(),
+	} as AgentDefinition
+}
+
+/** A parent session in a real workspace, plus the manager that spawns into it. */
+async function harness() {
+	const store = new InMemorySessionStore()
+	const threadStore = new InMemoryThreadStore()
+	const project = await store.createProject({ tenantId: TENANT, name: 'w' }, TENANT)
+	const thread = await threadStore.createThread({ projectId: project.id, title: 't' }, TENANT)
+	const parentActor = { kind: 'agent', agentId: 'sup' as AgentId, tenantId: TENANT } as const
+	const parentSession = await store.createSession(
+		{ threadId: thread.id, projectId: project.id, currentActor: parentActor },
+		TENANT,
+	)
+
+	const registry = new AgentRegistry()
+	registry.register(definition())
+
+	let n = 0
+	const manager = new AgentManager(registry, undefined, {
+		sessionStore: store,
+		threadManager: new ThreadManager({ threadStore, sessionStore: store }),
+		workspaceRegistry: new WorkspaceBackendRegistry(),
+		capacity: new DefaultCapacityValidator(store),
+		summaryMaterializer: new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: () => `sum_${++n}` as SummaryId,
+		}),
+	})
+
+	const context = {
+		parentRunId: 'run_parent' as never,
+		parentAgentId: 'sup',
+		parentAbortController: new AbortController(),
+		depth: 0,
+		budgetTracker: { total: 100_000, remaining: 100_000 },
+		tenantId: TENANT,
+		threadId: thread.id,
+		sessionId: parentSession.id,
+		projectId: project.id,
+		parentActor,
+	} as AgentTaskContext
+
+	const spawn = () =>
+		manager.sendMessage(
+			{
+				agentId: 'worker',
+				input: { messages: [], workingDirectory: '/tmp' } as never,
+				parentSessionId: parentSession.id,
+				tenantId: TENANT,
+			} as never,
+			context,
+		)
+
+	return { store, project, parentSession, projects: new ProjectManager({ store }), spawn }
+}
+
+describe('a closed workspace takes no new work', () => {
+	it('spawns while the workspace is open', async () => {
+		// The control. Without it, every assertion below could be passing
+		// because the harness cannot spawn at all.
+		const h = await harness()
+
+		await expect(h.spawn()).resolves.toBeDefined()
+	})
+
+	it('refuses a spawn into an archived workspace, through the real spawn path', async () => {
+		const h = await harness()
+		await h.projects.archive(h.project.id, TENANT)
+
+		await expect(h.spawn()).rejects.toBeInstanceOf(ProjectClosedError)
+	})
+
+	it('names the operation it refused', async () => {
+		// "Archived" alone does not tell a caller what they were denied.
+		const h = await harness()
+		await h.projects.archive(h.project.id, TENANT)
+
+		const error = await h.spawn().then(
+			() => null,
+			(e: unknown) => e,
+		)
+
+		expect((error as ProjectClosedError).details).toEqual({
+			projectId: h.project.id,
+			op: 'spawn',
+		})
+	})
+
+	it('spawns again after the workspace is reopened', async () => {
+		// Closing has to be reversible, or a mistaken archive is permanent.
+		const h = await harness()
+		await h.projects.archive(h.project.id, TENANT)
+		await h.projects.reopen(h.project.id, TENANT)
+
+		await expect(h.spawn()).resolves.toBeDefined()
+	})
+
+	it('refuses to close a workspace with a live session, and says which', async () => {
+		// Archival does not cascade and does not kill: a live session is a
+		// running agent whose owner is still watching.
+		const h = await harness()
+		await h.store.updateSession({ ...h.parentSession, status: 'active' }, TENANT)
+
+		const error = await h.projects.archive(h.project.id, TENANT).then(
+			() => null,
+			(e: unknown) => e,
+		)
+
+		expect(error).toBeInstanceOf(ProjectNotEmptyError)
+		const details = (error as ProjectNotEmptyError).details
+		expect(details.totalBlockingSessions).toBe(1)
+		expect(details.blockingSessions).toEqual([{ sessionId: h.parentSession.id, status: 'active' }])
+	})
+
+	it('closes a workspace whose sessions have settled', async () => {
+		const h = await harness()
+
+		const archived = await h.projects.archive(h.project.id, TENANT)
+
+		expect(archived.status).toBe('archived')
+		expect((await h.store.getProject(h.project.id, TENANT))?.status).toBe('archived')
+	})
+
+	it('re-archiving is a no-op that does not burn a version', async () => {
+		// An idempotent call that bumped the counter would invalidate a version
+		// a concurrent caller is holding, turning a retry into a conflict.
+		const h = await harness()
+		const first = await h.projects.archive(h.project.id, TENANT)
+
+		const second = await h.projects.archive(h.project.id, TENANT)
+
+		expect(second.ownerVersion).toBe(first.ownerVersion)
+	})
+
+	it('loses the second of two writes that read the same version', async () => {
+		// The store compares against what it holds, not against the caller's
+		// copy of it — the mistake the session CAS was written with first.
+		const h = await harness()
+		const read = await h.store.getProject(h.project.id, TENANT)
+		if (!read) throw new Error('project vanished')
+
+		await h.store.setProjectStatus?.(h.project.id, 'archived', TENANT, read.ownerVersion)
+
+		await expect(
+			h.store.setProjectStatus?.(h.project.id, 'open', TENANT, read.ownerVersion),
+		).rejects.toBeInstanceOf(StaleProjectError)
+	})
+})
+
+describe('a workspace stored before it had a status', () => {
+	const dirs: string[] = []
+	afterEach(async () => {
+		await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+		dirs.length = 0
+	})
+
+	it('reads as open at version 0, and can still be closed', async () => {
+		// Every project.json on disk today lacks both fields. Reading them as
+		// `undefined` would be worse than a wrong default: the compare-and-set
+		// would never match, so an existing workspace could never be closed.
+		const root = await mkdtemp(join(tmpdir(), 'namzu-oldproj-'))
+		dirs.push(root)
+		const store = new DiskSessionStore({ rootDir: root })
+		const project = await store.createProject({ tenantId: TENANT, name: 'w' }, TENANT)
+
+		const file = join(root, 'projects', project.id, 'project.json')
+		const raw = JSON.parse(await readFile(file, 'utf-8'))
+		raw.status = undefined
+		raw.ownerVersion = undefined
+		await writeFile(file, JSON.stringify(raw), 'utf-8')
+
+		const reloaded = await store.getProject(project.id, TENANT)
+		expect(reloaded?.status).toBe('open')
+		expect(reloaded?.ownerVersion).toBe(0)
+
+		const archived = await new ProjectManager({ store }).archive(project.id, TENANT)
+		expect(archived.status).toBe('archived')
+	})
+})