@kodrunhq/opencode-autopilot 1.15.2 → 1.16.0

package/src/orchestrator/handlers/build.ts

@@ -45,6 +45,30 @@ function findInProgressTasks(
 	return tasks.filter((t) => t.status === "IN_PROGRESS");
 }
 
+function buildPendingResultError(
+	wave: number,
+	inProgressTasks: readonly Task[],
+	buildProgress: Readonly<BuildProgress>,
+	updatedTasks?: readonly Task[],
+): DispatchResult {
+	const taskIds = inProgressTasks.map((task) => task.id);
+	return Object.freeze({
+		action: "error",
+		code: "E_BUILD_RESULT_PENDING",
+		phase: "BUILD",
+		message: `Wave ${wave} still has in-progress task result(s) pending for taskIds [${taskIds.join(", ")}]. Wait for the typed result envelope and pass it back to oc_orchestrate.`,
+		progress: `Wave ${wave} — waiting for typed result(s) for taskIds [${taskIds.join(", ")}]`,
+		_stateUpdates: {
+			...(updatedTasks ? { tasks: [...updatedTasks] } : {}),
+			buildProgress: {
+				...buildProgress,
+				currentWave: wave,
+				currentTask: buildProgress.currentTask ?? inProgressTasks[0]?.id ?? null,
+			},
+		},
+	} satisfies DispatchResult);
+}
+
 /**
  * Mark multiple tasks as IN_PROGRESS immutably.
  */
@@ -214,6 +238,7 @@ export const handleBuild: PhaseHandler = async (
 				_stateUpdates: {
 					buildProgress: {
 						...buildProgress,
+						reviewPending: false,
 						strikeCount: buildProgress.strikeCount + 1,
 					},
 				},
@@ -232,6 +257,7 @@ export const handleBuild: PhaseHandler = async (
 				_stateUpdates: {
 					buildProgress: {
 						...buildProgress,
+						currentTask: null,
 						reviewPending: false,
 					},
 				},
@@ -239,13 +265,18 @@ export const handleBuild: PhaseHandler = async (
 		}
 
 		const pendingTasks = findPendingTasks(waveMap, nextWave);
+		const inProgressTasks = findInProgressTasks(waveMap, nextWave);
 		const updatedProgress: BuildProgress = {
 			...buildProgress,
 			reviewPending: false,
 			currentWave: nextWave,
 		};
 
-		if (pendingTasks.length === 1) {
+		if (pendingTasks.length === 0 && inProgressTasks.length > 0) {
+			return buildPendingResultError(nextWave, inProgressTasks, updatedProgress);
+		}
+
+		if (pendingTasks.length > 0) {
 			const task = pendingTasks[0];
 			const prompt = await buildTaskPrompt(task, artifactDir);
 			return Object.freeze({
@@ -257,62 +288,25 @@ export const handleBuild: PhaseHandler = async (
 				taskId: task.id,
 				progress: `Wave ${nextWave} — task ${task.id}`,
 				_stateUpdates: {
+					tasks: [...markTasksInProgress(effectiveTasks, [task.id])],
 					buildProgress: { ...updatedProgress, currentTask: task.id },
 				},
 			} satisfies DispatchResult);
 		}
 
-		const dispatchedIds = pendingTasks.map((t) => t.id);
-		const promptsByTaskId = new Map<number, string>();
-		await Promise.all(
-			pendingTasks.map(async (task) => {
-				promptsByTaskId.set(task.id, await buildTaskPrompt(task, artifactDir));
-			}),
-		);
 		return Object.freeze({
-			action: "dispatch_multi",
-			agents: pendingTasks.map((task) => ({
-				agent: AGENT_NAMES.BUILD,
-				prompt: promptsByTaskId.get(task.id) ?? "",
-				taskId: task.id,
-				resultKind: "task_completion" as const,
-			})),
+			action: "error",
+			code: "E_BUILD_NO_DISPATCHABLE_TASK",
 			phase: "BUILD",
-			progress: `Wave ${nextWave} — ${pendingTasks.length} concurrent tasks`,
-			_stateUpdates: {
-				tasks: [...markTasksInProgress(effectiveTasks, dispatchedIds)],
-				buildProgress: { ...updatedProgress, currentTask: null },
-			},
+			message: `Wave ${nextWave} has no dispatchable pending tasks.`,
 		} satisfies DispatchResult);
 	}
 
 	// Case 2: Result provided + not review pending -> mark task done
-	// For dispatch_multi, currentTask may be null — find the first IN_PROGRESS task instead
-	const hasTypedContext = context !== undefined && !context.legacy;
+	const hasTypedContext = context !== undefined;
 	const isTaskCompletion = hasTypedContext && context.envelope.kind === "task_completion";
-	const isLegacyContext = context !== undefined && context.legacy;
-	const taskToComplete = isTaskCompletion
-		? context.envelope.taskId
-		: hasTypedContext
-			? buildProgress.currentTask
-			: (buildProgress.currentTask ??
-				effectiveTasks.find((t) => t.status === "IN_PROGRESS")?.id ??
-				null);
-
-	if (
-		resultText &&
-		!buildProgress.reviewPending &&
-		isLegacyContext &&
-		buildProgress.currentTask === null
-	) {
-		return Object.freeze({
-			action: "error",
-			code: "E_BUILD_TASK_ID_REQUIRED",
-			phase: "BUILD",
-			message:
-				"Legacy BUILD result cannot be attributed when currentTask is null. Submit typed envelope with taskId.",
-		} satisfies DispatchResult);
-	}
+	const taskToComplete = isTaskCompletion ? context.envelope.taskId : buildProgress.currentTask;
+
 	if (resultText && !buildProgress.reviewPending && taskToComplete === null) {
 		return Object.freeze({
 			action: "error",
@@ -349,7 +343,7 @@ export const handleBuild: PhaseHandler = async (
 					tasks: [...updatedTasks],
 					buildProgress: {
 						...buildProgress,
-						currentTask: null,
+						currentTask: taskToComplete,
 						reviewPending: true,
 					},
 				},
@@ -370,7 +364,7 @@ export const handleBuild: PhaseHandler = async (
 				taskId: next.id,
 				progress: `Wave ${currentWave} — task ${next.id}`,
 				_stateUpdates: {
-					tasks: [...updatedTasks],
+					tasks: [...markTasksInProgress(updatedTasks, [next.id])],
 					buildProgress: {
 						...buildProgress,
 						currentTask: next.id,
@@ -382,21 +376,7 @@ export const handleBuild: PhaseHandler = async (
 		// No pending tasks but wave not complete — other tasks are still IN_PROGRESS
 		const inProgressInWave = findInProgressTasks(waveMap, currentWave);
 		if (inProgressInWave.length > 0) {
-			return Object.freeze({
-				action: "dispatch",
-				agent: AGENT_NAMES.BUILD,
-				prompt: `Wave ${currentWave} has ${inProgressInWave.length} task(s) still in progress. Continue working on remaining tasks.`,
-				phase: "BUILD",
-				resultKind: "phase_output",
-				progress: `Wave ${currentWave} — waiting for ${inProgressInWave.length} in-progress task(s)`,
-				_stateUpdates: {
-					tasks: [...updatedTasks],
-					buildProgress: {
-						...buildProgress,
-						currentTask: null,
-					},
-				},
-			} satisfies DispatchResult);
+			return buildPendingResultError(currentWave, inProgressInWave, buildProgress, updatedTasks);
 		}
 	}
 
@@ -417,23 +397,7 @@ export const handleBuild: PhaseHandler = async (
 	const inProgressTasks = findInProgressTasks(waveMap, currentWave);
 
 	if (pendingTasks.length === 0 && inProgressTasks.length > 0) {
-		// Wave has only IN_PROGRESS tasks (e.g., resume after dispatch_multi).
-		// Return a dispatch instruction so the orchestrator knows work is underway.
-		return Object.freeze({
-			action: "dispatch",
-			agent: AGENT_NAMES.BUILD,
-			prompt: `Resume: wave ${currentWave} has ${inProgressTasks.length} task(s) still in progress. Wait for agent results and pass them back.`,
-			phase: "BUILD",
-			resultKind: "phase_output",
-			progress: `Wave ${currentWave} — waiting for ${inProgressTasks.length} in-progress task(s)`,
-			_stateUpdates: {
-				buildProgress: {
-					...buildProgress,
-					currentWave,
-					currentTask: null,
-				},
-			},
-		} satisfies DispatchResult);
+		return buildPendingResultError(currentWave, inProgressTasks, buildProgress);
 	}
 
 	if (pendingTasks.length === 0) {
@@ -457,6 +421,7 @@ export const handleBuild: PhaseHandler = async (
 			taskId: task.id,
 			progress: `Wave ${currentWave} — task ${task.id}`,
 			_stateUpdates: {
+				tasks: [...markTasksInProgress(effectiveTasks, [task.id])],
 				buildProgress: {
 					...buildProgress,
 					currentTask: task.id,
@@ -466,29 +431,22 @@ export const handleBuild: PhaseHandler = async (
 		} satisfies DispatchResult);
 	}
 
-	// Multiple pending tasks in wave -> dispatch_multi
-	const dispatchedIds = pendingTasks.map((t) => t.id);
-	const promptsByTaskId = new Map<number, string>();
-	await Promise.all(
-		pendingTasks.map(async (task) => {
-			promptsByTaskId.set(task.id, await buildTaskPrompt(task, artifactDir));
-		}),
-	);
+	// Multiple pending tasks in wave -> dispatch only the next task sequentially.
+	const task = pendingTasks[0];
+	const prompt = await buildTaskPrompt(task, artifactDir);
 	return Object.freeze({
-		action: "dispatch_multi",
-		agents: pendingTasks.map((task) => ({
-			agent: AGENT_NAMES.BUILD,
-			prompt: promptsByTaskId.get(task.id) ?? "",
-			taskId: task.id,
-			resultKind: "task_completion" as const,
-		})),
+		action: "dispatch",
+		agent: AGENT_NAMES.BUILD,
+		prompt,
 		phase: "BUILD",
-		progress: `Wave ${currentWave} — ${pendingTasks.length} concurrent tasks`,
+		resultKind: "task_completion",
+		taskId: task.id,
+		progress: `Wave ${currentWave} — task ${task.id}`,
 		_stateUpdates: {
-			tasks: [...markTasksInProgress(effectiveTasks, dispatchedIds)],
+			tasks: [...markTasksInProgress(effectiveTasks, [task.id])],
 			buildProgress: {
 				...buildProgress,
-				currentTask: null,
+				currentTask: task.id,
 				currentWave,
 			},
 		},

package/src/orchestrator/handlers/retrospective.ts

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { getProjectRootFromArtifactDir } from "../../utils/paths";
 import { getArtifactRef, PHASE_ARTIFACTS } from "../artifacts";
 import {
 	createEmptyLessonMemory,
@@ -81,7 +82,7 @@ export const handleRetrospective: PhaseHandler = async (_state, artifactDir, res
 
 		// Persist lessons to memory (best-effort: failure should not mark pipeline as FAILED)
 		try {
-			const projectRoot = join(artifactDir, "..");
+			const projectRoot = getProjectRootFromArtifactDir(artifactDir);
 			const existing = await loadLessonMemory(projectRoot);
 			const memory = existing ?? createEmptyLessonMemory();
 			const merged = [...memory.lessons, ...valid];

package/src/orchestrator/handlers/types.ts

@@ -40,7 +40,6 @@ export interface DispatchResult {
 
 export interface PhaseHandlerContext {
 	readonly envelope: ResultEnvelope;
-	readonly legacy: boolean;
 }
 
 export type PhaseHandler = (

package/src/orchestrator/lesson-memory.ts

@@ -1,8 +1,9 @@
 /**
  * Per-project lesson memory persistence.
  *
- * Stores lessons extracted from pipeline runs at
- * {projectRoot}/.opencode-autopilot/lesson-memory.json
+ * Stores lessons extracted from pipeline runs in the project kernel,
+ * with {projectRoot}/.opencode-autopilot/lesson-memory.json kept as a
+ * compatibility mirror/export during the Phase 4 migration window.
  *
  * Memory is pruned on load to remove stale entries (>90 days)
  * and cap at 50 lessons. All writes are atomic (tmp file + rename)
@@ -12,7 +13,9 @@
 import { randomBytes } from "node:crypto";
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { loadLessonMemoryFromKernel, saveLessonMemoryToKernel } from "../kernel/repository";
 import { ensureDir, isEnoentError } from "../utils/fs-helpers";
+import { getProjectArtifactDir } from "../utils/paths";
 import { lessonMemorySchema } from "./lesson-schemas";
 import type { LessonMemory } from "./lesson-types";
 
@@ -21,6 +24,7 @@ export type { LessonMemory };
 const LESSON_FILE = "lesson-memory.json";
 const MAX_LESSONS = 50;
 const NINETY_DAYS_MS = 90 * 24 * 60 * 60 * 1000;
+let legacyLessonMemoryMirrorWarned = false;
 
 /**
  * Create a valid empty lesson memory object.
@@ -41,6 +45,11 @@ export function createEmptyLessonMemory(): LessonMemory {
  * Prunes on load to remove stale entries and cap storage.
  */
 export async function loadLessonMemory(projectRoot: string): Promise<LessonMemory | null> {
+	const kernelMemory = loadLessonMemoryFromKernel(getProjectArtifactDir(projectRoot));
+	if (kernelMemory !== null) {
+		return pruneLessons(kernelMemory);
+	}
+
 	const memoryPath = join(projectRoot, ".opencode-autopilot", LESSON_FILE);
 	try {
 		const raw = await readFile(memoryPath, "utf-8");
@@ -51,7 +60,9 @@ export async function loadLessonMemory(projectRoot: string): Promise<LessonMemor
 			...parsed,
 			lessons: Array.isArray(parsed.lessons) ? parsed.lessons : [],
 		});
-		return lessonMemorySchema.parse(pruned);
+		const validated = lessonMemorySchema.parse(pruned);
+		saveLessonMemoryToKernel(getProjectArtifactDir(projectRoot), validated);
+		return validated;
 	} catch (error: unknown) {
 		if (isEnoentError(error)) {
 			return null;
@@ -74,12 +85,21 @@ export async function loadLessonMemory(projectRoot: string): Promise<LessonMemor
  */
 export async function saveLessonMemory(memory: LessonMemory, projectRoot: string): Promise<void> {
 	const validated = lessonMemorySchema.parse(memory);
-	const dir = join(projectRoot, ".opencode-autopilot");
-	await ensureDir(dir);
-	const memoryPath = join(dir, LESSON_FILE);
-	const tmpPath = `${memoryPath}.tmp.${randomBytes(8).toString("hex")}`;
-	await writeFile(tmpPath, JSON.stringify(validated, null, 2), "utf-8");
-	await rename(tmpPath, memoryPath);
+	saveLessonMemoryToKernel(getProjectArtifactDir(projectRoot), validated);
+
+	try {
+		const dir = join(projectRoot, ".opencode-autopilot");
+		await ensureDir(dir);
+		const memoryPath = join(dir, LESSON_FILE);
+		const tmpPath = `${memoryPath}.tmp.${randomBytes(8).toString("hex")}`;
+		await writeFile(tmpPath, JSON.stringify(validated, null, 2), "utf-8");
+		await rename(tmpPath, memoryPath);
+	} catch (error: unknown) {
+		if (!legacyLessonMemoryMirrorWarned) {
+			legacyLessonMemoryMirrorWarned = true;
+			console.warn("[opencode-autopilot] lesson-memory.json mirror write failed:", error);
+		}
+	}
 }
 
 /**

package/src/orchestrator/orchestration-logger.ts

@@ -1,5 +1,4 @@
-import { appendFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { appendForensicEventForArtifactDir } from "../observability/forensic-log";
 
 export interface OrchestrationEvent {
 	readonly timestamp: string;
@@ -9,32 +8,47 @@ export interface OrchestrationEvent {
 	readonly promptLength?: number;
 	readonly attempt?: number;
 	readonly message?: string;
+	readonly runId?: string;
+	readonly dispatchId?: string;
+	readonly taskId?: number | null;
+	readonly code?: string;
+	readonly sessionId?: string;
+	readonly payload?: Record<string, string | number | boolean | null>;
 }
 
-const LOG_FILE = "orchestration.jsonl";
-
-/** Rate-limit: warn about log failures at most once per process. */
-let logWriteWarned = false;
-
 /**
  * Append an orchestration event to the project-local JSONL log.
  * Uses synchronous append to survive crashes. Best-effort — errors are swallowed.
  */
 export function logOrchestrationEvent(artifactDir: string, event: OrchestrationEvent): void {
-	try {
-		mkdirSync(artifactDir, { recursive: true });
-		const logPath = join(artifactDir, LOG_FILE);
-		// Redact filesystem paths from message to avoid leaking sensitive directory info
-		const safe = event.message
-			? { ...event, message: event.message.replace(/[/\\][^\s"']+/g, "[PATH]") }
-			: event;
-		const line = `${JSON.stringify(safe)}\n`;
-		appendFileSync(logPath, line, "utf-8");
-	} catch (err) {
-		// Best-effort — never block the pipeline. Warn once so operators know logging is broken.
-		if (!logWriteWarned) {
-			logWriteWarned = true;
-			console.warn("[opencode-autopilot] orchestration log write failed:", err);
-		}
-	}
+	appendForensicEventForArtifactDir(artifactDir, {
+		timestamp: event.timestamp,
+		domain: event.action === "error" && event.code?.startsWith("E_") ? "contract" : "orchestrator",
+		runId: event.runId ?? null,
+		sessionId: event.sessionId ?? null,
+		phase: event.phase,
+		dispatchId: event.dispatchId ?? null,
+		taskId: event.taskId ?? null,
+		agent: event.agent ?? null,
+		type:
+			event.action === "dispatch"
+				? "dispatch"
+				: event.action === "dispatch_multi"
+					? "dispatch_multi"
+					: event.action === "complete"
+						? "complete"
+						: event.action === "loop_detected"
+							? "loop_detected"
+							: event.action === "error" && event.code?.startsWith("E_")
+								? "warning"
+								: "error",
+		code: event.code ?? null,
+		message: event.message ?? null,
+		payload: {
+			action: event.action,
+			...(event.promptLength !== undefined ? { promptLength: event.promptLength } : {}),
+			...(event.attempt !== undefined ? { attempt: event.attempt } : {}),
+			...(event.payload ?? {}),
+		},
+	});
 }

package/src/orchestrator/phase.ts

@@ -1,3 +1,4 @@
+import { patchState } from "./state";
 import type { Phase, PhaseStatus, PipelineState } from "./types";
 
 /** Maps each phase to its 1-based position for user-facing progress display. */
@@ -71,12 +72,15 @@ export function completePhase(state: Readonly<PipelineState>): PipelineState {
 		return phase;
 	});
 
-	return {
-		...state,
+	return patchState(state, {
+		status: nextPhase === null ? "COMPLETED" : state.status,
 		currentPhase: nextPhase,
 		phases: updatedPhases,
-		lastUpdatedAt: new Date().toISOString(),
-	};
+		pendingDispatches:
+			nextPhase === null
+				? []
+				: state.pendingDispatches.filter((entry) => entry.phase === nextPhase),
+	});
 }
 
 /**

package/src/orchestrator/state.ts

@@ -1,12 +1,15 @@
 import { randomBytes } from "node:crypto";
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { loadLatestPipelineStateFromKernel, savePipelineStateToKernel } from "../kernel/repository";
+import { KERNEL_STATE_CONFLICT_CODE } from "../kernel/types";
 import { ensureDir, isEnoentError } from "../utils/fs-helpers";
 import { assertStateInvariants } from "./contracts/invariants";
 import { PHASES, pipelineStateSchema } from "./schemas";
 import type { PipelineState } from "./types";
 
 const STATE_FILE = "state.json";
+let legacyStateMirrorWarned = false;
 
 function generateRunId(): string {
 	return `run_${randomBytes(8).toString("hex")}`;
@@ -37,12 +40,14 @@ export function createInitialState(idea: string): PipelineState {
 	});
 }
 
-export async function loadState(artifactDir: string): Promise<PipelineState | null> {
+async function loadLegacyState(artifactDir: string): Promise<PipelineState | null> {
 	const statePath = join(artifactDir, STATE_FILE);
 	try {
 		const raw = await readFile(statePath, "utf-8");
 		const parsed = JSON.parse(raw);
-		return pipelineStateSchema.parse(parsed);
+		const validated = pipelineStateSchema.parse(parsed);
+		assertStateInvariants(validated);
+		return validated;
 	} catch (error: unknown) {
 		if (isEnoentError(error)) {
 			return null;
@@ -51,28 +56,85 @@ export async function loadState(artifactDir: string): Promise<PipelineState | nu
 	}
 }
 
+async function writeLegacyStateMirror(state: PipelineState, artifactDir: string): Promise<void> {
+	await ensureDir(artifactDir);
+	const statePath = join(artifactDir, STATE_FILE);
+	const tmpPath = `${statePath}.tmp.${randomBytes(8).toString("hex")}`;
+	await writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
+	await rename(tmpPath, statePath);
+}
+
+async function syncLegacyStateMirror(state: PipelineState, artifactDir: string): Promise<void> {
+	try {
+		await writeLegacyStateMirror(state, artifactDir);
+	} catch (error: unknown) {
+		if (!legacyStateMirrorWarned) {
+			legacyStateMirrorWarned = true;
+			console.warn("[opencode-autopilot] state.json mirror write failed:", error);
+		}
+	}
+}
+
+export async function loadState(artifactDir: string): Promise<PipelineState | null> {
+	const kernelState = loadLatestPipelineStateFromKernel(artifactDir);
+	if (kernelState !== null) {
+		return kernelState;
+	}
+
+	const legacyState = await loadLegacyState(artifactDir);
+	if (legacyState === null) {
+		return null;
+	}
+
+	savePipelineStateToKernel(artifactDir, legacyState);
+	return legacyState;
+}
+
 export async function saveState(
 	state: PipelineState,
 	artifactDir: string,
 	expectedRevision?: number,
 ): Promise<void> {
-	if (typeof expectedRevision === "number") {
-		const current = await loadState(artifactDir);
-		const currentRevision = current?.stateRevision ?? -1;
-		if (currentRevision !== expectedRevision) {
-			throw new Error(
-				`E_STATE_CONFLICT: expected stateRevision ${expectedRevision}, found ${currentRevision}`,
-			);
-		}
-	}
-
 	const validated = pipelineStateSchema.parse(state);
 	assertStateInvariants(validated);
-	await ensureDir(artifactDir);
-	const statePath = join(artifactDir, STATE_FILE);
-	const tmpPath = `${statePath}.tmp.${randomBytes(8).toString("hex")}`;
-	await writeFile(tmpPath, JSON.stringify(validated, null, 2), "utf-8");
-	await rename(tmpPath, statePath);
+	savePipelineStateToKernel(artifactDir, validated, expectedRevision);
+	await syncLegacyStateMirror(validated, artifactDir);
+}
+
+export function isStateConflictError(error: unknown): boolean {
+	return error instanceof Error && error.message.startsWith(`${KERNEL_STATE_CONFLICT_CODE}:`);
+}
+
+export async function updatePersistedState(
+	artifactDir: string,
+	state: Readonly<PipelineState>,
+	transform: (current: Readonly<PipelineState>) => PipelineState,
+	options?: { readonly maxConflicts?: number },
+): Promise<PipelineState> {
+	const maxConflicts = options?.maxConflicts ?? 2;
+	let currentState = state;
+
+	for (let attempt = 0; ; attempt += 1) {
+		const nextState = transform(currentState);
+		if (nextState === currentState) {
+			return currentState;
+		}
+
+		try {
+			await saveState(nextState, artifactDir, currentState.stateRevision);
+			return nextState;
+		} catch (error: unknown) {
+			if (!isStateConflictError(error) || attempt >= maxConflicts) {
+				throw error;
+			}
+
+			const latestState = await loadState(artifactDir);
+			if (latestState === null) {
+				throw new Error(`${KERNEL_STATE_CONFLICT_CODE}: state disappeared during update`);
+			}
+			currentState = latestState;
+		}
+	}
 }
 
 export function patchState(

package/src/projects/database.ts

@@ -0,0 +1,47 @@
+import type { Database } from "bun:sqlite";
+
+export const PROJECT_REGISTRY_STATEMENTS: readonly string[] = Object.freeze([
+	`CREATE TABLE IF NOT EXISTS projects (
+		id TEXT PRIMARY KEY,
+		path TEXT NOT NULL UNIQUE,
+		name TEXT NOT NULL,
+		first_seen_at TEXT NOT NULL,
+		last_updated TEXT NOT NULL
+	)`,
+	`CREATE TABLE IF NOT EXISTS project_paths (
+		project_id TEXT NOT NULL,
+		path TEXT NOT NULL,
+		first_seen_at TEXT NOT NULL,
+		last_updated TEXT NOT NULL,
+		is_current INTEGER NOT NULL CHECK(is_current IN (0, 1)),
+		PRIMARY KEY (project_id, path),
+		UNIQUE(path),
+		FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+	)`,
+	`CREATE INDEX IF NOT EXISTS idx_project_paths_project ON project_paths(project_id, is_current DESC, path)`,
+	`CREATE TABLE IF NOT EXISTS project_git_fingerprints (
+		project_id TEXT NOT NULL,
+		normalized_remote_url TEXT NOT NULL,
+		default_branch TEXT,
+		first_seen_at TEXT NOT NULL,
+		last_updated TEXT NOT NULL,
+		PRIMARY KEY (project_id, normalized_remote_url),
+		FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+	)`,
+	`CREATE INDEX IF NOT EXISTS idx_project_git_remote ON project_git_fingerprints(normalized_remote_url, last_updated DESC)`,
+]);
+
+export function runProjectRegistryMigrations(database: Database): void {
+	for (const statement of PROJECT_REGISTRY_STATEMENTS) {
+		database.run(statement);
+	}
+
+	const projectsInfo = database.query("PRAGMA table_info(projects)").all() as Array<{
+		name?: string;
+	}>;
+	const hasFirstSeenAt = projectsInfo.some((column) => column.name === "first_seen_at");
+	if (!hasFirstSeenAt) {
+		database.run("ALTER TABLE projects ADD COLUMN first_seen_at TEXT");
+		database.run("UPDATE projects SET first_seen_at = COALESCE(first_seen_at, last_updated)");
+	}
+}