feat(FN-709): store branch name on tasks for reliable merge recovery

- Add 'branch' field to Task and ArchivedTaskEntry types with DB migration - Executor stores branch name on task after worktree assignment - Merger reads branch from task metadata instead of relying on worktree state - Implement non-destructive conflict recovery in prepareForTask with reset/clean - Add tests for branch storage, merger branch reading, and worktree recovery
2026-04-02 14:08:31 -07:00
parent 98dd0fad01
commit 0258c21ff6
10 changed files with 241 additions and 78 deletions
--- a/packages/core/src/db.test.ts
+++ b/packages/core/src/db.test.ts
@@ -86,7 +86,7 @@ describe("Database", () => {
    });

    it("seeds schema version", () => {
-      expect(db.getSchemaVersion()).toBe(5);
+      expect(db.getSchemaVersion()).toBe(6);
    });

    it("seeds lastModified", () => {
@@ -109,7 +109,7 @@ describe("Database", () => {

    it("is idempotent - calling init() twice does not fail", () => {
      expect(() => db.init()).not.toThrow();
-      expect(db.getSchemaVersion()).toBe(5);
+      expect(db.getSchemaVersion()).toBe(6);
    });

    it("does not overwrite existing config on re-init", () => {
@@ -704,7 +704,7 @@ describe("schema migrations", () => {
    db.init();

    // Verify version bumped to 5 (includes v1→v2, v2→v3, v3→v4, and v4→v5 migrations)
-    expect(db.getSchemaVersion()).toBe(5);
+    expect(db.getSchemaVersion()).toBe(6);

    // Verify new columns exist and existing data is intact
    const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
@@ -729,11 +729,11 @@ describe("schema migrations", () => {
    const db = new Database(kbDir);
    db.init();

-    expect(db.getSchemaVersion()).toBe(5);
+    expect(db.getSchemaVersion()).toBe(6);

    // Re-init should not fail
    db.init();
-    expect(db.getSchemaVersion()).toBe(5);
+    expect(db.getSchemaVersion()).toBe(6);

    db.close();
  });
@@ -828,13 +828,14 @@ describe("schema migrations", () => {
    db.init();

    // Verify version bumped to 5
-    expect(db.getSchemaVersion()).toBe(5);
+    expect(db.getSchemaVersion()).toBe(6);

    // Verify new columns exist and existing data is intact
    const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
    const colNames = cols.map((c) => c.name);
    expect(colNames).toContain("missionId");
    expect(colNames).toContain("sliceId");
+    expect(colNames).toContain("branch");

    // Existing task should still be readable
    const task = db.prepare("SELECT * FROM tasks WHERE id = 'KB-2'").get() as any;
@@ -1037,7 +1038,7 @@ describe("createDatabase factory", () => {
    const db = createDatabase(kbDir);
    db.init();

-    expect(db.getSchemaVersion()).toBe(5);
+    expect(db.getSchemaVersion()).toBe(6);
    expect(db.getLastModified()).toBeGreaterThan(0);

    db.close();
--- a/packages/core/src/db.ts
+++ b/packages/core/src/db.ts
@@ -402,8 +402,14 @@ export class Database {
      });
    }

+    if (version < 6) {
+      this.applyMigration(6, () => {
+        this.addColumnIfMissing("tasks", "branch", "TEXT");
+      });
+    }
+
    // Future migrations go here:
-    // if (version < 6) { this.applyMigration(6, () => { ... }); }
+    // if (version < 7) { this.applyMigration(7, () => { ... }); }
  }

  /**
--- a/packages/core/src/store.ts
+++ b/packages/core/src/store.ts
@@ -165,6 +165,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
      blockedBy: row.blockedBy || undefined,
      paused: row.paused ? true : undefined,
      baseBranch: row.baseBranch || undefined,
+      branch: row.branch || undefined,
      baseCommitSha: row.baseCommitSha || undefined,
      modelPresetId: row.modelPresetId || undefined,
      modelProvider: row.modelProvider || undefined,
@@ -208,7 +209,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
    this.db.prepare(`
      INSERT OR REPLACE INTO tasks (
        id, title, description, "column", status, size, reviewLevel, currentStep,
-        worktree, blockedBy, paused, baseBranch, baseCommitSha, modelPresetId, modelProvider,
+        worktree, blockedBy, paused, baseBranch, branch, baseCommitSha, modelPresetId, modelProvider,
        modelId, validatorModelProvider, validatorModelId, mergeRetries, error,
        summary, thinkingLevel, createdAt, updatedAt, columnMovedAt,
        dependencies, steps, log, attachments, steeringComments,
@@ -216,7 +217,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
        breakIntoSubtasks, enabledWorkflowSteps, modifiedFiles, missionId, sliceId
      ) VALUES (
        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
-        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
      )
    `).run(
      task.id,
@@ -231,6 +232,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
      task.blockedBy ?? null,
      task.paused ? 1 : 0,
      task.baseBranch ?? null,
+      task.branch ?? null,
      task.baseCommitSha ?? null,
      task.modelPresetId ?? null,
      task.modelProvider ?? null,
@@ -925,7 +927,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {

  async updateTask(
    id: string,
-    updates: { title?: string; description?: string; prompt?: string; worktree?: string; status?: string | null; dependencies?: string[]; blockedBy?: string | null; paused?: boolean; baseBranch?: string; baseCommitSha?: string; size?: "S" | "M" | "L"; reviewLevel?: number; mergeRetries?: number; modelProvider?: string | null; modelId?: string | null; validatorModelProvider?: string | null; validatorModelId?: string | null; error?: string | null; summary?: string | null; workflowStepResults?: import("./types.js").WorkflowStepResult[] | null; modifiedFiles?: string[] | null; missionId?: string | null; sliceId?: string | null },
+    updates: { title?: string; description?: string; prompt?: string; worktree?: string; status?: string | null; dependencies?: string[]; blockedBy?: string | null; paused?: boolean; baseBranch?: string; branch?: string; baseCommitSha?: string; size?: "S" | "M" | "L"; reviewLevel?: number; mergeRetries?: number; modelProvider?: string | null; modelId?: string | null; validatorModelProvider?: string | null; validatorModelId?: string | null; error?: string | null; summary?: string | null; workflowStepResults?: import("./types.js").WorkflowStepResult[] | null; modifiedFiles?: string[] | null; missionId?: string | null; sliceId?: string | null },
  ): Promise<Task> {
    return this.withTaskLock(id, async () => {
      // Validate that task doesn't depend on itself
@@ -975,6 +977,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
      }
      if (updates.paused !== undefined) task.paused = updates.paused || undefined;
      if (updates.baseBranch !== undefined) task.baseBranch = updates.baseBranch;
+      if (updates.branch !== undefined) task.branch = updates.branch;
      if (updates.baseCommitSha !== undefined) task.baseCommitSha = updates.baseCommitSha;
      if (updates.size !== undefined) task.size = updates.size;
      if (updates.reviewLevel !== undefined) task.reviewLevel = updates.reviewLevel;
@@ -1551,6 +1554,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
          breakIntoSubtasks: task.breakIntoSubtasks,
          paused: task.paused,
          baseBranch: task.baseBranch,
+          branch: task.branch,
          baseCommitSha: task.baseCommitSha,
          mergeRetries: task.mergeRetries,
          error: task.error,
@@ -2365,6 +2369,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
        breakIntoSubtasks: task.breakIntoSubtasks,
        paused: task.paused,
        baseBranch: task.baseBranch,
+        branch: task.branch,
        baseCommitSha: task.baseCommitSha,
        mergeRetries: task.mergeRetries,
        error: task.error,
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -426,6 +426,11 @@ export interface Task {
   *  unmerged branch. The executor reads this to branch from the
   *  dependency's branch instead of HEAD. Cleared after worktree creation. */
  baseBranch?: string;
+  /** Actual git branch name used for this task's worktree. May differ from
+   *  the conventional `kb/{task-id}` when conflict recovery generated a
+   *  unique suffixed name (e.g., `kb/fn-042-2`). The merger and PR systems
+   *  read this field instead of deriving the branch from the task ID. */
+  branch?: string;
  /** Base commit SHA for creating this task's worktree. Used with baseBranch
   *  to establish the exact starting point for the worktree. */
  baseCommitSha?: string;
@@ -947,6 +952,8 @@ export interface ArchivedTaskEntry {
  breakIntoSubtasks?: boolean;
  paused?: boolean;
  baseBranch?: string;
+  /** Actual git branch name used for this task's worktree */
+  branch?: string;
  /** Base commit SHA for the task's worktree */
  baseCommitSha?: string;
  /** List of files modified by this task */