fix(agent,data): task-state-based serialization + planner restore for fast-mode bound tasks

Round 5 of branch-isolation hardening per PR #85 review.

- coordinator: serialization predicate now combines current config AND task
  state. Previously, toggling git.create_branches=false mid-pipeline opened
  the parallel pool even though restorePersistedBranch kept switching HEAD
  on already-bound tasks. Fix: parallel disabled when EITHER
  projectUsesSharedBranchIsolation(rootPath) OR
  hasActiveBranchBoundTasksForProject(projectId) is true. Applied in both
  processAutoQueueAdvance and resolveProjectConcurrency. Until #86
  introduces per-task worktrees, any in-flight bound task forces serial.
- data: new hasActiveBranchBoundTasksForProject query. Includes backlog so
  a task pre-bound by accept_existing_plan / replan does not let the pool
  open before its first stage starts. Includes blocked_external so retry
  cycles do not leak parallel concurrency.
- planner: restore is no longer gated by plannerMode. For ANY bound non-fix
  task, restorePersistedBranch fires regardless of full/fast mode. Branch
  CREATION stays full-mode-only (fast mode never provisions a new branch
  by design — see aif-handoff#83). Closes the mode-drift gap where a
  fast-mode replan of an already-bound task ran on whatever HEAD happened
  to be.

Tests:
- data: 4 cases for hasActiveBranchBoundTasksForProject (no branchName,
  in-flight bound, queued backlog bound, terminal bound).
- planner: regression test — fast plannerMode + persisted branchName +
  drifted HEAD → planner ends on the persisted branch, not on main.

npm run ai:validate green end-to-end.

Author: lee-to

packages/agent/src/__tests__/planner.test.ts

@@ -268,6 +268,63 @@ describe("runPlanner comment selection", () => {
     expect(updatedTask?.branchName).toBe(branch);
   });
 
+  it("restores persisted branch in fast plannerMode for already-bound task (mode-drift safe)", async () => {
+    const db = testDb.current;
+    const projectRoot = mkdtempSync(join(tmpdir(), "planner-mode-drift-"));
+    execFileSync("git", ["init", "--initial-branch=main"], { cwd: projectRoot, stdio: "ignore" });
+    execFileSync("git", ["config", "user.email", "t@t.local"], {
+      cwd: projectRoot,
+      stdio: "ignore",
+    });
+    execFileSync("git", ["config", "user.name", "T"], { cwd: projectRoot, stdio: "ignore" });
+    execFileSync("git", ["config", "commit.gpgsign", "false"], {
+      cwd: projectRoot,
+      stdio: "ignore",
+    });
+    writeFileSync(join(projectRoot, "README.md"), "# t\n");
+    execFileSync("git", ["add", "README.md"], { cwd: projectRoot, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "init", "--no-verify"], {
+      cwd: projectRoot,
+      stdio: "ignore",
+    });
+    // Bind a feature branch then drift HEAD back to main.
+    execFileSync("git", ["checkout", "-b", "feature/bound-fast"], {
+      cwd: projectRoot,
+      stdio: "ignore",
+    });
+    execFileSync("git", ["checkout", "main"], { cwd: projectRoot, stdio: "ignore" });
+
+    db.insert(projects)
+      .values({ id: "project-mode-drift", name: "Mode drift", rootPath: projectRoot })
+      .run();
+    db.insert(tasks)
+      .values({
+        id: "task-mode-drift-1",
+        projectId: "project-mode-drift",
+        title: "Mode drift",
+        description: "",
+        status: "planning",
+        // FAST mode + persisted branchName = the dangerous case the previous
+        // gating broke: restore must still happen, otherwise the planner
+        // writes plan/log on whatever HEAD happens to be.
+        plannerMode: "fast",
+        useSubagents: false,
+        branchName: "feature/bound-fast",
+      })
+      .run();
+
+    queryMock.mockReset();
+    queryMock.mockReturnValue(streamSuccess("## Plan\n- [ ] x"));
+
+    await runPlanner("task-mode-drift-1", projectRoot);
+
+    const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd: projectRoot,
+      encoding: "utf8",
+    }).trim();
+    expect(branch).toBe("feature/bound-fast");
+  });
+
   it("throws BranchIsolationError when subagent silently switched branches (drift)", async () => {
     const db = testDb.current;
     const projectRoot = mkdtempSync(join(tmpdir(), "planner-drift-"));

packages/agent/src/coordinator.ts

@@ -14,6 +14,7 @@ import {
   listAutoQueueProjects,
   nextBacklogTaskByPosition,
   countActivePipelineTasksForProject,
+  hasActiveBranchBoundTasksForProject,
   claimBacklogTaskForAdvance,
   persistTaskRuntimeLimitSnapshot,
   resolveEffectiveRuntimeProfile,
@@ -629,11 +630,22 @@ export function processAutoQueueAdvance(): number {
 
   let advanced = 0;
   for (const project of projects) {
-    const usesSharedBranchIsolation = projectUsesSharedBranchIsolation(project.rootPath);
+    // Serialization predicate combines:
+    //   - current config (`git.create_branches=true` on a real git repo), AND
+    //   - task state (any in-flight task already has a persisted branchName).
+    //
+    // Config alone is not enough: an operator can toggle `create_branches=off`
+    // mid-pipeline. `restorePersistedBranch` keeps switching HEAD for already
+    // bound tasks, so concurrent parallel stages would still race on the
+    // shared work tree. Until #86 introduces per-task worktrees, fall back to
+    // serial whenever EITHER signal says the project is shared-branch.
+    const usesSharedBranchIsolation =
+      projectUsesSharedBranchIsolation(project.rootPath) ||
+      hasActiveBranchBoundTasksForProject(project.id);
     if (project.parallelEnabled && usesSharedBranchIsolation) {
       log.warn(
         { projectId: project.id, projectRoot: project.rootPath },
-        "Auto-queue parallel pool disabled for git.create_branches project until per-task worktrees are available",
+        "Auto-queue parallel pool disabled for git.create_branches project (or active branch-bound tasks) until per-task worktrees are available",
       );
     }
     const limit =
@@ -764,8 +776,10 @@ export async function pollAndProcess(): Promise<void> {
     if (cached === undefined) {
       const project = findProjectById(projectId);
       const configuredParallel = project?.parallelEnabled ?? false;
+      // Mirror processAutoQueueAdvance: config OR task-state forces serial.
       const usesSharedBranchIsolation = project
-        ? projectUsesSharedBranchIsolation(project.rootPath)
+        ? projectUsesSharedBranchIsolation(project.rootPath) ||
+          hasActiveBranchBoundTasksForProject(projectId)
         : false;
       cached = {
         parallel: configuredParallel && !usesSharedBranchIsolation,
@@ -774,7 +788,7 @@ export async function pollAndProcess(): Promise<void> {
       if (configuredParallel && usesSharedBranchIsolation) {
         log.warn(
           { projectId, projectRoot: project?.rootPath },
-          "Project parallel execution forced to serial because git.create_branches uses a shared worktree",
+          "Project parallel execution forced to serial because git.create_branches uses a shared worktree (or active branch-bound tasks remain)",
         );
       }
       projectConcurrencyCache.set(projectId, cached);

packages/agent/src/subagents/planner.ts

@@ -145,52 +145,51 @@ export async function runPlanner(taskId: string, projectRoot: string): Promise<v
   const planDocs = task.planDocs ? "true" : "false";
   const planTests = task.planTests ? "true" : "false";
 
-  // Deterministic branch handling — runs regardless of whether the subagent
-  // skill honors Step 1.4. Only activates for full-mode plans; fast mode stays
-  // on current branch by design. See aif-handoff#83.
+  // Deterministic branch handling. Two contracts, applied in order:
   //
-  // Two paths:
-  //   - First-time provisioning (no persisted branchName): use
-  //     ensureFeatureBranch which can create from base.
-  //   - Re-run / replan (task.branchName already persisted): use
-  //     restorePersistedBranch so config drift cannot release us to current
-  //     HEAD via the `skipped` shortcut, and a deleted branch errors out
-  //     instead of being silently re-created from base.
+  //  1. RESTORE for ANY bound non-fix task — runs regardless of plannerMode
+  //     (full or fast). `task.branchName` is the source-of-truth: once a
+  //     prior run persisted it, every subsequent stage MUST land on it or
+  //     fail loud. A replan triggered with mode=fast (manual replanning,
+  //     comment-driven re-run) used to skip the restore entirely and let
+  //     the planner write to whatever HEAD happened to be.
+  //
+  //  2. CREATE only in full mode for unbound non-fix tasks. Fast mode stays
+  //     on the current branch by design (see aif-handoff#83) — first-time
+  //     branch provisioning is a full-mode-only concern.
   //
   // Failures throw BranchIsolationError (dirty worktree, missing base branch,
   // checkout failure, branch_missing, etc). The coordinator classifies it as
   // blocked_external with retryAfter=null so an operator can inspect the work
   // tree instead of the stage silently reverting into a bad state.
   let preparedBranch: string | null = task.branchName ?? null;
-  if (plannerMode === "full" && !task.isFix) {
-    if (task.branchName) {
-      restorePersistedBranch({
-        projectRoot,
-        taskId,
-        persistedBranchName: task.branchName,
+  if (!task.isFix && task.branchName) {
+    restorePersistedBranch({
+      projectRoot,
+      taskId,
+      persistedBranchName: task.branchName,
+    });
+    preparedBranch = task.branchName;
+    logActivity(taskId, "Agent", `Restored feature branch: ${task.branchName}`);
+  } else if (!task.isFix && plannerMode === "full") {
+    const branchResult = ensureFeatureBranch({
+      projectRoot,
+      taskId,
+      title: task.title,
+    });
+    if (branchResult.action !== "skipped" && branchResult.branchName) {
+      preparedBranch = branchResult.branchName;
+      setTaskFields(taskId, {
+        branchName: branchResult.branchName,
+        updatedAt: new Date().toISOString(),
       });
-      preparedBranch = task.branchName;
-      logActivity(taskId, "Agent", `Restored feature branch: ${task.branchName}`);
-    } else {
-      const branchResult = ensureFeatureBranch({
-        projectRoot,
+      logActivity(
         taskId,
-        title: task.title,
-      });
-      if (branchResult.action !== "skipped" && branchResult.branchName) {
-        preparedBranch = branchResult.branchName;
-        setTaskFields(taskId, {
-          branchName: branchResult.branchName,
-          updatedAt: new Date().toISOString(),
-        });
-        logActivity(
-          taskId,
-          "Agent",
-          `Feature branch ${branchResult.action}: ${branchResult.branchName}`,
-        );
-      } else if (branchResult.reason) {
-        log.debug({ taskId, reason: branchResult.reason }, "Branch creation skipped");
-      }
+        "Agent",
+        `Feature branch ${branchResult.action}: ${branchResult.branchName}`,
+      );
+    } else if (branchResult.reason) {
+      log.debug({ taskId, reason: branchResult.reason }, "Branch creation skipped");
     }
   }
 

packages/data/src/__tests__/index.test.ts

@@ -57,6 +57,7 @@ const {
   nextBacklogTaskByPosition,
   listAutoQueueProjects,
   countActivePipelineTasksForProject,
+  hasActiveBranchBoundTasksForProject,
   claimBacklogTaskForAdvance,
 } = await import("../index.js");
 
@@ -1132,6 +1133,34 @@ describe("data layer", () => {
       expect(countActivePipelineTasksForProject("proj-1")).toBe(1);
     });
 
+    it("hasActiveBranchBoundTasksForProject returns false when no task has a branchName", () => {
+      const a = createTask({ projectId: "proj-1", title: "A", description: "" });
+      updateTaskStatus(a!.id, "implementing");
+      expect(hasActiveBranchBoundTasksForProject("proj-1")).toBe(false);
+    });
+
+    it("hasActiveBranchBoundTasksForProject true once a branch-bound task is in flight", () => {
+      const a = createTask({ projectId: "proj-1", title: "A", description: "" });
+      setTaskFields(a!.id, { branchName: "feature/a" });
+      updateTaskStatus(a!.id, "implementing");
+      expect(hasActiveBranchBoundTasksForProject("proj-1")).toBe(true);
+    });
+
+    it("hasActiveBranchBoundTasksForProject true for a queued backlog task that already has branchName", () => {
+      // accept_existing_plan / replan can leave a branch-bound task in
+      // backlog briefly; serialization must already kick in.
+      const a = createTask({ projectId: "proj-1", title: "A", description: "" });
+      setTaskFields(a!.id, { branchName: "feature/a-prepared" });
+      expect(hasActiveBranchBoundTasksForProject("proj-1")).toBe(true);
+    });
+
+    it("hasActiveBranchBoundTasksForProject false when bound tasks are terminal (done)", () => {
+      const a = createTask({ projectId: "proj-1", title: "A", description: "" });
+      setTaskFields(a!.id, { branchName: "feature/a" });
+      updateTaskStatus(a!.id, "done");
+      expect(hasActiveBranchBoundTasksForProject("proj-1")).toBe(false);
+    });
+
     it("nextBacklogTaskByPosition skips paused tasks", () => {
       const a = createTask({ projectId: "proj-1", title: "A", description: "" });
       setTaskFields(a!.id, { paused: true });

packages/data/src/index.ts

@@ -1319,6 +1319,39 @@ export function countActivePipelineTasksForProject(projectId: string): number {
   return row?.cnt ?? 0;
 }
 
+/**
+ * True if the project has at least one in-flight task with a persisted
+ * `branchName`. Used by the auto-queue scheduler to keep parallel execution
+ * disabled even after `git.create_branches` is toggled off mid-pipeline —
+ * already-bound tasks still mutate the shared worktree on stage transitions
+ * via `restorePersistedBranch`, so concurrent stages would race on HEAD.
+ *
+ * Includes `backlog` so a queued task whose branch was prepared (e.g. via
+ * `accept_existing_plan`) does not let the scheduler open the parallel pool
+ * before its first stage starts.
+ */
+export function hasActiveBranchBoundTasksForProject(projectId: string): boolean {
+  const row = getDb()
+    .select({ cnt: count() })
+    .from(tasks)
+    .where(
+      and(
+        eq(tasks.projectId, projectId),
+        isNotNull(tasks.branchName),
+        inArray(tasks.status, [
+          "backlog",
+          "planning",
+          "plan_ready",
+          "implementing",
+          "review",
+          "blocked_external",
+        ]),
+      ),
+    )
+    .get();
+  return (row?.cnt ?? 0) > 0;
+}
+
 export function hasActiveLockedTaskForProject(projectId: string): boolean {
   const nowIso = new Date().toISOString();
   const row = getDb()