trekoon 0.2.0 → 0.2.4

package/src/runtime/cli-shell.ts

@@ -5,12 +5,14 @@ import { runEvents } from "../commands/events";
 import { runInit } from "../commands/init";
 import { runMigrate } from "../commands/migrate";
 import { runQuickstart } from "../commands/quickstart";
+import { runSession } from "../commands/session";
 import { runSkills } from "../commands/skills";
 import { runSubtask } from "../commands/subtask";
 import { runSync } from "../commands/sync";
 import { runTask } from "../commands/task";
 import { runWipe } from "../commands/wipe";
 import { failResult, okResult, renderResult } from "../io/output";
+import { resolveStorageResolutionDiagnostics } from "../storage/database";
 import { type CliContext, type CliResult, type CompatibilityMode, type OutputMode } from "./command-types";
 import { CLI_VERSION } from "./version";
 import { resolveStoragePaths } from "../storage/path";
@@ -19,6 +21,7 @@ const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
   "help",
   "init",
   "quickstart",
+  "session",
   "epic",
   "task",
   "subtask",
@@ -119,9 +122,68 @@ export function renderShellResult(result: CliResult, mode: OutputMode, compatibi
   return renderResult(result, mode, { compatibilityMode: effectiveCompatibilityMode });
 }
 
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry: unknown) => typeof entry === "string");
+}
+
+function readResultStorageResolutionDiagnostics(result: CliResult) {
+  const data: unknown = result.data;
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+
+  const candidate: Record<string, unknown> = data as Record<string, unknown>;
+  if (
+    typeof candidate.invocationCwd !== "string"
+    || typeof candidate.storageMode !== "string"
+    || (candidate.repoCommonDir !== null && typeof candidate.repoCommonDir !== "string")
+    || typeof candidate.worktreeRoot !== "string"
+    || typeof candidate.sharedStorageRoot !== "string"
+    || typeof candidate.databaseFile !== "string"
+    || typeof candidate.legacyStateDetected !== "boolean"
+    || typeof candidate.recoveryRequired !== "boolean"
+    || typeof candidate.recoveryStatus !== "string"
+    || !isStringArray(candidate.legacyDatabaseFiles)
+    || !isStringArray(candidate.backupFiles)
+    || !isStringArray(candidate.trackedStorageFiles)
+    || typeof candidate.autoMigratedLegacyState !== "boolean"
+    || (candidate.importedFromLegacyDatabase !== null && typeof candidate.importedFromLegacyDatabase !== "string")
+    || typeof candidate.operatorAction !== "string"
+  ) {
+    return null;
+  }
+
+  return {
+    invocationCwd: candidate.invocationCwd,
+    storageMode: candidate.storageMode,
+    repoCommonDir: candidate.repoCommonDir,
+    worktreeRoot: candidate.worktreeRoot,
+    sharedStorageRoot: candidate.sharedStorageRoot,
+    databaseFile: candidate.databaseFile,
+    legacyStateDetected: candidate.legacyStateDetected,
+    recoveryRequired: candidate.recoveryRequired,
+    recoveryStatus: candidate.recoveryStatus,
+    legacyDatabaseFiles: candidate.legacyDatabaseFiles,
+    backupFiles: candidate.backupFiles,
+    trackedStorageFiles: candidate.trackedStorageFiles,
+    autoMigratedLegacyState: candidate.autoMigratedLegacyState,
+    importedFromLegacyDatabase: candidate.importedFromLegacyDatabase,
+    operatorAction: candidate.operatorAction,
+  };
+}
+
 function withStorageRootDiagnostics(result: CliResult, cwd: string): CliResult {
-  const diagnostics = resolveStoragePaths(cwd).diagnostics;
-  if (diagnostics.warnings.length === 0 && diagnostics.errors.length === 0) {
+  const paths = resolveStoragePaths(cwd);
+  const diagnostics = paths.diagnostics;
+  const resultDiagnostics = readResultStorageResolutionDiagnostics(result);
+  const resolutionDiagnostics = resultDiagnostics ?? resolveStorageResolutionDiagnostics(cwd);
+
+  if (
+    !resolutionDiagnostics.legacyStateDetected
+    && diagnostics.warnings.length === 0
+    && diagnostics.errors.length === 0
+    && resultDiagnostics === null
+  ) {
     return result;
   }
 
@@ -131,9 +193,22 @@ function withStorageRootDiagnostics(result: CliResult, cwd: string): CliResult {
       ...(result.meta ?? {}),
       storageRootDiagnostics: {
         invocationCwd: diagnostics.invocationCwd,
-        canonicalRoot: diagnostics.canonicalRoot,
-        warning: diagnostics.warnings[0] ?? null,
-        error: diagnostics.errors[0] ?? null,
+        storageMode: diagnostics.storageMode,
+        repoCommonDir: diagnostics.repoCommonDir,
+        worktreeRoot: diagnostics.worktreeRoot,
+        sharedStorageRoot: diagnostics.sharedStorageRoot,
+        databaseFile: diagnostics.databaseFile,
+        legacyStateDetected: resolutionDiagnostics.legacyStateDetected,
+        recoveryRequired: resolutionDiagnostics.recoveryRequired,
+        recoveryStatus: resolutionDiagnostics.recoveryStatus,
+        legacyDatabaseFiles: resolutionDiagnostics.legacyDatabaseFiles,
+        backupFiles: resolutionDiagnostics.backupFiles,
+        trackedStorageFiles: resolutionDiagnostics.trackedStorageFiles,
+        autoMigratedLegacyState: resolutionDiagnostics.autoMigratedLegacyState,
+        importedFromLegacyDatabase: resolutionDiagnostics.importedFromLegacyDatabase,
+        operatorAction: resolutionDiagnostics.operatorAction,
+        warnings: diagnostics.warnings,
+        errors: diagnostics.errors,
       },
     },
   };
@@ -289,6 +364,9 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
     case "sync":
       result = await runSync(context);
       break;
+    case "session":
+      result = await runSession(context);
+      break;
     case "skills":
       result = await runSkills(context);
       break;

package/src/storage/database.ts

@@ -2,12 +2,37 @@ import { mkdirSync } from "node:fs";
 
 import { Database } from "bun:sqlite";
 
+import { DomainError } from "../domain/types";
 import { migrateDatabase } from "./migrations";
 import { resolveStoragePaths, type StoragePaths } from "./path";
+import {
+  inspectWorktreeDatabaseState,
+  recoverWorktreeDatabaseState,
+  type WorktreeRecoveryDiagnostics,
+} from "./worktree-recovery";
+
+export interface StorageResolutionDiagnostics {
+  readonly invocationCwd: string;
+  readonly storageMode: StoragePaths["storageMode"];
+  readonly repoCommonDir: string | null;
+  readonly worktreeRoot: string;
+  readonly sharedStorageRoot: string;
+  readonly databaseFile: string;
+  readonly legacyStateDetected: boolean;
+  readonly recoveryRequired: boolean;
+  readonly recoveryStatus: WorktreeRecoveryDiagnostics["status"];
+  readonly legacyDatabaseFiles: readonly string[];
+  readonly backupFiles: readonly string[];
+  readonly trackedStorageFiles: readonly string[];
+  readonly autoMigratedLegacyState: boolean;
+  readonly importedFromLegacyDatabase: string | null;
+  readonly operatorAction: string;
+}
 
 export interface TrekoonDatabase {
   readonly db: Database;
   readonly paths: StoragePaths;
+  readonly diagnostics: StorageResolutionDiagnostics;
   close(): void;
 }
 
@@ -15,11 +40,71 @@ export interface OpenTrekoonDatabaseOptions {
   readonly autoMigrate?: boolean;
 }
 
+function buildStorageResolutionDiagnostics(
+  paths: StoragePaths,
+  recovery: WorktreeRecoveryDiagnostics,
+): StorageResolutionDiagnostics {
+  const legacyStateDetected: boolean = recovery.legacyDatabaseFiles.length > 0;
+  const recoveryRequired: boolean =
+    recovery.status === "ambiguous_recovery" || recovery.status === "tracked_ignored_mismatch";
+
+  return {
+    invocationCwd: paths.invocationCwd,
+    storageMode: paths.storageMode,
+    repoCommonDir: paths.repoCommonDir,
+    worktreeRoot: paths.worktreeRoot,
+    sharedStorageRoot: paths.sharedStorageRoot,
+    databaseFile: paths.databaseFile,
+    legacyStateDetected,
+    recoveryRequired,
+    recoveryStatus: recovery.status,
+    legacyDatabaseFiles: recovery.legacyDatabaseFiles,
+    backupFiles: recovery.backupFiles,
+    trackedStorageFiles: recovery.trackedStorageFiles,
+    autoMigratedLegacyState: recovery.autoMigrated,
+    importedFromLegacyDatabase: recovery.importedFrom,
+    operatorAction: recovery.operatorAction,
+  };
+}
+
+export function resolveStorageResolutionDiagnostics(
+  workingDirectory: string = process.cwd(),
+): StorageResolutionDiagnostics {
+  const paths: StoragePaths = resolveStoragePaths(workingDirectory);
+
+  try {
+    return buildStorageResolutionDiagnostics(paths, inspectWorktreeDatabaseState(paths));
+  } catch (error) {
+    if (!(error instanceof DomainError)) {
+      throw error;
+    }
+
+    const details: Record<string, unknown> = error.details ?? {};
+    const recovery: WorktreeRecoveryDiagnostics = {
+      status: (details.status as WorktreeRecoveryDiagnostics["status"] | undefined) ?? "no_legacy_state",
+      legacyDatabaseFiles: Array.isArray(details.legacyDatabaseFiles)
+        ? (details.legacyDatabaseFiles as string[])
+        : [],
+      backupFiles: Array.isArray(details.backupFiles) ? (details.backupFiles as string[]) : [],
+      trackedStorageFiles: Array.isArray(details.trackedStorageFiles)
+        ? (details.trackedStorageFiles as string[])
+        : [],
+      autoMigrated: details.autoMigrated === true,
+      importedFrom: typeof details.importedFrom === "string" ? details.importedFrom : null,
+      operatorAction: typeof details.operatorAction === "string" ? details.operatorAction : error.message,
+    };
+
+    return buildStorageResolutionDiagnostics(paths, recovery);
+  }
+}
+
 export function openTrekoonDatabase(
   workingDirectory: string = process.cwd(),
   options: OpenTrekoonDatabaseOptions = {},
 ): TrekoonDatabase {
   const paths: StoragePaths = resolveStoragePaths(workingDirectory);
+  const recovery: WorktreeRecoveryDiagnostics = recoverWorktreeDatabaseState(paths);
+  const diagnostics: StorageResolutionDiagnostics = buildStorageResolutionDiagnostics(paths, recovery);
 
   mkdirSync(paths.storageDir, { recursive: true });
 
@@ -36,6 +121,7 @@ export function openTrekoonDatabase(
   return {
     db,
     paths,
+    diagnostics,
     close(): void {
       db.exec("PRAGMA wal_checkpoint(PASSIVE);");
       db.close(false);

package/src/storage/migrations.ts

@@ -58,6 +58,43 @@ const EVENT_ARCHIVE_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
   "DROP TABLE IF EXISTS event_archive;",
 ];
 
+function tableHasColumn(db: Database, tableName: string, columnName: string): boolean {
+  const columns = db.query(`PRAGMA table_info(${tableName});`).all() as Array<{ name: string }>;
+  return columns.some((column) => column.name === columnName);
+}
+
+function migrateWorktreeScopedSyncMetadata(db: Database): void {
+  if (!tableHasColumn(db, "git_context", "metadata_scope")) {
+    db.exec("ALTER TABLE git_context ADD COLUMN metadata_scope TEXT NOT NULL DEFAULT 'worktree';");
+  }
+
+  db.exec("UPDATE git_context SET metadata_scope = 'worktree' WHERE metadata_scope IS NULL OR metadata_scope = ''; ");
+  db.exec("UPDATE git_context SET id = worktree_path WHERE id = 'current' AND worktree_path <> ''; ");
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_git_context_scope_path ON git_context(metadata_scope, worktree_path);");
+
+  if (!tableHasColumn(db, "sync_cursors", "owner_scope")) {
+    db.exec("ALTER TABLE sync_cursors ADD COLUMN owner_scope TEXT NOT NULL DEFAULT 'worktree';");
+  }
+
+  if (!tableHasColumn(db, "sync_cursors", "owner_worktree_path")) {
+    db.exec("ALTER TABLE sync_cursors ADD COLUMN owner_worktree_path TEXT NOT NULL DEFAULT ''; ");
+  }
+
+  db.exec("UPDATE sync_cursors SET owner_scope = 'worktree' WHERE owner_scope IS NULL OR owner_scope = ''; ");
+  db.exec(`
+    UPDATE sync_cursors
+    SET owner_worktree_path = COALESCE(
+      NULLIF(owner_worktree_path, ''),
+      (SELECT worktree_path FROM git_context ORDER BY updated_at DESC LIMIT 1),
+      ''
+    );
+  `);
+  db.exec("UPDATE sync_cursors SET id = owner_worktree_path || '::' || source_branch;");
+  db.exec(
+    "CREATE UNIQUE INDEX IF NOT EXISTS idx_sync_cursors_owner ON sync_cursors(owner_scope, owner_worktree_path, source_branch);",
+  );
+}
+
 interface Migration {
   readonly version: number;
   readonly name: string;
@@ -134,6 +171,17 @@ const MIGRATIONS: readonly Migration[] = [
       }
     },
   },
+  {
+    version: 4,
+    name: "0004_worktree_scoped_sync_metadata",
+    up(db: Database): void {
+      migrateWorktreeScopedSyncMetadata(db);
+    },
+    down(db: Database): void {
+      db.exec("DROP INDEX IF EXISTS idx_sync_cursors_owner;");
+      db.exec("DROP INDEX IF EXISTS idx_git_context_scope_path;");
+    },
+  },
 ];
 
 function migrationTableExists(db: Database): boolean {

package/src/storage/path.ts

@@ -1,12 +1,26 @@
 import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 
-const DB_DIRNAME = ".trekoon";
-const DB_FILENAME = "trekoon.db";
+export const TREKOON_STORAGE_DIRNAME = ".trekoon";
+export const TREKOON_DATABASE_FILENAME = "trekoon.db";
+
+export function resolveLegacyWorktreeStorageDir(worktreeRoot: string): string {
+  return resolve(worktreeRoot, TREKOON_STORAGE_DIRNAME);
+}
+
+export function resolveLegacyWorktreeDatabaseFile(worktreeRoot: string): string {
+  return resolve(resolveLegacyWorktreeStorageDir(worktreeRoot), TREKOON_DATABASE_FILENAME);
+}
+
+export type StorageMode = "cwd" | "git_common_dir";
 
 export interface StoragePaths {
   readonly invocationCwd: string;
+  readonly storageMode: StorageMode;
+  readonly repoCommonDir: string | null;
   readonly worktreeRoot: string;
+  readonly sharedStorageRoot: string;
   readonly storageDir: string;
   readonly databaseFile: string;
   readonly diagnostics: StoragePathDiagnostics;
@@ -16,18 +30,26 @@ export interface StoragePathIssue {
   readonly code: string;
   readonly message: string;
   readonly invocationCwd: string;
-  readonly canonicalRoot: string;
+  readonly storageMode: StorageMode;
+  readonly repoCommonDir: string | null;
+  readonly worktreeRoot: string;
+  readonly sharedStorageRoot: string;
+  readonly databaseFile: string;
 }
 
 export interface StoragePathDiagnostics {
   readonly invocationCwd: string;
-  readonly canonicalRoot: string;
+  readonly storageMode: StorageMode;
+  readonly repoCommonDir: string | null;
+  readonly worktreeRoot: string;
+  readonly sharedStorageRoot: string;
+  readonly databaseFile: string;
   readonly warnings: readonly StoragePathIssue[];
   readonly errors: readonly StoragePathIssue[];
 }
 
-function resolveGitTopLevel(workingDirectory: string): string | null {
-  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+function resolveGitPath(workingDirectory: string, argument: "--git-common-dir" | "--show-toplevel"): string | null {
+  const result = spawnSync("git", ["rev-parse", argument], {
     cwd: workingDirectory,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"],
@@ -37,41 +59,68 @@ function resolveGitTopLevel(workingDirectory: string): string | null {
     return null;
   }
 
-  const topLevel: string = result.stdout.trim();
-  if (!topLevel) {
+  const rawPath: string = result.stdout.trim();
+  if (!rawPath) {
     return null;
   }
 
-  return resolve(topLevel);
+  return resolve(workingDirectory, rawPath);
 }
 
 export function resolveStoragePaths(workingDirectory: string = process.cwd()): StoragePaths {
   const invocationCwd: string = resolve(workingDirectory);
-  const canonicalRoot: string = resolveGitTopLevel(invocationCwd) ?? invocationCwd;
-  const worktreeRoot: string = canonicalRoot;
-  const storageDir: string = resolve(worktreeRoot, DB_DIRNAME);
-  const databaseFile: string = resolve(storageDir, DB_FILENAME);
+  const worktreeRoot: string = resolveGitPath(invocationCwd, "--show-toplevel") ?? invocationCwd;
+  const repoCommonDirRaw: string | null = resolveGitPath(invocationCwd, "--git-common-dir");
+  const repoCommonDir: string | null = repoCommonDirRaw ? realpathSync(repoCommonDirRaw) : null;
+  const storageMode: StorageMode = repoCommonDir ? "git_common_dir" : "cwd";
+  const sharedStorageRoot: string = repoCommonDir ? realpathSync(resolve(repoCommonDir, "..")) : invocationCwd;
+  const storageDir: string = resolve(sharedStorageRoot, TREKOON_STORAGE_DIRNAME);
+  const databaseFile: string = resolve(storageDir, TREKOON_DATABASE_FILENAME);
   const warnings: StoragePathIssue[] = [];
 
-  if (invocationCwd !== canonicalRoot) {
-    warnings.push({
-      code: "storage_root_diverged_from_cwd",
-      message: "Resolved storage root differs from invocation cwd.",
-      invocationCwd,
-      canonicalRoot,
-    });
+  const createIssue = (code: string, message: string): StoragePathIssue => ({
+    code,
+    message,
+    invocationCwd,
+    storageMode,
+    repoCommonDir,
+    worktreeRoot,
+    sharedStorageRoot,
+    databaseFile,
+  });
+
+  if (invocationCwd !== worktreeRoot) {
+    warnings.push(
+      createIssue("storage_root_diverged_from_cwd", "Resolved worktree root differs from invocation cwd."),
+    );
+  }
+
+  if (sharedStorageRoot !== worktreeRoot) {
+    warnings.push(
+      createIssue(
+        "shared_storage_root_differs_from_worktree_root",
+        "Resolved shared storage root differs from worktree root.",
+      ),
+    );
   }
 
   const diagnostics: StoragePathDiagnostics = {
     invocationCwd,
-    canonicalRoot,
+    storageMode,
+    repoCommonDir,
+    worktreeRoot,
+    sharedStorageRoot,
+    databaseFile,
     warnings,
     errors: [],
   };
 
   return {
     invocationCwd,
+    storageMode,
+    repoCommonDir,
     worktreeRoot,
+    sharedStorageRoot,
     storageDir,
     databaseFile,
     diagnostics,

package/src/storage/schema.ts

@@ -76,23 +76,28 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `
   CREATE TABLE IF NOT EXISTS git_context (
     id TEXT PRIMARY KEY,
+    metadata_scope TEXT NOT NULL DEFAULT 'worktree',
     worktree_path TEXT NOT NULL,
     branch_name TEXT,
     head_sha TEXT,
     created_at INTEGER NOT NULL,
     updated_at INTEGER NOT NULL,
-    version INTEGER NOT NULL DEFAULT 1
+    version INTEGER NOT NULL DEFAULT 1,
+    UNIQUE (metadata_scope, worktree_path)
   );
   `,
   `
   CREATE TABLE IF NOT EXISTS sync_cursors (
     id TEXT PRIMARY KEY,
+    owner_scope TEXT NOT NULL DEFAULT 'worktree',
+    owner_worktree_path TEXT NOT NULL,
     source_branch TEXT NOT NULL,
     cursor_token TEXT NOT NULL,
     last_event_at INTEGER,
     created_at INTEGER NOT NULL,
     updated_at INTEGER NOT NULL,
-    version INTEGER NOT NULL DEFAULT 1
+    version INTEGER NOT NULL DEFAULT 1,
+    UNIQUE (owner_scope, owner_worktree_path, source_branch)
   );
   `,
   `
@@ -113,5 +118,7 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `CREATE INDEX IF NOT EXISTS idx_tasks_epic_id ON tasks(epic_id);`,
   `CREATE INDEX IF NOT EXISTS idx_subtasks_task_id ON subtasks(task_id);`,
   `CREATE INDEX IF NOT EXISTS idx_events_entity ON events(entity_kind, entity_id);`,
+  `CREATE INDEX IF NOT EXISTS idx_git_context_scope_path ON git_context(metadata_scope, worktree_path);`,
+  `CREATE INDEX IF NOT EXISTS idx_sync_cursors_owner ON sync_cursors(owner_scope, owner_worktree_path, source_branch);`,
   `CREATE INDEX IF NOT EXISTS idx_conflicts_resolution ON sync_conflicts(resolution);`,
 ];