refactor(storage): make the project catalog part of the operational database

apps/desktop/src/main/app-lifecycle.ts

@@ -11,6 +11,7 @@ import type {
  ShellRunProcessManager,
 } from '@maka/runtime';
 import type { McpClientManager } from '@maka/mcp';
+import { backfillSessionProjects } from '@maka/storage';
 import type {
  createConnectionStore,
  createProjectCatalog,
@@ -183,6 +184,23 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  }
 
+ async function resolveSessionProjectsOnStartup(): Promise<void> {
+ try {
+ const result = await backfillSessionProjects({
+ sessions: sessionStore,
+ catalog: projectCatalog,
+ });
+ for (const failure of result.failures) {
+ console.error(`[projects] could not resolve ${failure.cwd}: ${failure.reason}`);
+ }
+ if (result.resolved > 0) emitSessionsChanged('migrated');
+ } catch (error) {
+ // Best-effort: an unresolved project only affects sidebar grouping, and
+ // the sessions themselves must still reach the renderer.
+ console.error('[projects] session project resolution failed:', error);
+ }
+ }
+
  async function ensureBootstrapConnection(): Promise<void> {
  await mkdir(workspaceRoot, { recursive: true });
  if ((await connectionStore.list()).length > 0) return;
@@ -302,6 +320,9 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  await step('usage readiness', () => ensureUsageReady());
  await step('session recovery', () => recoverInterruptedSessionsOnStartup());
+ // After recovery: an interrupted session must come back before the sidebar
+ // learns how to group it, and resolution costs a git probe per directory.
+ await step('project resolution', () => resolveSessionProjectsOnStartup());
  let botRegistryReady = false;
  if (settings) {
  const resolved = settings;

apps/desktop/src/main/boot.ts

@@ -243,7 +243,10 @@ async function confirmDesktopStorageRootRepair(): Promise<boolean> {
 const keepSystemAwake = createKeepSystemAwakeController(powerSaveBlocker);
 const store = createSessionStore(workspaceRoot);
 const agentGraphControlStore = createAgentGraphControlStore(workspaceRoot);
-const projectCatalog = createProjectCatalog(workspaceRoot);
+const projectCatalog = createProjectCatalog(workspaceRoot, {
+ onLegacyImportFailure: (error) =>
+ console.error('[projects] projects.json could not be imported:', error),
+});
 const worktreeChildExecutor = createGitWorktreeChildExecutor({ storageRoot: workspaceRoot });
 const planStore = createSqlitePlanStore(workspaceRoot);
 const executionStoreWiring = await openDesktopExecutionStoreWiring(workspaceRoot);

apps/desktop/src/main/e2e-fixture.ts

@@ -1,5 +1,10 @@
 import { mkdir, rm } from 'node:fs/promises';
 import type { UiLocale, E2eFixtureScenario, E2eFixtureState } from '@maka/core';
+import {
+ backfillSessionProjects,
+ createProjectCatalog,
+ createSessionStore,
+} from '@maka/storage';
 import { resolveStorageRoot } from '@maka/storage/root-authority';
 import type { CredentialStore } from './credential-store.js';
 import {
@@ -761,4 +766,23 @@ export async function seedE2eFixture(input: {
  await writeSession(input.workspaceRoot, seed.header, seed.messages);
  }
  }
+ await seedSessionProjects(input.workspaceRoot);
+}
+
+/**
+ * Resolve every seeded session's project here rather than leaving it to the
+ * startup backfill. The fixture is meant to hand the renderer a settled state:
+ * the app resolves projects in background startup, concurrently with window
+ * creation, so a test that asserts on project grouping would otherwise be
+ * racing the resolver instead of exercising the sidebar.
+ */
+async function seedSessionProjects(workspaceRoot: string): Promise<void> {
+ const sessions = createSessionStore(workspaceRoot);
+ const catalog = createProjectCatalog(workspaceRoot);
+ try {
+ await backfillSessionProjects({ sessions, catalog });
+ } finally {
+ await sessions.close?.();
+ catalog.close();
+ }
 }

packages/storage/src/__tests__/agent-graph-intent-claims.test.ts

@@ -136,12 +136,14 @@ describe('SQLite agent graph intent claims', () => {
 
  const legacy = new DatabaseSync(path);
  legacy.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  DROP TABLE agent_graph_supervisor_wake_attempts;
  DROP TABLE agent_graph_supervisor_wakes;

packages/storage/src/__tests__/agent-graph-supervisor-wakes.test.ts

@@ -223,12 +223,14 @@ describe('SQLite Agent Graph supervisor wakes', () => {
 
  const v11 = new DatabaseSync(path);
  v11.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  `);
  v11

packages/storage/src/__tests__/operational-state-backup.test.ts

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { createSqliteArtifactStore } from '../artifact-store.js';
+import { createProjectCatalog } from '../project-catalog.js';
 import { createSessionStore } from '../session-store.js';
 import {
  createOperationalStateBackup,
@@ -17,9 +18,21 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  const stateRoot = join(base, 'state');
  const backupRoot = join(base, 'backup');
  const restoreRoot = join(base, 'restore');
+ const projectPath = join(base, 'project');
+ await mkdir(projectPath);
  const sessions = createSessionStore(stateRoot);
  try {
+ // The project catalog decides how every session is grouped, and its name,
+ // relink aliases and archive state exist nowhere else. Restoring sessions
+ // without it would silently reorganize the user's whole sidebar.
+ const catalog = createProjectCatalog(stateRoot, { now: () => 5 });
+ const project = await catalog.register(projectPath);
+ await catalog.rename(project.id, 'Renamed Project');
+ await catalog.archive(project.id);
+ catalog.close();
+
  const session = await sessions.create({
+ projectId: project.id,
  cwd: '/tmp/cwd',
  backend: 'fake',
  llmConnectionSlug: 'fake',
@@ -54,14 +67,31 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  await restoreOperationalStateBackup({ backupRoot, destinationRoot: restoreRoot });
 
  const restored = createSessionStore(restoreRoot);
+ const restoredCatalog = createProjectCatalog(restoreRoot);
  try {
  assert.equal((await restored.readMessages(session.id))[0]?.id, 'message-1');
  assert.equal(
  await readFile(join(restoreRoot, 'artifacts', artifact.relativePath), 'utf8'),
  'artifact',
  );
+ assert.equal(
+ (await restored.readHeaderSnapshot(session.id)).projectId,
+ project.id,
+ 'a restored session still belongs to the project it was grouped under',
+ );
+ assert.deepEqual(await restoredCatalog.list(), [
+ {
+ id: project.id,
+ name: 'Renamed Project',
+ locations: [{ path: await realpath(projectPath), isWorktree: false }],
+ archivedAt: 5,
+ available: true,
+ preferredPath: await realpath(projectPath),
+ },
+ ]);
  } finally {
  await restored.close?.();
+ restoredCatalog.close();
  }
  } finally {
  await rm(base, { recursive: true, force: true });

packages/storage/src/__tests__/project-catalog.test.ts

@@ -40,7 +40,9 @@ test('a Git probe failure cannot persistently downgrade a repository to a folder
  await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
 
  await assert.rejects(() => registerProjectWithoutGit(repository, storage));
- await assert.rejects(() => readFile(join(storage, 'projects.json')), { code: 'ENOENT' });
+ // Nothing may be recorded: a folder identity written here would outlive the
+ // probe failure and permanently split the repository from its worktrees.
+ assert.deepEqual(await createProjectCatalog(storage).list(), []);
  } finally {
  await rm(base, { recursive: true, force: true });
  }
@@ -227,6 +229,84 @@ test('a missing project directory remains in the catalog as unavailable', async
  }
 });
 
+test('two catalogs changing one project at the same time keep both changes', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-concurrent-'));
+ try {
+ const workspace = join(base, 'workspace');
+ const storage = join(base, 'storage');
+ await mkdir(workspace);
+ const first = createProjectCatalog(storage, { now: () => 1_000 });
+ const second = createProjectCatalog(storage, { now: () => 2_000 });
+ const project = await first.register(workspace);
+ // Both catalogs settle their one-time legacy-import probe first, so the two
+ // mutations below really do overlap instead of queueing behind that I/O.
+ await Promise.all([first.list(), second.list()]);
+
+ // Each catalog rewrites the whole table; without holding the write lock
+ // across its own read, the later writer replays a stale copy and the other
+ // window's edit disappears with no error anywhere.
+ await Promise.all([second.archive(project.id), first.rename(project.id, 'Renamed')]);
+
+ const [merged] = await first.list();
+ assert.equal(merged?.name, 'Renamed', 'the rename must survive the concurrent archive');
+ assert.equal(merged?.archivedAt, 2_000, 'the archive must survive the concurrent rename');
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a relink whose merge target changes mid-flight fails instead of half-committing', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-race-'));
+ try {
+ const storage = join(base, 'storage');
+ const home = join(base, 'home');
+ const shared = join(base, 'shared');
+ const elsewhere = join(base, 'elsewhere');
+ await Promise.all([mkdir(home), mkdir(shared), mkdir(elsewhere)]);
+ const first = createProjectCatalog(storage);
+ const second = createProjectCatalog(storage);
+ const moving = await first.register(home);
+ const target = await first.register(shared);
+ await Promise.all([first.list(), second.list()]);
+
+ let releaseCallback!: () => void;
+ let callbackStarted!: () => void;
+ const gate = new Promise<void>((release) => {
+ releaseCallback = release;
+ });
+ const started = new Promise<void>((resolve) => {
+ callbackStarted = resolve;
+ });
+ let observed: string | undefined;
+ const relink = first.relink(moving.id, shared, async (context) => {
+ observed = context.conflictingProjectId;
+ callbackStarted();
+ await gate;
+ });
+ await started;
+
+ // The callback was told to move `target`'s sessions onto `moving`. While it
+ // is doing that, the other window moves `target` somewhere else entirely.
+ await second.relink(target.id, elsewhere);
+ releaseCallback();
+
+ assert.equal(observed, target.id, 'precondition: the callback planned a merge');
+ await assert.rejects(() => relink, /retry/);
+ const projects = await first.list();
+ assert.deepEqual(
+ projects.map((project) => project.id).sort(),
+ [moving.id, target.id].sort(),
+ 'neither project may be merged away after the plan went stale',
+ );
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
 test('relinking an unavailable project preserves its id and adopts the new directory', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-'));
  try {
@@ -418,7 +498,7 @@ test('selecting a project returns its most recent available location and rejects
  }
 });
 
-test('a malformed project catalog fails closed without overwriting it', async () => {
+test('a malformed legacy catalog is reported and preserved without blocking the catalog', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-corrupt-'));
  try {
  const workspace = join(base, 'workspace');
@@ -428,10 +508,79 @@ test('a malformed project catalog fails closed without overwriting it', async ()
  await mkdir(storage);
  const original = '{"schemaVersion":1,"projects":[{}]}\n';
  await writeFile(catalogPath, original, 'utf8');
- const catalog = createProjectCatalog(storage);
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
 
- await assert.rejects(() => catalog.register(workspace), /Invalid project catalog/);
+ // SQLite is the authority: a legacy file that cannot be read must not take
+ // the catalog down with it, and it must stay on disk to recover by hand.
+ const project = await catalog.register(workspace);
+
+ assert.equal((await catalog.list()).length, 1);
+ assert.equal((await catalog.list())[0]?.id, project.id);
  assert.equal(await readFile(catalogPath, 'utf8'), original);
+ assert.equal(failures.length, 1);
+ assert.match(String(failures[0]), /Invalid project catalog/);
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a legacy catalog is imported once and then set aside', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-import-'));
+ try {
+ const storage = join(base, 'storage');
+ await mkdir(storage);
+ await writeFile(
+ join(storage, 'projects.json'),
+ JSON.stringify({
+ schemaVersion: 1,
+ projects: [
+ {
+ id: 'legacy-project',
+ aliases: ['merged-away'],
+ name: 'Renamed By Hand',
+ identity: 'folder:/gone',
+ locations: [{ path: '/gone', isWorktree: false, lastUsedAt: 5 }],
+ lastUsedAt: 7,
+ archivedAt: 9,
+ },
+ ],
+ }),
+ 'utf8',
+ );
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ now: () => 1_000,
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
+
+ const projects = await catalog.list();
+
+ assert.deepEqual(failures, []);
+ // The user's name, relink aliases and archive state only ever lived in this
+ // file; losing them on upgrade would be indistinguishable from data loss.
+ assert.equal(projects.length, 1);
+ assert.equal(projects[0]?.id, 'legacy-project');
+ assert.equal(projects[0]?.name, 'Renamed By Hand');
+ assert.deepEqual(projects[0]?.aliases, ['merged-away']);
+ assert.equal(projects[0]?.archivedAt, 9);
+ await assert.rejects(() => readFile(join(storage, 'projects.json'), 'utf8'), {
+ code: 'ENOENT',
+ });
+ const setAside = JSON.parse(
+ await readFile(join(storage, 'projects.json.imported-1000'), 'utf8'),
+ ) as { projects: Array<{ id: string }> };
+ assert.deepEqual(
+ setAside.projects.map((project) => project.id),
+ ['legacy-project'],
+ 'the imported file is kept verbatim so a bad upgrade stays recoverable',
+ );
+
+ // A catalog opened later must not re-import and must not lose the state.
+ catalog.close();
+ assert.equal((await createProjectCatalog(storage).list()).length, 1);
  } finally {
  await rm(base, { recursive: true, force: true });
  }

apps/desktop/src/main/app-lifecycle.ts

@@ -11,6 +11,7 @@ import type {
  ShellRunProcessManager,
 } from '@maka/runtime';
 import type { McpClientManager } from '@maka/mcp';
+import { backfillSessionProjects } from '@maka/storage';
 import type {
  createConnectionStore,
  createProjectCatalog,
@@ -183,6 +184,23 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  }
 
+ async function resolveSessionProjectsOnStartup(): Promise<void> {
+ try {
+ const result = await backfillSessionProjects({
+ sessions: sessionStore,
+ catalog: projectCatalog,
+ });
+ for (const failure of result.failures) {
+ console.error(`[projects] could not resolve ${failure.cwd}: ${failure.reason}`);
+ }
+ if (result.resolved > 0) emitSessionsChanged('migrated');
+ } catch (error) {
+ // Best-effort: an unresolved project only affects sidebar grouping, and
+ // the sessions themselves must still reach the renderer.
+ console.error('[projects] session project resolution failed:', error);
+ }
+ }
+
  async function ensureBootstrapConnection(): Promise<void> {
  await mkdir(workspaceRoot, { recursive: true });
  if ((await connectionStore.list()).length > 0) return;
@@ -302,6 +320,9 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  await step('usage readiness', () => ensureUsageReady());
  await step('session recovery', () => recoverInterruptedSessionsOnStartup());
+ // After recovery: an interrupted session must come back before the sidebar
+ // learns how to group it, and resolution costs a git probe per directory.
+ await step('project resolution', () => resolveSessionProjectsOnStartup());
  let botRegistryReady = false;
  if (settings) {
  const resolved = settings;

apps/desktop/src/main/boot.ts

@@ -243,7 +243,10 @@ async function confirmDesktopStorageRootRepair(): Promise<boolean> {
 const keepSystemAwake = createKeepSystemAwakeController(powerSaveBlocker);
 const store = createSessionStore(workspaceRoot);
 const agentGraphControlStore = createAgentGraphControlStore(workspaceRoot);
-const projectCatalog = createProjectCatalog(workspaceRoot);
+const projectCatalog = createProjectCatalog(workspaceRoot, {
+ onLegacyImportFailure: (error) =>
+ console.error('[projects] projects.json could not be imported:', error),
+});
 const worktreeChildExecutor = createGitWorktreeChildExecutor({ storageRoot: workspaceRoot });
 const planStore = createSqlitePlanStore(workspaceRoot);
 const executionStoreWiring = await openDesktopExecutionStoreWiring(workspaceRoot);

apps/desktop/src/main/e2e-fixture.ts

@@ -1,5 +1,10 @@
 import { mkdir, rm } from 'node:fs/promises';
 import type { UiLocale, E2eFixtureScenario, E2eFixtureState } from '@maka/core';
+import {
+ backfillSessionProjects,
+ createProjectCatalog,
+ createSessionStore,
+} from '@maka/storage';
 import { resolveStorageRoot } from '@maka/storage/root-authority';
 import type { CredentialStore } from './credential-store.js';
 import {
@@ -761,4 +766,23 @@ export async function seedE2eFixture(input: {
  await writeSession(input.workspaceRoot, seed.header, seed.messages);
  }
  }
+ await seedSessionProjects(input.workspaceRoot);
+}
+
+/**
+ * Resolve every seeded session's project here rather than leaving it to the
+ * startup backfill. The fixture is meant to hand the renderer a settled state:
+ * the app resolves projects in background startup, concurrently with window
+ * creation, so a test that asserts on project grouping would otherwise be
+ * racing the resolver instead of exercising the sidebar.
+ */
+async function seedSessionProjects(workspaceRoot: string): Promise<void> {
+ const sessions = createSessionStore(workspaceRoot);
+ const catalog = createProjectCatalog(workspaceRoot);
+ try {
+ await backfillSessionProjects({ sessions, catalog });
+ } finally {
+ await sessions.close?.();
+ catalog.close();
+ }
 }

packages/storage/src/__tests__/agent-graph-intent-claims.test.ts

@@ -136,12 +136,14 @@ describe('SQLite agent graph intent claims', () => {
 
  const legacy = new DatabaseSync(path);
  legacy.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  DROP TABLE agent_graph_supervisor_wake_attempts;
  DROP TABLE agent_graph_supervisor_wakes;

packages/storage/src/__tests__/agent-graph-supervisor-wakes.test.ts

@@ -223,12 +223,14 @@ describe('SQLite Agent Graph supervisor wakes', () => {
 
  const v11 = new DatabaseSync(path);
  v11.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  `);
  v11

packages/storage/src/__tests__/operational-state-backup.test.ts

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { createSqliteArtifactStore } from '../artifact-store.js';
+import { createProjectCatalog } from '../project-catalog.js';
 import { createSessionStore } from '../session-store.js';
 import {
  createOperationalStateBackup,
@@ -17,9 +18,21 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  const stateRoot = join(base, 'state');
  const backupRoot = join(base, 'backup');
  const restoreRoot = join(base, 'restore');
+ const projectPath = join(base, 'project');
+ await mkdir(projectPath);
  const sessions = createSessionStore(stateRoot);
  try {
+ // The project catalog decides how every session is grouped, and its name,
+ // relink aliases and archive state exist nowhere else. Restoring sessions
+ // without it would silently reorganize the user's whole sidebar.
+ const catalog = createProjectCatalog(stateRoot, { now: () => 5 });
+ const project = await catalog.register(projectPath);
+ await catalog.rename(project.id, 'Renamed Project');
+ await catalog.archive(project.id);
+ catalog.close();
+
  const session = await sessions.create({
+ projectId: project.id,
  cwd: '/tmp/cwd',
  backend: 'fake',
  llmConnectionSlug: 'fake',
@@ -54,14 +67,31 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  await restoreOperationalStateBackup({ backupRoot, destinationRoot: restoreRoot });
 
  const restored = createSessionStore(restoreRoot);
+ const restoredCatalog = createProjectCatalog(restoreRoot);
  try {
  assert.equal((await restored.readMessages(session.id))[0]?.id, 'message-1');
  assert.equal(
  await readFile(join(restoreRoot, 'artifacts', artifact.relativePath), 'utf8'),
  'artifact',
  );
+ assert.equal(
+ (await restored.readHeaderSnapshot(session.id)).projectId,
+ project.id,
+ 'a restored session still belongs to the project it was grouped under',
+ );
+ assert.deepEqual(await restoredCatalog.list(), [
+ {
+ id: project.id,
+ name: 'Renamed Project',
+ locations: [{ path: await realpath(projectPath), isWorktree: false }],
+ archivedAt: 5,
+ available: true,
+ preferredPath: await realpath(projectPath),
+ },
+ ]);
  } finally {
  await restored.close?.();
+ restoredCatalog.close();
  }
  } finally {
  await rm(base, { recursive: true, force: true });

packages/storage/src/__tests__/project-catalog.test.ts

@@ -40,7 +40,9 @@ test('a Git probe failure cannot persistently downgrade a repository to a folder
  await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
 
  await assert.rejects(() => registerProjectWithoutGit(repository, storage));
- await assert.rejects(() => readFile(join(storage, 'projects.json')), { code: 'ENOENT' });
+ // Nothing may be recorded: a folder identity written here would outlive the
+ // probe failure and permanently split the repository from its worktrees.
+ assert.deepEqual(await createProjectCatalog(storage).list(), []);
  } finally {
  await rm(base, { recursive: true, force: true });
  }
@@ -227,6 +229,84 @@ test('a missing project directory remains in the catalog as unavailable', async
  }
 });
 
+test('two catalogs changing one project at the same time keep both changes', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-concurrent-'));
+ try {
+ const workspace = join(base, 'workspace');
+ const storage = join(base, 'storage');
+ await mkdir(workspace);
+ const first = createProjectCatalog(storage, { now: () => 1_000 });
+ const second = createProjectCatalog(storage, { now: () => 2_000 });
+ const project = await first.register(workspace);
+ // Both catalogs settle their one-time legacy-import probe first, so the two
+ // mutations below really do overlap instead of queueing behind that I/O.
+ await Promise.all([first.list(), second.list()]);
+
+ // Each catalog rewrites the whole table; without holding the write lock
+ // across its own read, the later writer replays a stale copy and the other
+ // window's edit disappears with no error anywhere.
+ await Promise.all([second.archive(project.id), first.rename(project.id, 'Renamed')]);
+
+ const [merged] = await first.list();
+ assert.equal(merged?.name, 'Renamed', 'the rename must survive the concurrent archive');
+ assert.equal(merged?.archivedAt, 2_000, 'the archive must survive the concurrent rename');
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a relink whose merge target changes mid-flight fails instead of half-committing', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-race-'));
+ try {
+ const storage = join(base, 'storage');
+ const home = join(base, 'home');
+ const shared = join(base, 'shared');
+ const elsewhere = join(base, 'elsewhere');
+ await Promise.all([mkdir(home), mkdir(shared), mkdir(elsewhere)]);
+ const first = createProjectCatalog(storage);
+ const second = createProjectCatalog(storage);
+ const moving = await first.register(home);
+ const target = await first.register(shared);
+ await Promise.all([first.list(), second.list()]);
+
+ let releaseCallback!: () => void;
+ let callbackStarted!: () => void;
+ const gate = new Promise<void>((release) => {
+ releaseCallback = release;
+ });
+ const started = new Promise<void>((resolve) => {
+ callbackStarted = resolve;
+ });
+ let observed: string | undefined;
+ const relink = first.relink(moving.id, shared, async (context) => {
+ observed = context.conflictingProjectId;
+ callbackStarted();
+ await gate;
+ });
+ await started;
+
+ // The callback was told to move `target`'s sessions onto `moving`. While it
+ // is doing that, the other window moves `target` somewhere else entirely.
+ await second.relink(target.id, elsewhere);
+ releaseCallback();
+
+ assert.equal(observed, target.id, 'precondition: the callback planned a merge');
+ await assert.rejects(() => relink, /retry/);
+ const projects = await first.list();
+ assert.deepEqual(
+ projects.map((project) => project.id).sort(),
+ [moving.id, target.id].sort(),
+ 'neither project may be merged away after the plan went stale',
+ );
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
 test('relinking an unavailable project preserves its id and adopts the new directory', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-'));
  try {
@@ -418,7 +498,7 @@ test('selecting a project returns its most recent available location and rejects
  }
 });
 
-test('a malformed project catalog fails closed without overwriting it', async () => {
+test('a malformed legacy catalog is reported and preserved without blocking the catalog', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-corrupt-'));
  try {
  const workspace = join(base, 'workspace');
@@ -428,10 +508,79 @@ test('a malformed project catalog fails closed without overwriting it', async ()
  await mkdir(storage);
  const original = '{"schemaVersion":1,"projects":[{}]}\n';
  await writeFile(catalogPath, original, 'utf8');
- const catalog = createProjectCatalog(storage);
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
 
- await assert.rejects(() => catalog.register(workspace), /Invalid project catalog/);
+ // SQLite is the authority: a legacy file that cannot be read must not take
+ // the catalog down with it, and it must stay on disk to recover by hand.
+ const project = await catalog.register(workspace);
+
+ assert.equal((await catalog.list()).length, 1);
+ assert.equal((await catalog.list())[0]?.id, project.id);
  assert.equal(await readFile(catalogPath, 'utf8'), original);
+ assert.equal(failures.length, 1);
+ assert.match(String(failures[0]), /Invalid project catalog/);
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a legacy catalog is imported once and then set aside', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-import-'));
+ try {
+ const storage = join(base, 'storage');
+ await mkdir(storage);
+ await writeFile(
+ join(storage, 'projects.json'),
+ JSON.stringify({
+ schemaVersion: 1,
+ projects: [
+ {
+ id: 'legacy-project',
+ aliases: ['merged-away'],
+ name: 'Renamed By Hand',
+ identity: 'folder:/gone',
+ locations: [{ path: '/gone', isWorktree: false, lastUsedAt: 5 }],
+ lastUsedAt: 7,
+ archivedAt: 9,
+ },
+ ],
+ }),
+ 'utf8',
+ );
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ now: () => 1_000,
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
+
+ const projects = await catalog.list();
+
+ assert.deepEqual(failures, []);
+ // The user's name, relink aliases and archive state only ever lived in this
+ // file; losing them on upgrade would be indistinguishable from data loss.
+ assert.equal(projects.length, 1);
+ assert.equal(projects[0]?.id, 'legacy-project');
+ assert.equal(projects[0]?.name, 'Renamed By Hand');
+ assert.deepEqual(projects[0]?.aliases, ['merged-away']);
+ assert.equal(projects[0]?.archivedAt, 9);
+ await assert.rejects(() => readFile(join(storage, 'projects.json'), 'utf8'), {
+ code: 'ENOENT',
+ });
+ const setAside = JSON.parse(
+ await readFile(join(storage, 'projects.json.imported-1000'), 'utf8'),
+ ) as { projects: Array<{ id: string }> };
+ assert.deepEqual(
+ setAside.projects.map((project) => project.id),
+ ['legacy-project'],
+ 'the imported file is kept verbatim so a bad upgrade stays recoverable',
+ );
+
+ // A catalog opened later must not re-import and must not lose the state.
+ catalog.close();
+ assert.equal((await createProjectCatalog(storage).list()).length, 1);
  } finally {
  await rm(base, { recursive: true, force: true });
  }

apps/desktop/src/main/app-lifecycle.ts

@@ -11,6 +11,7 @@ import type {
  ShellRunProcessManager,
 } from '@maka/runtime';
 import type { McpClientManager } from '@maka/mcp';
+import { backfillSessionProjects } from '@maka/storage';
 import type {
  createConnectionStore,
  createProjectCatalog,
@@ -183,6 +184,23 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  }
 
+ async function resolveSessionProjectsOnStartup(): Promise<void> {
+ try {
+ const result = await backfillSessionProjects({
+ sessions: sessionStore,
+ catalog: projectCatalog,
+ });
+ for (const failure of result.failures) {
+ console.error(`[projects] could not resolve ${failure.cwd}: ${failure.reason}`);
+ }
+ if (result.resolved > 0) emitSessionsChanged('migrated');
+ } catch (error) {
+ // Best-effort: an unresolved project only affects sidebar grouping, and
+ // the sessions themselves must still reach the renderer.
+ console.error('[projects] session project resolution failed:', error);
+ }
+ }
+
  async function ensureBootstrapConnection(): Promise<void> {
  await mkdir(workspaceRoot, { recursive: true });
  if ((await connectionStore.list()).length > 0) return;
@@ -302,6 +320,9 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  await step('usage readiness', () => ensureUsageReady());
  await step('session recovery', () => recoverInterruptedSessionsOnStartup());
+ // After recovery: an interrupted session must come back before the sidebar
+ // learns how to group it, and resolution costs a git probe per directory.
+ await step('project resolution', () => resolveSessionProjectsOnStartup());
  let botRegistryReady = false;
  if (settings) {
  const resolved = settings;

apps/desktop/src/main/boot.ts

@@ -243,7 +243,10 @@ async function confirmDesktopStorageRootRepair(): Promise<boolean> {
 const keepSystemAwake = createKeepSystemAwakeController(powerSaveBlocker);
 const store = createSessionStore(workspaceRoot);
 const agentGraphControlStore = createAgentGraphControlStore(workspaceRoot);
-const projectCatalog = createProjectCatalog(workspaceRoot);
+const projectCatalog = createProjectCatalog(workspaceRoot, {
+ onLegacyImportFailure: (error) =>
+ console.error('[projects] projects.json could not be imported:', error),
+});
 const worktreeChildExecutor = createGitWorktreeChildExecutor({ storageRoot: workspaceRoot });
 const planStore = createSqlitePlanStore(workspaceRoot);
 const executionStoreWiring = await openDesktopExecutionStoreWiring(workspaceRoot);

apps/desktop/src/main/e2e-fixture.ts

@@ -1,5 +1,10 @@
 import { mkdir, rm } from 'node:fs/promises';
 import type { UiLocale, E2eFixtureScenario, E2eFixtureState } from '@maka/core';
+import {
+ backfillSessionProjects,
+ createProjectCatalog,
+ createSessionStore,
+} from '@maka/storage';
 import { resolveStorageRoot } from '@maka/storage/root-authority';
 import type { CredentialStore } from './credential-store.js';
 import {
@@ -761,4 +766,23 @@ export async function seedE2eFixture(input: {
  await writeSession(input.workspaceRoot, seed.header, seed.messages);
  }
  }
+ await seedSessionProjects(input.workspaceRoot);
+}
+
+/**
+ * Resolve every seeded session's project here rather than leaving it to the
+ * startup backfill. The fixture is meant to hand the renderer a settled state:
+ * the app resolves projects in background startup, concurrently with window
+ * creation, so a test that asserts on project grouping would otherwise be
+ * racing the resolver instead of exercising the sidebar.
+ */
+async function seedSessionProjects(workspaceRoot: string): Promise<void> {
+ const sessions = createSessionStore(workspaceRoot);
+ const catalog = createProjectCatalog(workspaceRoot);
+ try {
+ await backfillSessionProjects({ sessions, catalog });
+ } finally {
+ await sessions.close?.();
+ catalog.close();
+ }
 }

packages/storage/src/__tests__/agent-graph-intent-claims.test.ts

@@ -136,12 +136,14 @@ describe('SQLite agent graph intent claims', () => {
 
  const legacy = new DatabaseSync(path);
  legacy.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  DROP TABLE agent_graph_supervisor_wake_attempts;
  DROP TABLE agent_graph_supervisor_wakes;

packages/storage/src/__tests__/agent-graph-supervisor-wakes.test.ts

@@ -223,12 +223,14 @@ describe('SQLite Agent Graph supervisor wakes', () => {
 
  const v11 = new DatabaseSync(path);
  v11.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  `);
  v11

packages/storage/src/__tests__/operational-state-backup.test.ts

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { createSqliteArtifactStore } from '../artifact-store.js';
+import { createProjectCatalog } from '../project-catalog.js';
 import { createSessionStore } from '../session-store.js';
 import {
  createOperationalStateBackup,
@@ -17,9 +18,21 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  const stateRoot = join(base, 'state');
  const backupRoot = join(base, 'backup');
  const restoreRoot = join(base, 'restore');
+ const projectPath = join(base, 'project');
+ await mkdir(projectPath);
  const sessions = createSessionStore(stateRoot);
  try {
+ // The project catalog decides how every session is grouped, and its name,
+ // relink aliases and archive state exist nowhere else. Restoring sessions
+ // without it would silently reorganize the user's whole sidebar.
+ const catalog = createProjectCatalog(stateRoot, { now: () => 5 });
+ const project = await catalog.register(projectPath);
+ await catalog.rename(project.id, 'Renamed Project');
+ await catalog.archive(project.id);
+ catalog.close();
+
  const session = await sessions.create({
+ projectId: project.id,
  cwd: '/tmp/cwd',
  backend: 'fake',
  llmConnectionSlug: 'fake',
@@ -54,14 +67,31 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  await restoreOperationalStateBackup({ backupRoot, destinationRoot: restoreRoot });
 
  const restored = createSessionStore(restoreRoot);
+ const restoredCatalog = createProjectCatalog(restoreRoot);
  try {
  assert.equal((await restored.readMessages(session.id))[0]?.id, 'message-1');
  assert.equal(
  await readFile(join(restoreRoot, 'artifacts', artifact.relativePath), 'utf8'),
  'artifact',
  );
+ assert.equal(
+ (await restored.readHeaderSnapshot(session.id)).projectId,
+ project.id,
+ 'a restored session still belongs to the project it was grouped under',
+ );
+ assert.deepEqual(await restoredCatalog.list(), [
+ {
+ id: project.id,
+ name: 'Renamed Project',
+ locations: [{ path: await realpath(projectPath), isWorktree: false }],
+ archivedAt: 5,
+ available: true,
+ preferredPath: await realpath(projectPath),
+ },
+ ]);
  } finally {
  await restored.close?.();
+ restoredCatalog.close();
  }
  } finally {
  await rm(base, { recursive: true, force: true });

packages/storage/src/__tests__/project-catalog.test.ts

@@ -40,7 +40,9 @@ test('a Git probe failure cannot persistently downgrade a repository to a folder
  await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
 
  await assert.rejects(() => registerProjectWithoutGit(repository, storage));
- await assert.rejects(() => readFile(join(storage, 'projects.json')), { code: 'ENOENT' });
+ // Nothing may be recorded: a folder identity written here would outlive the
+ // probe failure and permanently split the repository from its worktrees.
+ assert.deepEqual(await createProjectCatalog(storage).list(), []);
  } finally {
  await rm(base, { recursive: true, force: true });
  }
@@ -227,6 +229,84 @@ test('a missing project directory remains in the catalog as unavailable', async
  }
 });
 
+test('two catalogs changing one project at the same time keep both changes', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-concurrent-'));
+ try {
+ const workspace = join(base, 'workspace');
+ const storage = join(base, 'storage');
+ await mkdir(workspace);
+ const first = createProjectCatalog(storage, { now: () => 1_000 });
+ const second = createProjectCatalog(storage, { now: () => 2_000 });
+ const project = await first.register(workspace);
+ // Both catalogs settle their one-time legacy-import probe first, so the two
+ // mutations below really do overlap instead of queueing behind that I/O.
+ await Promise.all([first.list(), second.list()]);
+
+ // Each catalog rewrites the whole table; without holding the write lock
+ // across its own read, the later writer replays a stale copy and the other
+ // window's edit disappears with no error anywhere.
+ await Promise.all([second.archive(project.id), first.rename(project.id, 'Renamed')]);
+
+ const [merged] = await first.list();
+ assert.equal(merged?.name, 'Renamed', 'the rename must survive the concurrent archive');
+ assert.equal(merged?.archivedAt, 2_000, 'the archive must survive the concurrent rename');
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a relink whose merge target changes mid-flight fails instead of half-committing', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-race-'));
+ try {
+ const storage = join(base, 'storage');
+ const home = join(base, 'home');
+ const shared = join(base, 'shared');
+ const elsewhere = join(base, 'elsewhere');
+ await Promise.all([mkdir(home), mkdir(shared), mkdir(elsewhere)]);
+ const first = createProjectCatalog(storage);
+ const second = createProjectCatalog(storage);
+ const moving = await first.register(home);
+ const target = await first.register(shared);
+ await Promise.all([first.list(), second.list()]);
+
+ let releaseCallback!: () => void;
+ let callbackStarted!: () => void;
+ const gate = new Promise<void>((release) => {
+ releaseCallback = release;
+ });
+ const started = new Promise<void>((resolve) => {
+ callbackStarted = resolve;
+ });
+ let observed: string | undefined;
+ const relink = first.relink(moving.id, shared, async (context) => {
+ observed = context.conflictingProjectId;
+ callbackStarted();
+ await gate;
+ });
+ await started;
+
+ // The callback was told to move `target`'s sessions onto `moving`. While it
+ // is doing that, the other window moves `target` somewhere else entirely.
+ await second.relink(target.id, elsewhere);
+ releaseCallback();
+
+ assert.equal(observed, target.id, 'precondition: the callback planned a merge');
+ await assert.rejects(() => relink, /retry/);
+ const projects = await first.list();
+ assert.deepEqual(
+ projects.map((project) => project.id).sort(),
+ [moving.id, target.id].sort(),
+ 'neither project may be merged away after the plan went stale',
+ );
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
 test('relinking an unavailable project preserves its id and adopts the new directory', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-'));
  try {
@@ -418,7 +498,7 @@ test('selecting a project returns its most recent available location and rejects
  }
 });
 
-test('a malformed project catalog fails closed without overwriting it', async () => {
+test('a malformed legacy catalog is reported and preserved without blocking the catalog', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-corrupt-'));
  try {
  const workspace = join(base, 'workspace');
@@ -428,10 +508,79 @@ test('a malformed project catalog fails closed without overwriting it', async ()
  await mkdir(storage);
  const original = '{"schemaVersion":1,"projects":[{}]}\n';
  await writeFile(catalogPath, original, 'utf8');
- const catalog = createProjectCatalog(storage);
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
 
- await assert.rejects(() => catalog.register(workspace), /Invalid project catalog/);
+ // SQLite is the authority: a legacy file that cannot be read must not take
+ // the catalog down with it, and it must stay on disk to recover by hand.
+ const project = await catalog.register(workspace);
+
+ assert.equal((await catalog.list()).length, 1);
+ assert.equal((await catalog.list())[0]?.id, project.id);
  assert.equal(await readFile(catalogPath, 'utf8'), original);
+ assert.equal(failures.length, 1);
+ assert.match(String(failures[0]), /Invalid project catalog/);
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a legacy catalog is imported once and then set aside', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-import-'));
+ try {
+ const storage = join(base, 'storage');
+ await mkdir(storage);
+ await writeFile(
+ join(storage, 'projects.json'),
+ JSON.stringify({
+ schemaVersion: 1,
+ projects: [
+ {
+ id: 'legacy-project',
+ aliases: ['merged-away'],
+ name: 'Renamed By Hand',
+ identity: 'folder:/gone',
+ locations: [{ path: '/gone', isWorktree: false, lastUsedAt: 5 }],
+ lastUsedAt: 7,
+ archivedAt: 9,
+ },
+ ],
+ }),
+ 'utf8',
+ );
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ now: () => 1_000,
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
+
+ const projects = await catalog.list();
+
+ assert.deepEqual(failures, []);
+ // The user's name, relink aliases and archive state only ever lived in this
+ // file; losing them on upgrade would be indistinguishable from data loss.
+ assert.equal(projects.length, 1);
+ assert.equal(projects[0]?.id, 'legacy-project');
+ assert.equal(projects[0]?.name, 'Renamed By Hand');
+ assert.deepEqual(projects[0]?.aliases, ['merged-away']);
+ assert.equal(projects[0]?.archivedAt, 9);
+ await assert.rejects(() => readFile(join(storage, 'projects.json'), 'utf8'), {
+ code: 'ENOENT',
+ });
+ const setAside = JSON.parse(
+ await readFile(join(storage, 'projects.json.imported-1000'), 'utf8'),
+ ) as { projects: Array<{ id: string }> };
+ assert.deepEqual(
+ setAside.projects.map((project) => project.id),
+ ['legacy-project'],
+ 'the imported file is kept verbatim so a bad upgrade stays recoverable',
+ );
+
+ // A catalog opened later must not re-import and must not lose the state.
+ catalog.close();
+ assert.equal((await createProjectCatalog(storage).list()).length, 1);
  } finally {
  await rm(base, { recursive: true, force: true });
  }

apps/desktop/src/main/app-lifecycle.ts

@@ -11,6 +11,7 @@ import type {
  ShellRunProcessManager,
 } from '@maka/runtime';
 import type { McpClientManager } from '@maka/mcp';
+import { backfillSessionProjects } from '@maka/storage';
 import type {
  createConnectionStore,
  createProjectCatalog,
@@ -183,6 +184,23 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  }
 
+ async function resolveSessionProjectsOnStartup(): Promise<void> {
+ try {
+ const result = await backfillSessionProjects({
+ sessions: sessionStore,
+ catalog: projectCatalog,
+ });
+ for (const failure of result.failures) {
+ console.error(`[projects] could not resolve ${failure.cwd}: ${failure.reason}`);
+ }
+ if (result.resolved > 0) emitSessionsChanged('migrated');
+ } catch (error) {
+ // Best-effort: an unresolved project only affects sidebar grouping, and
+ // the sessions themselves must still reach the renderer.
+ console.error('[projects] session project resolution failed:', error);
+ }
+ }
+
  async function ensureBootstrapConnection(): Promise<void> {
  await mkdir(workspaceRoot, { recursive: true });
  if ((await connectionStore.list()).length > 0) return;
@@ -302,6 +320,9 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  await step('usage readiness', () => ensureUsageReady());
  await step('session recovery', () => recoverInterruptedSessionsOnStartup());
+ // After recovery: an interrupted session must come back before the sidebar
+ // learns how to group it, and resolution costs a git probe per directory.
+ await step('project resolution', () => resolveSessionProjectsOnStartup());
  let botRegistryReady = false;
  if (settings) {
  const resolved = settings;

apps/desktop/src/main/boot.ts

@@ -243,7 +243,10 @@ async function confirmDesktopStorageRootRepair(): Promise<boolean> {
 const keepSystemAwake = createKeepSystemAwakeController(powerSaveBlocker);
 const store = createSessionStore(workspaceRoot);
 const agentGraphControlStore = createAgentGraphControlStore(workspaceRoot);
-const projectCatalog = createProjectCatalog(workspaceRoot);
+const projectCatalog = createProjectCatalog(workspaceRoot, {
+ onLegacyImportFailure: (error) =>
+ console.error('[projects] projects.json could not be imported:', error),
+});
 const worktreeChildExecutor = createGitWorktreeChildExecutor({ storageRoot: workspaceRoot });
 const planStore = createSqlitePlanStore(workspaceRoot);
 const executionStoreWiring = await openDesktopExecutionStoreWiring(workspaceRoot);

apps/desktop/src/main/e2e-fixture.ts

@@ -1,5 +1,10 @@
 import { mkdir, rm } from 'node:fs/promises';
 import type { UiLocale, E2eFixtureScenario, E2eFixtureState } from '@maka/core';
+import {
+ backfillSessionProjects,
+ createProjectCatalog,
+ createSessionStore,
+} from '@maka/storage';
 import { resolveStorageRoot } from '@maka/storage/root-authority';
 import type { CredentialStore } from './credential-store.js';
 import {
@@ -761,4 +766,23 @@ export async function seedE2eFixture(input: {
  await writeSession(input.workspaceRoot, seed.header, seed.messages);
  }
  }
+ await seedSessionProjects(input.workspaceRoot);
+}
+
+/**
+ * Resolve every seeded session's project here rather than leaving it to the
+ * startup backfill. The fixture is meant to hand the renderer a settled state:
+ * the app resolves projects in background startup, concurrently with window
+ * creation, so a test that asserts on project grouping would otherwise be
+ * racing the resolver instead of exercising the sidebar.
+ */
+async function seedSessionProjects(workspaceRoot: string): Promise<void> {
+ const sessions = createSessionStore(workspaceRoot);
+ const catalog = createProjectCatalog(workspaceRoot);
+ try {
+ await backfillSessionProjects({ sessions, catalog });
+ } finally {
+ await sessions.close?.();
+ catalog.close();
+ }
 }

packages/storage/src/__tests__/agent-graph-intent-claims.test.ts

@@ -136,12 +136,14 @@ describe('SQLite agent graph intent claims', () => {
 
  const legacy = new DatabaseSync(path);
  legacy.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  DROP TABLE agent_graph_supervisor_wake_attempts;
  DROP TABLE agent_graph_supervisor_wakes;

packages/storage/src/__tests__/agent-graph-supervisor-wakes.test.ts

@@ -223,12 +223,14 @@ describe('SQLite Agent Graph supervisor wakes', () => {
 
  const v11 = new DatabaseSync(path);
  v11.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  `);
  v11

packages/storage/src/__tests__/operational-state-backup.test.ts

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { createSqliteArtifactStore } from '../artifact-store.js';
+import { createProjectCatalog } from '../project-catalog.js';
 import { createSessionStore } from '../session-store.js';
 import {
  createOperationalStateBackup,
@@ -17,9 +18,21 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  const stateRoot = join(base, 'state');
  const backupRoot = join(base, 'backup');
  const restoreRoot = join(base, 'restore');
+ const projectPath = join(base, 'project');
+ await mkdir(projectPath);
  const sessions = createSessionStore(stateRoot);
  try {
+ // The project catalog decides how every session is grouped, and its name,
+ // relink aliases and archive state exist nowhere else. Restoring sessions
+ // without it would silently reorganize the user's whole sidebar.
+ const catalog = createProjectCatalog(stateRoot, { now: () => 5 });
+ const project = await catalog.register(projectPath);
+ await catalog.rename(project.id, 'Renamed Project');
+ await catalog.archive(project.id);
+ catalog.close();
+
  const session = await sessions.create({
+ projectId: project.id,
  cwd: '/tmp/cwd',
  backend: 'fake',
  llmConnectionSlug: 'fake',
@@ -54,14 +67,31 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  await restoreOperationalStateBackup({ backupRoot, destinationRoot: restoreRoot });
 
  const restored = createSessionStore(restoreRoot);
+ const restoredCatalog = createProjectCatalog(restoreRoot);
  try {
  assert.equal((await restored.readMessages(session.id))[0]?.id, 'message-1');
  assert.equal(
  await readFile(join(restoreRoot, 'artifacts', artifact.relativePath), 'utf8'),
  'artifact',
  );
+ assert.equal(
+ (await restored.readHeaderSnapshot(session.id)).projectId,
+ project.id,
+ 'a restored session still belongs to the project it was grouped under',
+ );
+ assert.deepEqual(await restoredCatalog.list(), [
+ {
+ id: project.id,
+ name: 'Renamed Project',
+ locations: [{ path: await realpath(projectPath), isWorktree: false }],
+ archivedAt: 5,
+ available: true,
+ preferredPath: await realpath(projectPath),
+ },
+ ]);
  } finally {
  await restored.close?.();
+ restoredCatalog.close();
  }
  } finally {
  await rm(base, { recursive: true, force: true });

packages/storage/src/__tests__/project-catalog.test.ts

@@ -40,7 +40,9 @@ test('a Git probe failure cannot persistently downgrade a repository to a folder
  await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
 
  await assert.rejects(() => registerProjectWithoutGit(repository, storage));
- await assert.rejects(() => readFile(join(storage, 'projects.json')), { code: 'ENOENT' });
+ // Nothing may be recorded: a folder identity written here would outlive the
+ // probe failure and permanently split the repository from its worktrees.
+ assert.deepEqual(await createProjectCatalog(storage).list(), []);
  } finally {
  await rm(base, { recursive: true, force: true });
  }
@@ -227,6 +229,84 @@ test('a missing project directory remains in the catalog as unavailable', async
  }
 });
 
+test('two catalogs changing one project at the same time keep both changes', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-concurrent-'));
+ try {
+ const workspace = join(base, 'workspace');
+ const storage = join(base, 'storage');
+ await mkdir(workspace);
+ const first = createProjectCatalog(storage, { now: () => 1_000 });
+ const second = createProjectCatalog(storage, { now: () => 2_000 });
+ const project = await first.register(workspace);
+ // Both catalogs settle their one-time legacy-import probe first, so the two
+ // mutations below really do overlap instead of queueing behind that I/O.
+ await Promise.all([first.list(), second.list()]);
+
+ // Each catalog rewrites the whole table; without holding the write lock
+ // across its own read, the later writer replays a stale copy and the other
+ // window's edit disappears with no error anywhere.
+ await Promise.all([second.archive(project.id), first.rename(project.id, 'Renamed')]);
+
+ const [merged] = await first.list();
+ assert.equal(merged?.name, 'Renamed', 'the rename must survive the concurrent archive');
+ assert.equal(merged?.archivedAt, 2_000, 'the archive must survive the concurrent rename');
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a relink whose merge target changes mid-flight fails instead of half-committing', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-race-'));
+ try {
+ const storage = join(base, 'storage');
+ const home = join(base, 'home');
+ const shared = join(base, 'shared');
+ const elsewhere = join(base, 'elsewhere');
+ await Promise.all([mkdir(home), mkdir(shared), mkdir(elsewhere)]);
+ const first = createProjectCatalog(storage);
+ const second = createProjectCatalog(storage);
+ const moving = await first.register(home);
+ const target = await first.register(shared);
+ await Promise.all([first.list(), second.list()]);
+
+ let releaseCallback!: () => void;
+ let callbackStarted!: () => void;
+ const gate = new Promise<void>((release) => {
+ releaseCallback = release;
+ });
+ const started = new Promise<void>((resolve) => {
+ callbackStarted = resolve;
+ });
+ let observed: string | undefined;
+ const relink = first.relink(moving.id, shared, async (context) => {
+ observed = context.conflictingProjectId;
+ callbackStarted();
+ await gate;
+ });
+ await started;
+
+ // The callback was told to move `target`'s sessions onto `moving`. While it
+ // is doing that, the other window moves `target` somewhere else entirely.
+ await second.relink(target.id, elsewhere);
+ releaseCallback();
+
+ assert.equal(observed, target.id, 'precondition: the callback planned a merge');
+ await assert.rejects(() => relink, /retry/);
+ const projects = await first.list();
+ assert.deepEqual(
+ projects.map((project) => project.id).sort(),
+ [moving.id, target.id].sort(),
+ 'neither project may be merged away after the plan went stale',
+ );
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
 test('relinking an unavailable project preserves its id and adopts the new directory', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-'));
  try {
@@ -418,7 +498,7 @@ test('selecting a project returns its most recent available location and rejects
  }
 });
 
-test('a malformed project catalog fails closed without overwriting it', async () => {
+test('a malformed legacy catalog is reported and preserved without blocking the catalog', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-corrupt-'));
  try {
  const workspace = join(base, 'workspace');
@@ -428,10 +508,79 @@ test('a malformed project catalog fails closed without overwriting it', async ()
  await mkdir(storage);
  const original = '{"schemaVersion":1,"projects":[{}]}\n';
  await writeFile(catalogPath, original, 'utf8');
- const catalog = createProjectCatalog(storage);
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
 
- await assert.rejects(() => catalog.register(workspace), /Invalid project catalog/);
+ // SQLite is the authority: a legacy file that cannot be read must not take
+ // the catalog down with it, and it must stay on disk to recover by hand.
+ const project = await catalog.register(workspace);
+
+ assert.equal((await catalog.list()).length, 1);
+ assert.equal((await catalog.list())[0]?.id, project.id);
  assert.equal(await readFile(catalogPath, 'utf8'), original);
+ assert.equal(failures.length, 1);
+ assert.match(String(failures[0]), /Invalid project catalog/);
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a legacy catalog is imported once and then set aside', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-import-'));
+ try {
+ const storage = join(base, 'storage');
+ await mkdir(storage);
+ await writeFile(
+ join(storage, 'projects.json'),
+ JSON.stringify({
+ schemaVersion: 1,
+ projects: [
+ {
+ id: 'legacy-project',
+ aliases: ['merged-away'],
+ name: 'Renamed By Hand',
+ identity: 'folder:/gone',
+ locations: [{ path: '/gone', isWorktree: false, lastUsedAt: 5 }],
+ lastUsedAt: 7,
+ archivedAt: 9,
+ },
+ ],
+ }),
+ 'utf8',
+ );
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ now: () => 1_000,
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
+
+ const projects = await catalog.list();
+
+ assert.deepEqual(failures, []);
+ // The user's name, relink aliases and archive state only ever lived in this
+ // file; losing them on upgrade would be indistinguishable from data loss.
+ assert.equal(projects.length, 1);
+ assert.equal(projects[0]?.id, 'legacy-project');
+ assert.equal(projects[0]?.name, 'Renamed By Hand');
+ assert.deepEqual(projects[0]?.aliases, ['merged-away']);
+ assert.equal(projects[0]?.archivedAt, 9);
+ await assert.rejects(() => readFile(join(storage, 'projects.json'), 'utf8'), {
+ code: 'ENOENT',
+ });
+ const setAside = JSON.parse(
+ await readFile(join(storage, 'projects.json.imported-1000'), 'utf8'),
+ ) as { projects: Array<{ id: string }> };
+ assert.deepEqual(
+ setAside.projects.map((project) => project.id),
+ ['legacy-project'],
+ 'the imported file is kept verbatim so a bad upgrade stays recoverable',
+ );
+
+ // A catalog opened later must not re-import and must not lose the state.
+ catalog.close();
+ assert.equal((await createProjectCatalog(storage).list()).length, 1);
  } finally {
  await rm(base, { recursive: true, force: true });
  }

apps/desktop/src/main/app-lifecycle.ts

@@ -11,6 +11,7 @@ import type {
  ShellRunProcessManager,
 } from '@maka/runtime';
 import type { McpClientManager } from '@maka/mcp';
+import { backfillSessionProjects } from '@maka/storage';
 import type {
  createConnectionStore,
  createProjectCatalog,
@@ -183,6 +184,23 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  }
 
+ async function resolveSessionProjectsOnStartup(): Promise<void> {
+ try {
+ const result = await backfillSessionProjects({
+ sessions: sessionStore,
+ catalog: projectCatalog,
+ });
+ for (const failure of result.failures) {
+ console.error(`[projects] could not resolve ${failure.cwd}: ${failure.reason}`);
+ }
+ if (result.resolved > 0) emitSessionsChanged('migrated');
+ } catch (error) {
+ // Best-effort: an unresolved project only affects sidebar grouping, and
+ // the sessions themselves must still reach the renderer.
+ console.error('[projects] session project resolution failed:', error);
+ }
+ }
+
  async function ensureBootstrapConnection(): Promise<void> {
  await mkdir(workspaceRoot, { recursive: true });
  if ((await connectionStore.list()).length > 0) return;
@@ -302,6 +320,9 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  await step('usage readiness', () => ensureUsageReady());
  await step('session recovery', () => recoverInterruptedSessionsOnStartup());
+ // After recovery: an interrupted session must come back before the sidebar
+ // learns how to group it, and resolution costs a git probe per directory.
+ await step('project resolution', () => resolveSessionProjectsOnStartup());
  let botRegistryReady = false;
  if (settings) {
  const resolved = settings;

apps/desktop/src/main/boot.ts

@@ -243,7 +243,10 @@ async function confirmDesktopStorageRootRepair(): Promise<boolean> {
 const keepSystemAwake = createKeepSystemAwakeController(powerSaveBlocker);
 const store = createSessionStore(workspaceRoot);
 const agentGraphControlStore = createAgentGraphControlStore(workspaceRoot);
-const projectCatalog = createProjectCatalog(workspaceRoot);
+const projectCatalog = createProjectCatalog(workspaceRoot, {
+ onLegacyImportFailure: (error) =>
+ console.error('[projects] projects.json could not be imported:', error),
+});
 const worktreeChildExecutor = createGitWorktreeChildExecutor({ storageRoot: workspaceRoot });
 const planStore = createSqlitePlanStore(workspaceRoot);
 const executionStoreWiring = await openDesktopExecutionStoreWiring(workspaceRoot);

apps/desktop/src/main/e2e-fixture.ts

@@ -1,5 +1,10 @@
 import { mkdir, rm } from 'node:fs/promises';
 import type { UiLocale, E2eFixtureScenario, E2eFixtureState } from '@maka/core';
+import {
+ backfillSessionProjects,
+ createProjectCatalog,
+ createSessionStore,
+} from '@maka/storage';
 import { resolveStorageRoot } from '@maka/storage/root-authority';
 import type { CredentialStore } from './credential-store.js';
 import {
@@ -761,4 +766,23 @@ export async function seedE2eFixture(input: {
  await writeSession(input.workspaceRoot, seed.header, seed.messages);
  }
  }
+ await seedSessionProjects(input.workspaceRoot);
+}
+
+/**
+ * Resolve every seeded session's project here rather than leaving it to the
+ * startup backfill. The fixture is meant to hand the renderer a settled state:
+ * the app resolves projects in background startup, concurrently with window
+ * creation, so a test that asserts on project grouping would otherwise be
+ * racing the resolver instead of exercising the sidebar.
+ */
+async function seedSessionProjects(workspaceRoot: string): Promise<void> {
+ const sessions = createSessionStore(workspaceRoot);
+ const catalog = createProjectCatalog(workspaceRoot);
+ try {
+ await backfillSessionProjects({ sessions, catalog });
+ } finally {
+ await sessions.close?.();
+ catalog.close();
+ }
 }

packages/storage/src/__tests__/agent-graph-intent-claims.test.ts

@@ -136,12 +136,14 @@ describe('SQLite agent graph intent claims', () => {
 
  const legacy = new DatabaseSync(path);
  legacy.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  DROP TABLE agent_graph_supervisor_wake_attempts;
  DROP TABLE agent_graph_supervisor_wakes;

packages/storage/src/__tests__/agent-graph-supervisor-wakes.test.ts

@@ -223,12 +223,14 @@ describe('SQLite Agent Graph supervisor wakes', () => {
 
  const v11 = new DatabaseSync(path);
  v11.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  `);
  v11

packages/storage/src/__tests__/operational-state-backup.test.ts

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { createSqliteArtifactStore } from '../artifact-store.js';
+import { createProjectCatalog } from '../project-catalog.js';
 import { createSessionStore } from '../session-store.js';
 import {
  createOperationalStateBackup,
@@ -17,9 +18,21 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  const stateRoot = join(base, 'state');
  const backupRoot = join(base, 'backup');
  const restoreRoot = join(base, 'restore');
+ const projectPath = join(base, 'project');
+ await mkdir(projectPath);
  const sessions = createSessionStore(stateRoot);
  try {
+ // The project catalog decides how every session is grouped, and its name,
+ // relink aliases and archive state exist nowhere else. Restoring sessions
+ // without it would silently reorganize the user's whole sidebar.
+ const catalog = createProjectCatalog(stateRoot, { now: () => 5 });
+ const project = await catalog.register(projectPath);
+ await catalog.rename(project.id, 'Renamed Project');
+ await catalog.archive(project.id);
+ catalog.close();
+
  const session = await sessions.create({
+ projectId: project.id,
  cwd: '/tmp/cwd',
  backend: 'fake',
  llmConnectionSlug: 'fake',
@@ -54,14 +67,31 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  await restoreOperationalStateBackup({ backupRoot, destinationRoot: restoreRoot });
 
  const restored = createSessionStore(restoreRoot);
+ const restoredCatalog = createProjectCatalog(restoreRoot);
  try {
  assert.equal((await restored.readMessages(session.id))[0]?.id, 'message-1');
  assert.equal(
  await readFile(join(restoreRoot, 'artifacts', artifact.relativePath), 'utf8'),
  'artifact',
  );
+ assert.equal(
+ (await restored.readHeaderSnapshot(session.id)).projectId,
+ project.id,
+ 'a restored session still belongs to the project it was grouped under',
+ );
+ assert.deepEqual(await restoredCatalog.list(), [
+ {
+ id: project.id,
+ name: 'Renamed Project',
+ locations: [{ path: await realpath(projectPath), isWorktree: false }],
+ archivedAt: 5,
+ available: true,
+ preferredPath: await realpath(projectPath),
+ },
+ ]);
  } finally {
  await restored.close?.();
+ restoredCatalog.close();
  }
  } finally {
  await rm(base, { recursive: true, force: true });

packages/storage/src/__tests__/project-catalog.test.ts

@@ -40,7 +40,9 @@ test('a Git probe failure cannot persistently downgrade a repository to a folder
  await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
 
  await assert.rejects(() => registerProjectWithoutGit(repository, storage));
- await assert.rejects(() => readFile(join(storage, 'projects.json')), { code: 'ENOENT' });
+ // Nothing may be recorded: a folder identity written here would outlive the
+ // probe failure and permanently split the repository from its worktrees.
+ assert.deepEqual(await createProjectCatalog(storage).list(), []);
  } finally {
  await rm(base, { recursive: true, force: true });
  }
@@ -227,6 +229,84 @@ test('a missing project directory remains in the catalog as unavailable', async
  }
 });
 
+test('two catalogs changing one project at the same time keep both changes', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-concurrent-'));
+ try {
+ const workspace = join(base, 'workspace');
+ const storage = join(base, 'storage');
+ await mkdir(workspace);
+ const first = createProjectCatalog(storage, { now: () => 1_000 });
+ const second = createProjectCatalog(storage, { now: () => 2_000 });
+ const project = await first.register(workspace);
+ // Both catalogs settle their one-time legacy-import probe first, so the two
+ // mutations below really do overlap instead of queueing behind that I/O.
+ await Promise.all([first.list(), second.list()]);
+
+ // Each catalog rewrites the whole table; without holding the write lock
+ // across its own read, the later writer replays a stale copy and the other
+ // window's edit disappears with no error anywhere.
+ await Promise.all([second.archive(project.id), first.rename(project.id, 'Renamed')]);
+
+ const [merged] = await first.list();
+ assert.equal(merged?.name, 'Renamed', 'the rename must survive the concurrent archive');
+ assert.equal(merged?.archivedAt, 2_000, 'the archive must survive the concurrent rename');
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a relink whose merge target changes mid-flight fails instead of half-committing', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-race-'));
+ try {
+ const storage = join(base, 'storage');
+ const home = join(base, 'home');
+ const shared = join(base, 'shared');
+ const elsewhere = join(base, 'elsewhere');
+ await Promise.all([mkdir(home), mkdir(shared), mkdir(elsewhere)]);
+ const first = createProjectCatalog(storage);
+ const second = createProjectCatalog(storage);
+ const moving = await first.register(home);
+ const target = await first.register(shared);
+ await Promise.all([first.list(), second.list()]);
+
+ let releaseCallback!: () => void;
+ let callbackStarted!: () => void;
+ const gate = new Promise<void>((release) => {
+ releaseCallback = release;
+ });
+ const started = new Promise<void>((resolve) => {
+ callbackStarted = resolve;
+ });
+ let observed: string | undefined;
+ const relink = first.relink(moving.id, shared, async (context) => {
+ observed = context.conflictingProjectId;
+ callbackStarted();
+ await gate;
+ });
+ await started;
+
+ // The callback was told to move `target`'s sessions onto `moving`. While it
+ // is doing that, the other window moves `target` somewhere else entirely.
+ await second.relink(target.id, elsewhere);
+ releaseCallback();
+
+ assert.equal(observed, target.id, 'precondition: the callback planned a merge');
+ await assert.rejects(() => relink, /retry/);
+ const projects = await first.list();
+ assert.deepEqual(
+ projects.map((project) => project.id).sort(),
+ [moving.id, target.id].sort(),
+ 'neither project may be merged away after the plan went stale',
+ );
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
 test('relinking an unavailable project preserves its id and adopts the new directory', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-'));
  try {
@@ -418,7 +498,7 @@ test('selecting a project returns its most recent available location and rejects
  }
 });
 
-test('a malformed project catalog fails closed without overwriting it', async () => {
+test('a malformed legacy catalog is reported and preserved without blocking the catalog', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-corrupt-'));
  try {
  const workspace = join(base, 'workspace');
@@ -428,10 +508,79 @@ test('a malformed project catalog fails closed without overwriting it', async ()
  await mkdir(storage);
  const original = '{"schemaVersion":1,"projects":[{}]}\n';
  await writeFile(catalogPath, original, 'utf8');
- const catalog = createProjectCatalog(storage);
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
 
- await assert.rejects(() => catalog.register(workspace), /Invalid project catalog/);
+ // SQLite is the authority: a legacy file that cannot be read must not take
+ // the catalog down with it, and it must stay on disk to recover by hand.
+ const project = await catalog.register(workspace);
+
+ assert.equal((await catalog.list()).length, 1);
+ assert.equal((await catalog.list())[0]?.id, project.id);
  assert.equal(await readFile(catalogPath, 'utf8'), original);
+ assert.equal(failures.length, 1);
+ assert.match(String(failures[0]), /Invalid project catalog/);
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a legacy catalog is imported once and then set aside', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-import-'));
+ try {
+ const storage = join(base, 'storage');
+ await mkdir(storage);
+ await writeFile(
+ join(storage, 'projects.json'),
+ JSON.stringify({
+ schemaVersion: 1,
+ projects: [
+ {
+ id: 'legacy-project',
+ aliases: ['merged-away'],
+ name: 'Renamed By Hand',
+ identity: 'folder:/gone',
+ locations: [{ path: '/gone', isWorktree: false, lastUsedAt: 5 }],
+ lastUsedAt: 7,
+ archivedAt: 9,
+ },
+ ],
+ }),
+ 'utf8',
+ );
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ now: () => 1_000,
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
+
+ const projects = await catalog.list();
+
+ assert.deepEqual(failures, []);
+ // The user's name, relink aliases and archive state only ever lived in this
+ // file; losing them on upgrade would be indistinguishable from data loss.
+ assert.equal(projects.length, 1);
+ assert.equal(projects[0]?.id, 'legacy-project');
+ assert.equal(projects[0]?.name, 'Renamed By Hand');
+ assert.deepEqual(projects[0]?.aliases, ['merged-away']);
+ assert.equal(projects[0]?.archivedAt, 9);
+ await assert.rejects(() => readFile(join(storage, 'projects.json'), 'utf8'), {
+ code: 'ENOENT',
+ });
+ const setAside = JSON.parse(
+ await readFile(join(storage, 'projects.json.imported-1000'), 'utf8'),
+ ) as { projects: Array<{ id: string }> };
+ assert.deepEqual(
+ setAside.projects.map((project) => project.id),
+ ['legacy-project'],
+ 'the imported file is kept verbatim so a bad upgrade stays recoverable',
+ );
+
+ // A catalog opened later must not re-import and must not lose the state.
+ catalog.close();
+ assert.equal((await createProjectCatalog(storage).list()).length, 1);
  } finally {
  await rm(base, { recursive: true, force: true });
  }

apps/desktop/src/main/app-lifecycle.ts

@@ -11,6 +11,7 @@ import type {
  ShellRunProcessManager,
 } from '@maka/runtime';
 import type { McpClientManager } from '@maka/mcp';
+import { backfillSessionProjects } from '@maka/storage';
 import type {
  createConnectionStore,
  createProjectCatalog,
@@ -183,6 +184,23 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  }
 
+ async function resolveSessionProjectsOnStartup(): Promise<void> {
+ try {
+ const result = await backfillSessionProjects({
+ sessions: sessionStore,
+ catalog: projectCatalog,
+ });
+ for (const failure of result.failures) {
+ console.error(`[projects] could not resolve ${failure.cwd}: ${failure.reason}`);
+ }
+ if (result.resolved > 0) emitSessionsChanged('migrated');
+ } catch (error) {
+ // Best-effort: an unresolved project only affects sidebar grouping, and
+ // the sessions themselves must still reach the renderer.
+ console.error('[projects] session project resolution failed:', error);
+ }
+ }
+
  async function ensureBootstrapConnection(): Promise<void> {
  await mkdir(workspaceRoot, { recursive: true });
  if ((await connectionStore.list()).length > 0) return;
@@ -302,6 +320,9 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  await step('usage readiness', () => ensureUsageReady());
  await step('session recovery', () => recoverInterruptedSessionsOnStartup());
+ // After recovery: an interrupted session must come back before the sidebar
+ // learns how to group it, and resolution costs a git probe per directory.
+ await step('project resolution', () => resolveSessionProjectsOnStartup());
  let botRegistryReady = false;
  if (settings) {
  const resolved = settings;

apps/desktop/src/main/boot.ts

@@ -243,7 +243,10 @@ async function confirmDesktopStorageRootRepair(): Promise<boolean> {
 const keepSystemAwake = createKeepSystemAwakeController(powerSaveBlocker);
 const store = createSessionStore(workspaceRoot);
 const agentGraphControlStore = createAgentGraphControlStore(workspaceRoot);
-const projectCatalog = createProjectCatalog(workspaceRoot);
+const projectCatalog = createProjectCatalog(workspaceRoot, {
+ onLegacyImportFailure: (error) =>
+ console.error('[projects] projects.json could not be imported:', error),
+});
 const worktreeChildExecutor = createGitWorktreeChildExecutor({ storageRoot: workspaceRoot });
 const planStore = createSqlitePlanStore(workspaceRoot);
 const executionStoreWiring = await openDesktopExecutionStoreWiring(workspaceRoot);

apps/desktop/src/main/e2e-fixture.ts

@@ -1,5 +1,10 @@
 import { mkdir, rm } from 'node:fs/promises';
 import type { UiLocale, E2eFixtureScenario, E2eFixtureState } from '@maka/core';
+import {
+ backfillSessionProjects,
+ createProjectCatalog,
+ createSessionStore,
+} from '@maka/storage';
 import { resolveStorageRoot } from '@maka/storage/root-authority';
 import type { CredentialStore } from './credential-store.js';
 import {
@@ -761,4 +766,23 @@ export async function seedE2eFixture(input: {
  await writeSession(input.workspaceRoot, seed.header, seed.messages);
  }
  }
+ await seedSessionProjects(input.workspaceRoot);
+}
+
+/**
+ * Resolve every seeded session's project here rather than leaving it to the
+ * startup backfill. The fixture is meant to hand the renderer a settled state:
+ * the app resolves projects in background startup, concurrently with window
+ * creation, so a test that asserts on project grouping would otherwise be
+ * racing the resolver instead of exercising the sidebar.
+ */
+async function seedSessionProjects(workspaceRoot: string): Promise<void> {
+ const sessions = createSessionStore(workspaceRoot);
+ const catalog = createProjectCatalog(workspaceRoot);
+ try {
+ await backfillSessionProjects({ sessions, catalog });
+ } finally {
+ await sessions.close?.();
+ catalog.close();
+ }
 }

packages/storage/src/__tests__/agent-graph-intent-claims.test.ts

@@ -136,12 +136,14 @@ describe('SQLite agent graph intent claims', () => {
 
  const legacy = new DatabaseSync(path);
  legacy.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  DROP TABLE agent_graph_supervisor_wake_attempts;
  DROP TABLE agent_graph_supervisor_wakes;

packages/storage/src/__tests__/agent-graph-supervisor-wakes.test.ts

@@ -223,12 +223,14 @@ describe('SQLite Agent Graph supervisor wakes', () => {
 
  const v11 = new DatabaseSync(path);
  v11.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  `);
  v11

packages/storage/src/__tests__/operational-state-backup.test.ts

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { createSqliteArtifactStore } from '../artifact-store.js';
+import { createProjectCatalog } from '../project-catalog.js';
 import { createSessionStore } from '../session-store.js';
 import {
  createOperationalStateBackup,
@@ -17,9 +18,21 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  const stateRoot = join(base, 'state');
  const backupRoot = join(base, 'backup');
  const restoreRoot = join(base, 'restore');
+ const projectPath = join(base, 'project');
+ await mkdir(projectPath);
  const sessions = createSessionStore(stateRoot);
  try {
+ // The project catalog decides how every session is grouped, and its name,
+ // relink aliases and archive state exist nowhere else. Restoring sessions
+ // without it would silently reorganize the user's whole sidebar.
+ const catalog = createProjectCatalog(stateRoot, { now: () => 5 });
+ const project = await catalog.register(projectPath);
+ await catalog.rename(project.id, 'Renamed Project');
+ await catalog.archive(project.id);
+ catalog.close();
+
  const session = await sessions.create({
+ projectId: project.id,
  cwd: '/tmp/cwd',
  backend: 'fake',
  llmConnectionSlug: 'fake',
@@ -54,14 +67,31 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  await restoreOperationalStateBackup({ backupRoot, destinationRoot: restoreRoot });
 
  const restored = createSessionStore(restoreRoot);
+ const restoredCatalog = createProjectCatalog(restoreRoot);
  try {
  assert.equal((await restored.readMessages(session.id))[0]?.id, 'message-1');
  assert.equal(
  await readFile(join(restoreRoot, 'artifacts', artifact.relativePath), 'utf8'),
  'artifact',
  );
+ assert.equal(
+ (await restored.readHeaderSnapshot(session.id)).projectId,
+ project.id,
+ 'a restored session still belongs to the project it was grouped under',
+ );
+ assert.deepEqual(await restoredCatalog.list(), [
+ {
+ id: project.id,
+ name: 'Renamed Project',
+ locations: [{ path: await realpath(projectPath), isWorktree: false }],
+ archivedAt: 5,
+ available: true,
+ preferredPath: await realpath(projectPath),
+ },
+ ]);
  } finally {
  await restored.close?.();
+ restoredCatalog.close();
  }
  } finally {
  await rm(base, { recursive: true, force: true });

packages/storage/src/__tests__/project-catalog.test.ts

@@ -40,7 +40,9 @@ test('a Git probe failure cannot persistently downgrade a repository to a folder
  await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
 
  await assert.rejects(() => registerProjectWithoutGit(repository, storage));
- await assert.rejects(() => readFile(join(storage, 'projects.json')), { code: 'ENOENT' });
+ // Nothing may be recorded: a folder identity written here would outlive the
+ // probe failure and permanently split the repository from its worktrees.
+ assert.deepEqual(await createProjectCatalog(storage).list(), []);
  } finally {
  await rm(base, { recursive: true, force: true });
  }
@@ -227,6 +229,84 @@ test('a missing project directory remains in the catalog as unavailable', async
  }
 });
 
+test('two catalogs changing one project at the same time keep both changes', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-concurrent-'));
+ try {
+ const workspace = join(base, 'workspace');
+ const storage = join(base, 'storage');
+ await mkdir(workspace);
+ const first = createProjectCatalog(storage, { now: () => 1_000 });
+ const second = createProjectCatalog(storage, { now: () => 2_000 });
+ const project = await first.register(workspace);
+ // Both catalogs settle their one-time legacy-import probe first, so the two
+ // mutations below really do overlap instead of queueing behind that I/O.
+ await Promise.all([first.list(), second.list()]);
+
+ // Each catalog rewrites the whole table; without holding the write lock
+ // across its own read, the later writer replays a stale copy and the other
+ // window's edit disappears with no error anywhere.
+ await Promise.all([second.archive(project.id), first.rename(project.id, 'Renamed')]);
+
+ const [merged] = await first.list();
+ assert.equal(merged?.name, 'Renamed', 'the rename must survive the concurrent archive');
+ assert.equal(merged?.archivedAt, 2_000, 'the archive must survive the concurrent rename');
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a relink whose merge target changes mid-flight fails instead of half-committing', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-race-'));
+ try {
+ const storage = join(base, 'storage');
+ const home = join(base, 'home');
+ const shared = join(base, 'shared');
+ const elsewhere = join(base, 'elsewhere');
+ await Promise.all([mkdir(home), mkdir(shared), mkdir(elsewhere)]);
+ const first = createProjectCatalog(storage);
+ const second = createProjectCatalog(storage);
+ const moving = await first.register(home);
+ const target = await first.register(shared);
+ await Promise.all([first.list(), second.list()]);
+
+ let releaseCallback!: () => void;
+ let callbackStarted!: () => void;
+ const gate = new Promise<void>((release) => {
+ releaseCallback = release;
+ });
+ const started = new Promise<void>((resolve) => {
+ callbackStarted = resolve;
+ });
+ let observed: string | undefined;
+ const relink = first.relink(moving.id, shared, async (context) => {
+ observed = context.conflictingProjectId;
+ callbackStarted();
+ await gate;
+ });
+ await started;
+
+ // The callback was told to move `target`'s sessions onto `moving`. While it
+ // is doing that, the other window moves `target` somewhere else entirely.
+ await second.relink(target.id, elsewhere);
+ releaseCallback();
+
+ assert.equal(observed, target.id, 'precondition: the callback planned a merge');
+ await assert.rejects(() => relink, /retry/);
+ const projects = await first.list();
+ assert.deepEqual(
+ projects.map((project) => project.id).sort(),
+ [moving.id, target.id].sort(),
+ 'neither project may be merged away after the plan went stale',
+ );
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
 test('relinking an unavailable project preserves its id and adopts the new directory', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-'));
  try {
@@ -418,7 +498,7 @@ test('selecting a project returns its most recent available location and rejects
  }
 });
 
-test('a malformed project catalog fails closed without overwriting it', async () => {
+test('a malformed legacy catalog is reported and preserved without blocking the catalog', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-corrupt-'));
  try {
  const workspace = join(base, 'workspace');
@@ -428,10 +508,79 @@ test('a malformed project catalog fails closed without overwriting it', async ()
  await mkdir(storage);
  const original = '{"schemaVersion":1,"projects":[{}]}\n';
  await writeFile(catalogPath, original, 'utf8');
- const catalog = createProjectCatalog(storage);
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
 
- await assert.rejects(() => catalog.register(workspace), /Invalid project catalog/);
+ // SQLite is the authority: a legacy file that cannot be read must not take
+ // the catalog down with it, and it must stay on disk to recover by hand.
+ const project = await catalog.register(workspace);
+
+ assert.equal((await catalog.list()).length, 1);
+ assert.equal((await catalog.list())[0]?.id, project.id);
  assert.equal(await readFile(catalogPath, 'utf8'), original);
+ assert.equal(failures.length, 1);
+ assert.match(String(failures[0]), /Invalid project catalog/);
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a legacy catalog is imported once and then set aside', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-import-'));
+ try {
+ const storage = join(base, 'storage');
+ await mkdir(storage);
+ await writeFile(
+ join(storage, 'projects.json'),
+ JSON.stringify({
+ schemaVersion: 1,
+ projects: [
+ {
+ id: 'legacy-project',
+ aliases: ['merged-away'],
+ name: 'Renamed By Hand',
+ identity: 'folder:/gone',
+ locations: [{ path: '/gone', isWorktree: false, lastUsedAt: 5 }],
+ lastUsedAt: 7,
+ archivedAt: 9,
+ },
+ ],
+ }),
+ 'utf8',
+ );
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ now: () => 1_000,
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
+
+ const projects = await catalog.list();
+
+ assert.deepEqual(failures, []);
+ // The user's name, relink aliases and archive state only ever lived in this
+ // file; losing them on upgrade would be indistinguishable from data loss.
+ assert.equal(projects.length, 1);
+ assert.equal(projects[0]?.id, 'legacy-project');
+ assert.equal(projects[0]?.name, 'Renamed By Hand');
+ assert.deepEqual(projects[0]?.aliases, ['merged-away']);
+ assert.equal(projects[0]?.archivedAt, 9);
+ await assert.rejects(() => readFile(join(storage, 'projects.json'), 'utf8'), {
+ code: 'ENOENT',
+ });
+ const setAside = JSON.parse(
+ await readFile(join(storage, 'projects.json.imported-1000'), 'utf8'),
+ ) as { projects: Array<{ id: string }> };
+ assert.deepEqual(
+ setAside.projects.map((project) => project.id),
+ ['legacy-project'],
+ 'the imported file is kept verbatim so a bad upgrade stays recoverable',
+ );
+
+ // A catalog opened later must not re-import and must not lose the state.
+ catalog.close();
+ assert.equal((await createProjectCatalog(storage).list()).length, 1);
  } finally {
  await rm(base, { recursive: true, force: true });
  }

apps/desktop/src/main/app-lifecycle.ts

@@ -11,6 +11,7 @@ import type {
  ShellRunProcessManager,
 } from '@maka/runtime';
 import type { McpClientManager } from '@maka/mcp';
+import { backfillSessionProjects } from '@maka/storage';
 import type {
  createConnectionStore,
  createProjectCatalog,
@@ -183,6 +184,23 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  }
 
+ async function resolveSessionProjectsOnStartup(): Promise<void> {
+ try {
+ const result = await backfillSessionProjects({
+ sessions: sessionStore,
+ catalog: projectCatalog,
+ });
+ for (const failure of result.failures) {
+ console.error(`[projects] could not resolve ${failure.cwd}: ${failure.reason}`);
+ }
+ if (result.resolved > 0) emitSessionsChanged('migrated');
+ } catch (error) {
+ // Best-effort: an unresolved project only affects sidebar grouping, and
+ // the sessions themselves must still reach the renderer.
+ console.error('[projects] session project resolution failed:', error);
+ }
+ }
+
  async function ensureBootstrapConnection(): Promise<void> {
  await mkdir(workspaceRoot, { recursive: true });
  if ((await connectionStore.list()).length > 0) return;
@@ -302,6 +320,9 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  await step('usage readiness', () => ensureUsageReady());
  await step('session recovery', () => recoverInterruptedSessionsOnStartup());
+ // After recovery: an interrupted session must come back before the sidebar
+ // learns how to group it, and resolution costs a git probe per directory.
+ await step('project resolution', () => resolveSessionProjectsOnStartup());
  let botRegistryReady = false;
  if (settings) {
  const resolved = settings;

apps/desktop/src/main/boot.ts

@@ -243,7 +243,10 @@ async function confirmDesktopStorageRootRepair(): Promise<boolean> {
 const keepSystemAwake = createKeepSystemAwakeController(powerSaveBlocker);
 const store = createSessionStore(workspaceRoot);
 const agentGraphControlStore = createAgentGraphControlStore(workspaceRoot);
-const projectCatalog = createProjectCatalog(workspaceRoot);
+const projectCatalog = createProjectCatalog(workspaceRoot, {
+ onLegacyImportFailure: (error) =>
+ console.error('[projects] projects.json could not be imported:', error),
+});
 const worktreeChildExecutor = createGitWorktreeChildExecutor({ storageRoot: workspaceRoot });
 const planStore = createSqlitePlanStore(workspaceRoot);
 const executionStoreWiring = await openDesktopExecutionStoreWiring(workspaceRoot);

apps/desktop/src/main/e2e-fixture.ts

@@ -1,5 +1,10 @@
 import { mkdir, rm } from 'node:fs/promises';
 import type { UiLocale, E2eFixtureScenario, E2eFixtureState } from '@maka/core';
+import {
+ backfillSessionProjects,
+ createProjectCatalog,
+ createSessionStore,
+} from '@maka/storage';
 import { resolveStorageRoot } from '@maka/storage/root-authority';
 import type { CredentialStore } from './credential-store.js';
 import {
@@ -761,4 +766,23 @@ export async function seedE2eFixture(input: {
  await writeSession(input.workspaceRoot, seed.header, seed.messages);
  }
  }
+ await seedSessionProjects(input.workspaceRoot);
+}
+
+/**
+ * Resolve every seeded session's project here rather than leaving it to the
+ * startup backfill. The fixture is meant to hand the renderer a settled state:
+ * the app resolves projects in background startup, concurrently with window
+ * creation, so a test that asserts on project grouping would otherwise be
+ * racing the resolver instead of exercising the sidebar.
+ */
+async function seedSessionProjects(workspaceRoot: string): Promise<void> {
+ const sessions = createSessionStore(workspaceRoot);
+ const catalog = createProjectCatalog(workspaceRoot);
+ try {
+ await backfillSessionProjects({ sessions, catalog });
+ } finally {
+ await sessions.close?.();
+ catalog.close();
+ }
 }

packages/storage/src/__tests__/agent-graph-intent-claims.test.ts

@@ -136,12 +136,14 @@ describe('SQLite agent graph intent claims', () => {
 
  const legacy = new DatabaseSync(path);
  legacy.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  DROP TABLE agent_graph_supervisor_wake_attempts;
  DROP TABLE agent_graph_supervisor_wakes;

packages/storage/src/__tests__/agent-graph-supervisor-wakes.test.ts

@@ -223,12 +223,14 @@ describe('SQLite Agent Graph supervisor wakes', () => {
 
  const v11 = new DatabaseSync(path);
  v11.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  `);
  v11

packages/storage/src/__tests__/operational-state-backup.test.ts

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { createSqliteArtifactStore } from '../artifact-store.js';
+import { createProjectCatalog } from '../project-catalog.js';
 import { createSessionStore } from '../session-store.js';
 import {
  createOperationalStateBackup,
@@ -17,9 +18,21 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  const stateRoot = join(base, 'state');
  const backupRoot = join(base, 'backup');
  const restoreRoot = join(base, 'restore');
+ const projectPath = join(base, 'project');
+ await mkdir(projectPath);
  const sessions = createSessionStore(stateRoot);
  try {
+ // The project catalog decides how every session is grouped, and its name,
+ // relink aliases and archive state exist nowhere else. Restoring sessions
+ // without it would silently reorganize the user's whole sidebar.
+ const catalog = createProjectCatalog(stateRoot, { now: () => 5 });
+ const project = await catalog.register(projectPath);
+ await catalog.rename(project.id, 'Renamed Project');
+ await catalog.archive(project.id);
+ catalog.close();
+
  const session = await sessions.create({
+ projectId: project.id,
  cwd: '/tmp/cwd',
  backend: 'fake',
  llmConnectionSlug: 'fake',
@@ -54,14 +67,31 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  await restoreOperationalStateBackup({ backupRoot, destinationRoot: restoreRoot });
 
  const restored = createSessionStore(restoreRoot);
+ const restoredCatalog = createProjectCatalog(restoreRoot);
  try {
  assert.equal((await restored.readMessages(session.id))[0]?.id, 'message-1');
  assert.equal(
  await readFile(join(restoreRoot, 'artifacts', artifact.relativePath), 'utf8'),
  'artifact',
  );
+ assert.equal(
+ (await restored.readHeaderSnapshot(session.id)).projectId,
+ project.id,
+ 'a restored session still belongs to the project it was grouped under',
+ );
+ assert.deepEqual(await restoredCatalog.list(), [
+ {
+ id: project.id,
+ name: 'Renamed Project',
+ locations: [{ path: await realpath(projectPath), isWorktree: false }],
+ archivedAt: 5,
+ available: true,
+ preferredPath: await realpath(projectPath),
+ },
+ ]);
  } finally {
  await restored.close?.();
+ restoredCatalog.close();
  }
  } finally {
  await rm(base, { recursive: true, force: true });

packages/storage/src/__tests__/project-catalog.test.ts

@@ -40,7 +40,9 @@ test('a Git probe failure cannot persistently downgrade a repository to a folder
  await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
 
  await assert.rejects(() => registerProjectWithoutGit(repository, storage));
- await assert.rejects(() => readFile(join(storage, 'projects.json')), { code: 'ENOENT' });
+ // Nothing may be recorded: a folder identity written here would outlive the
+ // probe failure and permanently split the repository from its worktrees.
+ assert.deepEqual(await createProjectCatalog(storage).list(), []);
  } finally {
  await rm(base, { recursive: true, force: true });
  }
@@ -227,6 +229,84 @@ test('a missing project directory remains in the catalog as unavailable', async
  }
 });
 
+test('two catalogs changing one project at the same time keep both changes', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-concurrent-'));
+ try {
+ const workspace = join(base, 'workspace');
+ const storage = join(base, 'storage');
+ await mkdir(workspace);
+ const first = createProjectCatalog(storage, { now: () => 1_000 });
+ const second = createProjectCatalog(storage, { now: () => 2_000 });
+ const project = await first.register(workspace);
+ // Both catalogs settle their one-time legacy-import probe first, so the two
+ // mutations below really do overlap instead of queueing behind that I/O.
+ await Promise.all([first.list(), second.list()]);
+
+ // Each catalog rewrites the whole table; without holding the write lock
+ // across its own read, the later writer replays a stale copy and the other
+ // window's edit disappears with no error anywhere.
+ await Promise.all([second.archive(project.id), first.rename(project.id, 'Renamed')]);
+
+ const [merged] = await first.list();
+ assert.equal(merged?.name, 'Renamed', 'the rename must survive the concurrent archive');
+ assert.equal(merged?.archivedAt, 2_000, 'the archive must survive the concurrent rename');
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a relink whose merge target changes mid-flight fails instead of half-committing', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-race-'));
+ try {
+ const storage = join(base, 'storage');
+ const home = join(base, 'home');
+ const shared = join(base, 'shared');
+ const elsewhere = join(base, 'elsewhere');
+ await Promise.all([mkdir(home), mkdir(shared), mkdir(elsewhere)]);
+ const first = createProjectCatalog(storage);
+ const second = createProjectCatalog(storage);
+ const moving = await first.register(home);
+ const target = await first.register(shared);
+ await Promise.all([first.list(), second.list()]);
+
+ let releaseCallback!: () => void;
+ let callbackStarted!: () => void;
+ const gate = new Promise<void>((release) => {
+ releaseCallback = release;
+ });
+ const started = new Promise<void>((resolve) => {
+ callbackStarted = resolve;
+ });
+ let observed: string | undefined;
+ const relink = first.relink(moving.id, shared, async (context) => {
+ observed = context.conflictingProjectId;
+ callbackStarted();
+ await gate;
+ });
+ await started;
+
+ // The callback was told to move `target`'s sessions onto `moving`. While it
+ // is doing that, the other window moves `target` somewhere else entirely.
+ await second.relink(target.id, elsewhere);
+ releaseCallback();
+
+ assert.equal(observed, target.id, 'precondition: the callback planned a merge');
+ await assert.rejects(() => relink, /retry/);
+ const projects = await first.list();
+ assert.deepEqual(
+ projects.map((project) => project.id).sort(),
+ [moving.id, target.id].sort(),
+ 'neither project may be merged away after the plan went stale',
+ );
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
 test('relinking an unavailable project preserves its id and adopts the new directory', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-'));
  try {
@@ -418,7 +498,7 @@ test('selecting a project returns its most recent available location and rejects
  }
 });
 
-test('a malformed project catalog fails closed without overwriting it', async () => {
+test('a malformed legacy catalog is reported and preserved without blocking the catalog', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-corrupt-'));
  try {
  const workspace = join(base, 'workspace');
@@ -428,10 +508,79 @@ test('a malformed project catalog fails closed without overwriting it', async ()
  await mkdir(storage);
  const original = '{"schemaVersion":1,"projects":[{}]}\n';
  await writeFile(catalogPath, original, 'utf8');
- const catalog = createProjectCatalog(storage);
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
 
- await assert.rejects(() => catalog.register(workspace), /Invalid project catalog/);
+ // SQLite is the authority: a legacy file that cannot be read must not take
+ // the catalog down with it, and it must stay on disk to recover by hand.
+ const project = await catalog.register(workspace);
+
+ assert.equal((await catalog.list()).length, 1);
+ assert.equal((await catalog.list())[0]?.id, project.id);
  assert.equal(await readFile(catalogPath, 'utf8'), original);
+ assert.equal(failures.length, 1);
+ assert.match(String(failures[0]), /Invalid project catalog/);
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a legacy catalog is imported once and then set aside', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-import-'));
+ try {
+ const storage = join(base, 'storage');
+ await mkdir(storage);
+ await writeFile(
+ join(storage, 'projects.json'),
+ JSON.stringify({
+ schemaVersion: 1,
+ projects: [
+ {
+ id: 'legacy-project',
+ aliases: ['merged-away'],
+ name: 'Renamed By Hand',
+ identity: 'folder:/gone',
+ locations: [{ path: '/gone', isWorktree: false, lastUsedAt: 5 }],
+ lastUsedAt: 7,
+ archivedAt: 9,
+ },
+ ],
+ }),
+ 'utf8',
+ );
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ now: () => 1_000,
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
+
+ const projects = await catalog.list();
+
+ assert.deepEqual(failures, []);
+ // The user's name, relink aliases and archive state only ever lived in this
+ // file; losing them on upgrade would be indistinguishable from data loss.
+ assert.equal(projects.length, 1);
+ assert.equal(projects[0]?.id, 'legacy-project');
+ assert.equal(projects[0]?.name, 'Renamed By Hand');
+ assert.deepEqual(projects[0]?.aliases, ['merged-away']);
+ assert.equal(projects[0]?.archivedAt, 9);
+ await assert.rejects(() => readFile(join(storage, 'projects.json'), 'utf8'), {
+ code: 'ENOENT',
+ });
+ const setAside = JSON.parse(
+ await readFile(join(storage, 'projects.json.imported-1000'), 'utf8'),
+ ) as { projects: Array<{ id: string }> };
+ assert.deepEqual(
+ setAside.projects.map((project) => project.id),
+ ['legacy-project'],
+ 'the imported file is kept verbatim so a bad upgrade stays recoverable',
+ );
+
+ // A catalog opened later must not re-import and must not lose the state.
+ catalog.close();
+ assert.equal((await createProjectCatalog(storage).list()).length, 1);
  } finally {
  await rm(base, { recursive: true, force: true });
  }

apps/desktop/src/main/app-lifecycle.ts

@@ -11,6 +11,7 @@ import type {
  ShellRunProcessManager,
 } from '@maka/runtime';
 import type { McpClientManager } from '@maka/mcp';
+import { backfillSessionProjects } from '@maka/storage';
 import type {
  createConnectionStore,
  createProjectCatalog,
@@ -183,6 +184,23 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  }
 
+ async function resolveSessionProjectsOnStartup(): Promise<void> {
+ try {
+ const result = await backfillSessionProjects({
+ sessions: sessionStore,
+ catalog: projectCatalog,
+ });
+ for (const failure of result.failures) {
+ console.error(`[projects] could not resolve ${failure.cwd}: ${failure.reason}`);
+ }
+ if (result.resolved > 0) emitSessionsChanged('migrated');
+ } catch (error) {
+ // Best-effort: an unresolved project only affects sidebar grouping, and
+ // the sessions themselves must still reach the renderer.
+ console.error('[projects] session project resolution failed:', error);
+ }
+ }
+
  async function ensureBootstrapConnection(): Promise<void> {
  await mkdir(workspaceRoot, { recursive: true });
  if ((await connectionStore.list()).length > 0) return;
@@ -302,6 +320,9 @@ export function wireAppLifecycle(deps: AppLifecycleDeps): void {
  }
  await step('usage readiness', () => ensureUsageReady());
  await step('session recovery', () => recoverInterruptedSessionsOnStartup());
+ // After recovery: an interrupted session must come back before the sidebar
+ // learns how to group it, and resolution costs a git probe per directory.
+ await step('project resolution', () => resolveSessionProjectsOnStartup());
  let botRegistryReady = false;
  if (settings) {
  const resolved = settings;

apps/desktop/src/main/boot.ts

@@ -243,7 +243,10 @@ async function confirmDesktopStorageRootRepair(): Promise<boolean> {
 const keepSystemAwake = createKeepSystemAwakeController(powerSaveBlocker);
 const store = createSessionStore(workspaceRoot);
 const agentGraphControlStore = createAgentGraphControlStore(workspaceRoot);
-const projectCatalog = createProjectCatalog(workspaceRoot);
+const projectCatalog = createProjectCatalog(workspaceRoot, {
+ onLegacyImportFailure: (error) =>
+ console.error('[projects] projects.json could not be imported:', error),
+});
 const worktreeChildExecutor = createGitWorktreeChildExecutor({ storageRoot: workspaceRoot });
 const planStore = createSqlitePlanStore(workspaceRoot);
 const executionStoreWiring = await openDesktopExecutionStoreWiring(workspaceRoot);

apps/desktop/src/main/e2e-fixture.ts

@@ -1,5 +1,10 @@
 import { mkdir, rm } from 'node:fs/promises';
 import type { UiLocale, E2eFixtureScenario, E2eFixtureState } from '@maka/core';
+import {
+ backfillSessionProjects,
+ createProjectCatalog,
+ createSessionStore,
+} from '@maka/storage';
 import { resolveStorageRoot } from '@maka/storage/root-authority';
 import type { CredentialStore } from './credential-store.js';
 import {
@@ -761,4 +766,23 @@ export async function seedE2eFixture(input: {
  await writeSession(input.workspaceRoot, seed.header, seed.messages);
  }
  }
+ await seedSessionProjects(input.workspaceRoot);
+}
+
+/**
+ * Resolve every seeded session's project here rather than leaving it to the
+ * startup backfill. The fixture is meant to hand the renderer a settled state:
+ * the app resolves projects in background startup, concurrently with window
+ * creation, so a test that asserts on project grouping would otherwise be
+ * racing the resolver instead of exercising the sidebar.
+ */
+async function seedSessionProjects(workspaceRoot: string): Promise<void> {
+ const sessions = createSessionStore(workspaceRoot);
+ const catalog = createProjectCatalog(workspaceRoot);
+ try {
+ await backfillSessionProjects({ sessions, catalog });
+ } finally {
+ await sessions.close?.();
+ catalog.close();
+ }
 }

packages/storage/src/__tests__/agent-graph-intent-claims.test.ts

@@ -136,12 +136,14 @@ describe('SQLite agent graph intent claims', () => {
 
  const legacy = new DatabaseSync(path);
  legacy.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  DROP TABLE agent_graph_supervisor_wake_attempts;
  DROP TABLE agent_graph_supervisor_wakes;

packages/storage/src/__tests__/agent-graph-supervisor-wakes.test.ts

@@ -223,12 +223,14 @@ describe('SQLite Agent Graph supervisor wakes', () => {
 
  const v11 = new DatabaseSync(path);
  v11.exec(`
- DROP TABLE session_messages;
  DROP INDEX session_metadata_tombstones_by_retirement_unit;
  ALTER TABLE session_metadata_tombstones DROP COLUMN cleanup_pending;
  ALTER TABLE session_metadata_tombstones DROP COLUMN retirement_unit_id;
  DROP TABLE session_create_claims;
  DROP TABLE sandbox_boundary_log;
+ DROP TABLE project_aliases;
+ DROP TABLE project_locations;
+ DROP TABLE projects;
  DROP TABLE session_messages;
  `);
  v11

packages/storage/src/__tests__/operational-state-backup.test.ts

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { createSqliteArtifactStore } from '../artifact-store.js';
+import { createProjectCatalog } from '../project-catalog.js';
 import { createSessionStore } from '../session-store.js';
 import {
  createOperationalStateBackup,
@@ -17,9 +18,21 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  const stateRoot = join(base, 'state');
  const backupRoot = join(base, 'backup');
  const restoreRoot = join(base, 'restore');
+ const projectPath = join(base, 'project');
+ await mkdir(projectPath);
  const sessions = createSessionStore(stateRoot);
  try {
+ // The project catalog decides how every session is grouped, and its name,
+ // relink aliases and archive state exist nowhere else. Restoring sessions
+ // without it would silently reorganize the user's whole sidebar.
+ const catalog = createProjectCatalog(stateRoot, { now: () => 5 });
+ const project = await catalog.register(projectPath);
+ await catalog.rename(project.id, 'Renamed Project');
+ await catalog.archive(project.id);
+ catalog.close();
+
  const session = await sessions.create({
+ projectId: project.id,
  cwd: '/tmp/cwd',
  backend: 'fake',
  llmConnectionSlug: 'fake',
@@ -54,14 +67,31 @@ test('backs up and restores runtime.sqlite plus artifact bytes', async () => {
  await restoreOperationalStateBackup({ backupRoot, destinationRoot: restoreRoot });
 
  const restored = createSessionStore(restoreRoot);
+ const restoredCatalog = createProjectCatalog(restoreRoot);
  try {
  assert.equal((await restored.readMessages(session.id))[0]?.id, 'message-1');
  assert.equal(
  await readFile(join(restoreRoot, 'artifacts', artifact.relativePath), 'utf8'),
  'artifact',
  );
+ assert.equal(
+ (await restored.readHeaderSnapshot(session.id)).projectId,
+ project.id,
+ 'a restored session still belongs to the project it was grouped under',
+ );
+ assert.deepEqual(await restoredCatalog.list(), [
+ {
+ id: project.id,
+ name: 'Renamed Project',
+ locations: [{ path: await realpath(projectPath), isWorktree: false }],
+ archivedAt: 5,
+ available: true,
+ preferredPath: await realpath(projectPath),
+ },
+ ]);
  } finally {
  await restored.close?.();
+ restoredCatalog.close();
  }
  } finally {
  await rm(base, { recursive: true, force: true });

packages/storage/src/__tests__/project-catalog.test.ts

@@ -40,7 +40,9 @@ test('a Git probe failure cannot persistently downgrade a repository to a folder
  await execFileAsync('git', ['init', '--quiet'], { cwd: repository });
 
  await assert.rejects(() => registerProjectWithoutGit(repository, storage));
- await assert.rejects(() => readFile(join(storage, 'projects.json')), { code: 'ENOENT' });
+ // Nothing may be recorded: a folder identity written here would outlive the
+ // probe failure and permanently split the repository from its worktrees.
+ assert.deepEqual(await createProjectCatalog(storage).list(), []);
  } finally {
  await rm(base, { recursive: true, force: true });
  }
@@ -227,6 +229,84 @@ test('a missing project directory remains in the catalog as unavailable', async
  }
 });
 
+test('two catalogs changing one project at the same time keep both changes', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-concurrent-'));
+ try {
+ const workspace = join(base, 'workspace');
+ const storage = join(base, 'storage');
+ await mkdir(workspace);
+ const first = createProjectCatalog(storage, { now: () => 1_000 });
+ const second = createProjectCatalog(storage, { now: () => 2_000 });
+ const project = await first.register(workspace);
+ // Both catalogs settle their one-time legacy-import probe first, so the two
+ // mutations below really do overlap instead of queueing behind that I/O.
+ await Promise.all([first.list(), second.list()]);
+
+ // Each catalog rewrites the whole table; without holding the write lock
+ // across its own read, the later writer replays a stale copy and the other
+ // window's edit disappears with no error anywhere.
+ await Promise.all([second.archive(project.id), first.rename(project.id, 'Renamed')]);
+
+ const [merged] = await first.list();
+ assert.equal(merged?.name, 'Renamed', 'the rename must survive the concurrent archive');
+ assert.equal(merged?.archivedAt, 2_000, 'the archive must survive the concurrent rename');
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a relink whose merge target changes mid-flight fails instead of half-committing', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-race-'));
+ try {
+ const storage = join(base, 'storage');
+ const home = join(base, 'home');
+ const shared = join(base, 'shared');
+ const elsewhere = join(base, 'elsewhere');
+ await Promise.all([mkdir(home), mkdir(shared), mkdir(elsewhere)]);
+ const first = createProjectCatalog(storage);
+ const second = createProjectCatalog(storage);
+ const moving = await first.register(home);
+ const target = await first.register(shared);
+ await Promise.all([first.list(), second.list()]);
+
+ let releaseCallback!: () => void;
+ let callbackStarted!: () => void;
+ const gate = new Promise<void>((release) => {
+ releaseCallback = release;
+ });
+ const started = new Promise<void>((resolve) => {
+ callbackStarted = resolve;
+ });
+ let observed: string | undefined;
+ const relink = first.relink(moving.id, shared, async (context) => {
+ observed = context.conflictingProjectId;
+ callbackStarted();
+ await gate;
+ });
+ await started;
+
+ // The callback was told to move `target`'s sessions onto `moving`. While it
+ // is doing that, the other window moves `target` somewhere else entirely.
+ await second.relink(target.id, elsewhere);
+ releaseCallback();
+
+ assert.equal(observed, target.id, 'precondition: the callback planned a merge');
+ await assert.rejects(() => relink, /retry/);
+ const projects = await first.list();
+ assert.deepEqual(
+ projects.map((project) => project.id).sort(),
+ [moving.id, target.id].sort(),
+ 'neither project may be merged away after the plan went stale',
+ );
+ first.close();
+ second.close();
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
 test('relinking an unavailable project preserves its id and adopts the new directory', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-relink-'));
  try {
@@ -418,7 +498,7 @@ test('selecting a project returns its most recent available location and rejects
  }
 });
 
-test('a malformed project catalog fails closed without overwriting it', async () => {
+test('a malformed legacy catalog is reported and preserved without blocking the catalog', async () => {
  const base = await mkdtemp(join(tmpdir(), 'maka-project-corrupt-'));
  try {
  const workspace = join(base, 'workspace');
@@ -428,10 +508,79 @@ test('a malformed project catalog fails closed without overwriting it', async ()
  await mkdir(storage);
  const original = '{"schemaVersion":1,"projects":[{}]}\n';
  await writeFile(catalogPath, original, 'utf8');
- const catalog = createProjectCatalog(storage);
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
 
- await assert.rejects(() => catalog.register(workspace), /Invalid project catalog/);
+ // SQLite is the authority: a legacy file that cannot be read must not take
+ // the catalog down with it, and it must stay on disk to recover by hand.
+ const project = await catalog.register(workspace);
+
+ assert.equal((await catalog.list()).length, 1);
+ assert.equal((await catalog.list())[0]?.id, project.id);
  assert.equal(await readFile(catalogPath, 'utf8'), original);
+ assert.equal(failures.length, 1);
+ assert.match(String(failures[0]), /Invalid project catalog/);
+ } finally {
+ await rm(base, { recursive: true, force: true });
+ }
+});
+
+test('a legacy catalog is imported once and then set aside', async () => {
+ const base = await mkdtemp(join(tmpdir(), 'maka-project-import-'));
+ try {
+ const storage = join(base, 'storage');
+ await mkdir(storage);
+ await writeFile(
+ join(storage, 'projects.json'),
+ JSON.stringify({
+ schemaVersion: 1,
+ projects: [
+ {
+ id: 'legacy-project',
+ aliases: ['merged-away'],
+ name: 'Renamed By Hand',
+ identity: 'folder:/gone',
+ locations: [{ path: '/gone', isWorktree: false, lastUsedAt: 5 }],
+ lastUsedAt: 7,
+ archivedAt: 9,
+ },
+ ],
+ }),
+ 'utf8',
+ );
+ const failures: unknown[] = [];
+ const catalog = createProjectCatalog(storage, {
+ now: () => 1_000,
+ onLegacyImportFailure: (error) => failures.push(error),
+ });
+
+ const projects = await catalog.list();
+
+ assert.deepEqual(failures, []);
+ // The user's name, relink aliases and archive state only ever lived in this
+ // file; losing them on upgrade would be indistinguishable from data loss.
+ assert.equal(projects.length, 1);
+ assert.equal(projects[0]?.id, 'legacy-project');
+ assert.equal(projects[0]?.name, 'Renamed By Hand');
+ assert.deepEqual(projects[0]?.aliases, ['merged-away']);
+ assert.equal(projects[0]?.archivedAt, 9);
+ await assert.rejects(() => readFile(join(storage, 'projects.json'), 'utf8'), {
+ code: 'ENOENT',
+ });
+ const setAside = JSON.parse(
+ await readFile(join(storage, 'projects.json.imported-1000'), 'utf8'),
+ ) as { projects: Array<{ id: string }> };
+ assert.deepEqual(
+ setAside.projects.map((project) => project.id),
+ ['legacy-project'],
+ 'the imported file is kept verbatim so a bad upgrade stays recoverable',
+ );
+
+ // A catalog opened later must not re-import and must not lose the state.
+ catalog.close();
+ assert.equal((await createProjectCatalog(storage).list()).length, 1);
  } finally {
  await rm(base, { recursive: true, force: true });
  }