@namzu/sdk 13.1.0 → 14.0.1

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

package/src/manager/project/lifecycle.ts

@@ -0,0 +1,160 @@
+/**
+ * ProjectManager — open/close a workspace, and the gate the ingress paths read.
+ *
+ * This is the Thread archival model moved to the level that survives. Thread
+ * carried `status` and `ThreadManager.requireOpen`; Project — the thing a
+ * tenant actually owns, configures, and closes — carried nothing, so archiving
+ * a workspace meant nothing to the code. See the hierarchy plan.
+ *
+ * Two deliberate differences from the Thread version:
+ *
+ *   - Status moves **both ways**. A thread was archived forever; a workspace is
+ *     long-lived and a mistaken close should be recoverable.
+ *   - The gate is a **function over a store**, not a method on an injected
+ *     manager. The three ingress paths already hold a `SessionStore`, so
+ *     nothing has to be threaded through a constructor for the invariant to be
+ *     enforced — a gate that requires new wiring is a gate somebody forgets to
+ *     wire.
+ */
+
+import {
+	PROJECT_NOT_EMPTY_SAMPLE_LIMIT,
+	ProjectClosedError,
+	ProjectNotEmptyError,
+} from '../../session/errors.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type { Project } from '../../types/project/entity.js'
+import type { SessionStatus } from '../../types/session/entity.js'
+import type { ProjectId } from '../../types/session/ids.js'
+import type { SessionStore } from '../../types/session/store.js'
+
+/**
+ * Session statuses that block a workspace from closing.
+ *
+ * A live session is a running agent. Closing its workspace out from under it
+ * would strand work whose owner is still watching, so the caller settles the
+ * sessions first and archival never cascades.
+ */
+const ARCHIVAL_BLOCKING_STATUSES: ReadonlySet<SessionStatus> = new Set([
+	'active',
+	'locked',
+	'awaiting_merge',
+	'awaiting_hitl',
+])
+
+/**
+ * Load a Project and assert it accepts new work.
+ *
+ * Throws on absence — a missing project is a hard error, not an assumed-open
+ * one — and {@link ProjectClosedError} on an archived project. Returns the
+ * loaded Project so the caller can skip a second read; every current caller
+ * needs `config` immediately afterwards.
+ *
+ * `op` names the operation in the error, because "archived" is not by itself
+ * an explanation of what the caller was refused.
+ */
+export async function requireOpenProject(
+	store: Pick<SessionStore, 'getProject'>,
+	projectId: ProjectId,
+	tenantId: TenantId,
+	op: string,
+): Promise<Project> {
+	const project = await store.getProject(projectId, tenantId)
+	if (!project) {
+		throw new Error(`Project ${projectId} not found for tenant ${tenantId} — ${op} rejected`)
+	}
+	if (project.status === 'archived') {
+		throw new ProjectClosedError({ projectId, op })
+	}
+	return project
+}
+
+export interface ProjectManagerDeps {
+	store: SessionStore
+}
+
+export class ProjectManager {
+	constructor(private readonly deps: ProjectManagerDeps) {}
+
+	/** See {@link requireOpenProject}. */
+	requireOpen(projectId: ProjectId, tenantId: TenantId, op = 'require-open'): Promise<Project> {
+		return requireOpenProject(this.deps.store, projectId, tenantId, op)
+	}
+
+	/**
+	 * Close a workspace.
+	 *
+	 * Refuses while any attached session is non-terminal
+	 * ({@link ARCHIVAL_BLOCKING_STATUSES}), throwing {@link ProjectNotEmptyError}
+	 * with a sample of what is blocking. The presence check runs **before** the
+	 * already-archived short-circuit, so a workspace that is archived and still
+	 * harbouring a live session reports the live session rather than reporting
+	 * success — the second call is where an operator finds out.
+	 *
+	 * Idempotent: re-archiving an empty archived project is a no-op that
+	 * returns the stored record without a write, so it does not burn a version
+	 * and cannot lose a race it is not in.
+	 */
+	async archive(projectId: ProjectId, tenantId: TenantId): Promise<Project> {
+		const project = await this.deps.store.getProject(projectId, tenantId)
+		if (!project) {
+			throw new Error(`Project ${projectId} not found for tenant ${tenantId} — archive rejected`)
+		}
+
+		const sessions = (await this.deps.store.listSessionsByProject?.(projectId, tenantId)) ?? []
+		const blocking = sessions.filter((s) => ARCHIVAL_BLOCKING_STATUSES.has(s.status))
+		if (blocking.length > 0) {
+			throw new ProjectNotEmptyError({
+				projectId,
+				tenantId,
+				op: 'archive',
+				blockingSessions: blocking
+					.slice(0, PROJECT_NOT_EMPTY_SAMPLE_LIMIT)
+					.map((s) => ({ sessionId: s.id, status: s.status })),
+				totalBlockingSessions: blocking.length,
+			})
+		}
+
+		if (project.status === 'archived') return project
+		return this.write(projectId, 'archived', tenantId, project.ownerVersion)
+	}
+
+	/**
+	 * Reopen a workspace. Idempotent in the same way, and unconditional
+	 * otherwise: there is nothing a live session could make unsafe about
+	 * accepting work again.
+	 */
+	async reopen(projectId: ProjectId, tenantId: TenantId): Promise<Project> {
+		const project = await this.deps.store.getProject(projectId, tenantId)
+		if (!project) {
+			throw new Error(`Project ${projectId} not found for tenant ${tenantId} — reopen rejected`)
+		}
+		if (project.status === 'open') return project
+		return this.write(projectId, 'open', tenantId, project.ownerVersion)
+	}
+
+	private async write(
+		projectId: ProjectId,
+		status: Project['status'],
+		tenantId: TenantId,
+		expectedOwnerVersion: number,
+	): Promise<Project> {
+		const setStatus = this.deps.store.setProjectStatus
+		if (!setStatus) {
+			throw new Error(
+				`Project ${projectId} cannot be set to '${status}': this SessionStore does not implement setProjectStatus. A store without it cannot record the state, and pretending the write succeeded would leave the gate reading 'open' forever.`,
+			)
+		}
+		const written = await setStatus.call(
+			this.deps.store,
+			projectId,
+			status,
+			tenantId,
+			expectedOwnerVersion,
+		)
+		if (!written) {
+			throw new Error(`Project ${projectId} disappeared during '${status}' write`)
+		}
+		return written
+	}
+}

package/src/public-runtime.ts

@@ -225,6 +225,12 @@ export {
 	AgentManager,
 	EmergencySaveManager,
 	PlanManager,
+	ProjectManager,
+	// The gate itself, not only the manager that wraps it. A host writing its
+	// own ingress path — a custom handoff, a queue consumer that creates
+	// sessions — needs to refuse a closed workspace without constructing a
+	// manager, which is the reason it is a function over a store.
+	requireOpenProject,
 	RunPersistence,
 	ThreadManager,
 } from './manager/index.js'
@@ -483,6 +489,14 @@ export {
 
 export {
 	AncestryCycleError,
+	// Exported, unlike `ThreadClosedError`, because a host that closes a
+	// workspace has to be able to tell "this workspace is closed" from any
+	// other spawn failure — and matching on a message string is not a
+	// contract. The comment below is the reason; these are the first three
+	// that take it seriously.
+	ProjectClosedError,
+	ProjectNotEmptyError,
+	StaleProjectError,
 	// 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

package/src/session/errors.ts

@@ -9,7 +9,7 @@
 
 import type { SessionId, TenantId } from '../types/ids/index.js'
 import type { SessionStatus } from '../types/session/entity.js'
-import type { ThreadId } from '../types/session/ids.js'
+import type { ProjectId, ThreadId } from '../types/session/ids.js'
 import type { WorkspaceBackendKind } from './workspace/driver.js'
 
 /**
@@ -186,3 +186,87 @@ export class ThreadNotEmptyError extends Error {
 		this.details = details
 	}
 }
+
+/**
+ * Raised when an ingress path is asked to attach work to an archived Project.
+ *
+ * The sibling of {@link ThreadClosedError}, on the level that survives. A
+ * closed workspace is a decision by its owner, and the paths that create
+ * sessions have to be able to see it — otherwise "archived" is a word in a
+ * listing rather than a state of the system.
+ */
+export class ProjectClosedError extends Error {
+	readonly details: {
+		projectId: ProjectId
+		op: string
+	}
+
+	constructor(details: { projectId: ProjectId; op: string }) {
+		super(`Project ${details.projectId} is archived; operation '${details.op}' rejected`)
+		this.name = 'ProjectClosedError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised by the project archive path when sessions are still attached and not
+ * in a terminal state.
+ *
+ * Archiving does not cascade and does not kill anything: a live session is a
+ * running agent, and closing its workspace out from under it would strand
+ * work whose owner is still watching. The caller settles the sessions first.
+ * `blockingSessions` is truncated to {@link PROJECT_NOT_EMPTY_SAMPLE_LIMIT};
+ * `totalBlockingSessions` is the real count.
+ */
+export const PROJECT_NOT_EMPTY_SAMPLE_LIMIT = 50
+
+export class ProjectNotEmptyError extends Error {
+	readonly details: {
+		projectId: ProjectId
+		tenantId: TenantId
+		op: 'archive'
+		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		totalBlockingSessions: number
+	}
+
+	constructor(details: {
+		projectId: ProjectId
+		tenantId: TenantId
+		op: 'archive'
+		blockingSessions: ReadonlyArray<{ sessionId: SessionId; status: SessionStatus }>
+		totalBlockingSessions: number
+	}) {
+		super(
+			`Project ${details.projectId} ${details.op} blocked: ${details.totalBlockingSessions} session(s) still attached`,
+		)
+		this.name = 'ProjectNotEmptyError'
+		this.details = details
+	}
+}
+
+/**
+ * Raised when a project status write loses a compare-and-set.
+ *
+ * The sibling of {@link StaleSessionError}: the caller re-reads and decides
+ * again, because the project it was about to close is not the project on
+ * disk.
+ */
+export class StaleProjectError extends Error {
+	readonly details: {
+		projectId: ProjectId
+		expectedOwnerVersion: number
+		actualOwnerVersion: number
+	}
+
+	constructor(details: {
+		projectId: ProjectId
+		expectedOwnerVersion: number
+		actualOwnerVersion: number
+	}) {
+		super(
+			`Project ${details.projectId} was modified concurrently: expected ownerVersion ${details.expectedOwnerVersion}, found ${details.actualOwnerVersion}`,
+		)
+		this.name = 'StaleProjectError'
+		this.details = details
+	}
+}

package/src/session/handoff/broadcast.ts

@@ -21,6 +21,7 @@
  * ```
  */
 
+import { requireOpenProject } from '../../manager/project/lifecycle.js'
 import type { ThreadManager } from '../../manager/thread/lifecycle.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Session } from '../../types/session/entity.js'
@@ -189,11 +190,9 @@ export async function executeBroadcastHandoff(
 	}
 
 	// 6. Capacity — width + depth. Width covers N new children in one shot
-	//    (§6.5); depth covers `source.depth + 1 ≤ maxDepth`.
-	const project = await deps.store.getProject(source.projectId, tenantId)
-	if (!project) {
-		throw new Error(`Project ${source.projectId} not found`)
-	}
+	//    (§6.5); depth covers `source.depth + 1 ≤ maxDepth`. The same read is
+	//    the archive gate: a closed workspace takes no broadcast either.
+	const project = await requireOpenProject(deps.store, source.projectId, tenantId, 'broadcast')
 	await deps.capacity.validateWidth(
 		source.id,
 		assignments.length,

package/src/session/handoff/single.ts

@@ -20,6 +20,7 @@
  *   9. Emit `onCommitted` with the new version.
  */
 
+import { requireOpenProject } from '../../manager/project/lifecycle.js'
 import type { ThreadManager } from '../../manager/thread/lifecycle.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Session } from '../../types/session/entity.js'
@@ -145,10 +146,10 @@ export async function executeSingleHandoff(
 	//    ownership of the same session. Width only applies to broadcast).
 	//    For `single` we still validate depth to future-proof should the flow
 	//    evolve into a branch variant.
-	const project = await deps.store.getProject(source.projectId, tenantId)
-	if (!project) {
-		throw new Error(`Project ${source.projectId} not found`)
-	}
+	//    The same read is the archive gate: an archived workspace accepts no
+	//    handoff either. Transferring ownership into a closed workspace would
+	//    be a new owner for work its project says is finished.
+	const project = await requireOpenProject(deps.store, source.projectId, tenantId, 'handoff')
 	await deps.capacity.validateDepth(source.id, project.config.maxDelegationDepth, tenantId)
 
 	// 5. CAS → `idle → locked`.

package/src/session/migration/__tests__/a-migrated-project-id-is-an-id.test.ts

@@ -0,0 +1,92 @@
+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 { ProjectIdSchema } from '../../../contracts/schemas.js'
+import { FilesystemMigrationError } from '../errors.js'
+import { DefaultFilesystemMigrator, NOOP_FILESYSTEM_MIGRATION_SINK } from '../filesystem.js'
+
+/**
+ * The v0.2.0 migration is the only place a `ProjectId` is built from data
+ * instead of generated: it takes a legacy `thd_*` folder name off disk and
+ * mints `prj_legacy_<that name>`. The only check the name had passed was
+ * `startsWith('thd_')`, so a folder named `thd_Not An Id` produced a project
+ * id that satisfies the TypeScript type, is written into the new layout as a
+ * directory name, and is rejected by the SDK's own `ProjectIdSchema`.
+ *
+ * It refuses such a folder rather than skipping it. Skipping would leave that
+ * thread's runs on disk and unaddressable, write the completion marker anyway,
+ * and return `kind: 'migrated'` with the thread missing from the list — the
+ * failure shape this codebase keeps meeting, where the run did not fail, it
+ * succeeded while quietly not doing what it said.
+ */
+
+const dirs: string[] = []
+afterEach(async () => {
+	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+	dirs.length = 0
+})
+
+async function seed(root: string, folder: string): Promise<void> {
+	const dir = join(root, 'threads', folder, 'runs', 'run_seed')
+	await mkdir(dir, { recursive: true })
+	await writeFile(join(dir, 'run.json'), JSON.stringify({ id: 'run_seed' }), 'utf-8')
+}
+
+async function newRoot(tag: string): Promise<string> {
+	const root = await mkdtemp(join(tmpdir(), `namzu-mig-${tag}-`))
+	dirs.push(root)
+	return root
+}
+
+describe('the migration only mints project ids that are project ids', () => {
+	it('refuses a legacy folder whose name is not a thread id, and names it', async () => {
+		const root = await newRoot('badname')
+		await seed(root, 'thd_Not An Id')
+
+		const error = await new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK)
+			.migrate(root)
+			.then(
+				() => null,
+				(e: unknown) => e,
+			)
+
+		expect(error).toBeInstanceOf(FilesystemMigrationError)
+		const details = (error as FilesystemMigrationError).details
+		expect(details.op).toBe('validate_thread_id')
+		// An operator has to be able to go and look at the folder.
+		expect(details.path).toContain('thd_Not An Id')
+	})
+
+	it('refuses rather than reporting a migration that left a thread behind', async () => {
+		// The seductive alternative is `continue`. This pins why it is wrong:
+		// the good thread would migrate, the result would say `migrated`, and
+		// the bad one would be absent from `migratedThreads` with no error.
+		const root = await newRoot('partial')
+		await seed(root, 'thd_a1b2c3d4e5f6')
+		await seed(root, 'thd_UPPER')
+
+		await expect(
+			new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK).migrate(root),
+		).rejects.toBeInstanceOf(FilesystemMigrationError)
+	})
+
+	it('still migrates a folder whose name is a thread id, and the id it mints validates', async () => {
+		// The guard must refuse only what is not an id. A guard that refuses
+		// everything passes the two cases above and breaks migration entirely.
+		const root = await newRoot('good')
+		await seed(root, 'thd_a1b2c3d4e5f6')
+
+		const result = await new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK).migrate(root)
+
+		expect(result.kind).toBe('migrated')
+		expect(result.migratedThreads.map((m) => m.legacyThreadId)).toEqual(['thd_a1b2c3d4e5f6'])
+		for (const { newProjectId } of result.migratedThreads) {
+			expect({ newProjectId, ok: ProjectIdSchema.safeParse(newProjectId).success }).toEqual({
+				newProjectId,
+				ok: true,
+			})
+		}
+	})
+})