fix(FN-080): ignore non-runnable queued overlap blockers

Fusion-Task-Id: FN-080

.changeset/fn-057-scheduler-deferral.md

@@ -0,0 +1,5 @@
+---
+"@fusion/engine": patch
+---
+
+Fix scheduler overlap deferral starvation by considering only runnable queued todo tasks as higher-priority overlap competitors. Dependency-blocked queued tasks now keep their unmet-dependency queue state without reserving overlapping files from ready work, while active in-progress and eligible in-review tasks continue to hold explicit file-scope leases. Dispatch logs now distinguish unmet dependencies, active file-scope lease blocking, and higher-priority runnable queued-task deferral.

packages/engine/src/__tests__/reliability-interactions/scheduler-overlap-priority-inversion.test.ts

@@ -78,7 +78,7 @@ describe("reliability interactions: FN-5325 scheduler overlap priority inversion
     (scheduler as any).running = true;
     await scheduler.schedule();
 
-    expect(store.logEntry).toHaveBeenCalledWith("FN-2", "queued — deferred for higher-priority queued task FN-1 (overlap)");
+    expect(store.logEntry).toHaveBeenCalledWith("FN-2", "queued — blocked by active file-scope lease FN-1 (column=in-progress)");
   });
 
   it("preserves FN-4969 fanout ordering and only defers when overlap exists", async () => {

packages/engine/src/__tests__/scheduler-overlap-starvation.test.ts

@@ -0,0 +1,263 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Scheduler } from "../scheduler.js";
+import type { Task, TaskStore } from "@fusion/core";
+
+function makeTask(overrides: Partial<Task> = {}): Task {
+  return {
+    id: "FN-001",
+    title: "task",
+    description: "",
+    column: "todo",
+    dependencies: [],
+    steps: [],
+    currentStep: 0,
+    log: [],
+    createdAt: "2026-01-01T00:00:00.000Z",
+    updatedAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
+  } as Task;
+}
+
+function createStore(tasks: Task[], scopes: Record<string, string[]>): TaskStore {
+  const updateTask = vi.fn(async (id: string, patch: Partial<Task>) => {
+    const task = tasks.find((candidate) => candidate.id === id);
+    if (task) Object.assign(task, patch);
+    return task as Task;
+  });
+  const moveTask = vi.fn(async (id: string, column: Task["column"]) => {
+    const task = tasks.find((candidate) => candidate.id === id);
+    if (task) task.column = column;
+    return task as Task;
+  });
+
+  return {
+    listTasks: vi.fn(async () => tasks),
+    getSettings: vi.fn(async () => ({ maxConcurrent: 10, maxWorktrees: 10, groupOverlappingFiles: true })),
+    parseFileScopeFromPrompt: vi.fn(async (id: string) => scopes[id] ?? []),
+    updateTask,
+    moveTask,
+    getTask: vi.fn(async (id: string) => tasks.find((task) => task.id === id) ?? null),
+    logEntry: vi.fn(async () => undefined),
+    getRootDir: vi.fn(() => "/tmp/project"),
+    getTasksDir: vi.fn(() => "/tmp/project/.fusion/tasks"),
+    on: vi.fn(),
+    off: vi.fn(),
+    recordRunAuditEvent: vi.fn(async () => undefined),
+  } as unknown as TaskStore;
+}
+
+describe("scheduler overlap starvation regression (FN-057)", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(Scheduler.prototype as any, "validateTaskFilesystem").mockResolvedValue({ valid: true });
+  });
+
+  it("does not let dependency-blocked queued overlap starve ready work", async () => {
+    const tasks = [
+      makeTask({ id: "FN-039", column: "in-progress", priority: "normal" }),
+      makeTask({
+        id: "FN-028",
+        column: "todo",
+        status: "queued",
+        priority: "urgent",
+        dependencies: ["FN-039"],
+        createdAt: "2026-01-01T00:00:00.000Z",
+      }),
+      makeTask({
+        id: "FN-030",
+        column: "todo",
+        priority: "normal",
+        createdAt: "2026-01-01T00:01:00.000Z",
+      }),
+    ];
+    const store = createStore(tasks, {
+      "FN-039": ["packages/core/src/store.ts"],
+      "FN-028": ["packages/engine/src/scheduler.ts"],
+      "FN-030": ["packages/engine/src/scheduler.ts"],
+    });
+
+    const scheduler = new Scheduler(store);
+    (scheduler as any).running = true;
+    await scheduler.schedule();
+
+    expect(store.updateTask).toHaveBeenCalledWith("FN-028", { status: "queued", blockedBy: "FN-039" });
+    expect(store.logEntry).toHaveBeenCalledWith("FN-028", "queued — unmet dependencies: FN-039");
+    expect(store.moveTask).toHaveBeenCalledWith("FN-030", "in-progress", expect.objectContaining({ allocateWorktree: expect.any(Function) }));
+    expect(store.updateTask).not.toHaveBeenCalledWith(
+      "FN-030",
+      expect.objectContaining({ status: "queued", overlapBlockedBy: "FN-028" }),
+    );
+    expect(store.logEntry).not.toHaveBeenCalledWith(
+      "FN-030",
+      "queued — deferred for higher-priority runnable queued task FN-028 (overlap)",
+    );
+  });
+
+
+  it("does not defer ready work behind queued overlap blocked by an active lease", async () => {
+    const tasks = [
+      makeTask({ id: "FN-039", column: "in-progress", priority: "normal" }),
+      makeTask({ id: "FN-028", column: "todo", status: "queued", priority: "urgent", createdAt: "2026-01-01T00:00:00.000Z" }),
+      makeTask({ id: "FN-030", column: "todo", priority: "normal", createdAt: "2026-01-01T00:01:00.000Z" }),
+    ];
+    const store = createStore(tasks, {
+      "FN-039": ["packages/engine/src/scheduler.ts"],
+      "FN-028": ["packages/engine/src/scheduler.ts", "packages/core/src/store.ts"],
+      "FN-030": ["packages/core/src/store.ts"],
+    });
+
+    const scheduler = new Scheduler(store);
+    (scheduler as any).running = true;
+    await scheduler.schedule();
+
+    expect(store.updateTask).toHaveBeenCalledWith(
+      "FN-028",
+      expect.objectContaining({ status: "queued", overlapBlockedBy: "FN-039" }),
+    );
+    expect(store.moveTask).toHaveBeenCalledWith("FN-030", "in-progress", expect.anything());
+    expect(store.logEntry).not.toHaveBeenCalledWith(
+      "FN-030",
+      "queued — deferred for higher-priority runnable queued task FN-028 (overlap)",
+    );
+  });
+
+  it("keeps active file-scope leases bounded while non-overlapping ready work proceeds", async () => {
+    const tasks = [
+      makeTask({ id: "FN-039", column: "in-progress", priority: "normal" }),
+      makeTask({ id: "FN-030", column: "todo", priority: "urgent" }),
+      makeTask({ id: "FN-031", column: "todo", priority: "normal", createdAt: "2026-01-01T00:01:00.000Z" }),
+    ];
+    const store = createStore(tasks, {
+      "FN-039": ["packages/engine/src/scheduler.ts"],
+      "FN-030": ["packages/engine/src/scheduler.ts"],
+      "FN-031": ["packages/core/src/store.ts"],
+    });
+
+    const scheduler = new Scheduler(store);
+    (scheduler as any).running = true;
+    await scheduler.schedule();
+
+    expect(store.updateTask).toHaveBeenCalledWith("FN-030", {
+      status: "queued",
+      blockedBy: null,
+      overlapBlockedBy: "FN-039",
+    });
+    expect(store.logEntry).toHaveBeenCalledWith(
+      "FN-030",
+      "queued — blocked by active file-scope lease FN-039 (column=in-progress)",
+    );
+    expect(store.moveTask).toHaveBeenCalledWith("FN-031", "in-progress", expect.objectContaining({ allocateWorktree: expect.any(Function) }));
+  });
+
+  it("does not defer FN-078-style ready work behind non-runnable queued overlaps", async () => {
+    const tasks = [
+      makeTask({ id: "FN-069", column: "todo", status: "queued", priority: "high" }),
+      makeTask({
+        id: "FN-070",
+        column: "todo",
+        status: "queued",
+        priority: "urgent",
+        dependencies: ["FN-069"],
+        createdAt: "2026-01-01T00:00:00.000Z",
+      }),
+      makeTask({
+        id: "FN-045",
+        column: "todo",
+        status: "queued",
+        priority: "high",
+        overlapBlockedBy: "FN-033",
+        createdAt: "2026-01-01T00:01:00.000Z",
+      }),
+      makeTask({ id: "FN-033", column: "in-progress", status: "in-progress", priority: "normal" }),
+      makeTask({ id: "FN-078", column: "todo", priority: "normal", createdAt: "2026-01-01T00:02:00.000Z" }),
+    ];
+    const store = createStore(tasks, {
+      "FN-033": ["packages/atlas/README.md"],
+      "FN-045": ["packages/atlas/README.md"],
+      "FN-070": ["packages/atlas/notes.md"],
+      "FN-078": ["packages/atlas/notes.md"],
+    });
+
+    const scheduler = new Scheduler(store);
+    (scheduler as any).running = true;
+    await scheduler.schedule();
+
+    expect(store.updateTask).toHaveBeenCalledWith("FN-070", { status: "queued", blockedBy: "FN-069" });
+    expect(store.logEntry).toHaveBeenCalledWith("FN-070", "queued — unmet dependencies: FN-069");
+    expect(store.updateTask).toHaveBeenCalledWith(
+      "FN-045",
+      expect.objectContaining({ status: "queued", overlapBlockedBy: "FN-033" }),
+    );
+    expect(store.logEntry).toHaveBeenCalledWith(
+      "FN-045",
+      "queued — blocked by active file-scope lease FN-033 (column=in-progress)",
+    );
+    expect(store.moveTask).toHaveBeenCalledWith("FN-078", "in-progress", expect.anything());
+    expect(store.logEntry).not.toHaveBeenCalledWith(
+      "FN-078",
+      "queued — deferred for higher-priority runnable queued task FN-070 (overlap)",
+    );
+    expect(store.logEntry).not.toHaveBeenCalledWith(
+      "FN-078",
+      "queued — deferred for higher-priority runnable queued task FN-045 (overlap)",
+    );
+  });
+
+
+  it("does not use queued candidates that become non-runnable after earlier dispatch in the same pass", async () => {
+    const tasks = [
+      makeTask({ id: "FN-033", column: "todo", priority: "urgent", createdAt: "2026-01-01T00:00:00.000Z" }),
+      makeTask({ id: "FN-045", column: "todo", status: "queued", priority: "high", createdAt: "2026-01-01T00:01:00.000Z" }),
+      makeTask({ id: "FN-078", column: "todo", priority: "normal", createdAt: "2026-01-01T00:02:00.000Z" }),
+    ];
+    const store = createStore(tasks, {
+      "FN-033": ["packages/atlas/docs/README.md"],
+      "FN-045": ["packages/atlas/docs/README.md", "packages/atlas/notes/today.md"],
+      "FN-078": ["packages/atlas/notes/today.md"],
+    });
+
+    const scheduler = new Scheduler(store);
+    (scheduler as any).running = true;
+    await scheduler.schedule();
+
+    expect(store.moveTask).toHaveBeenCalledWith("FN-033", "in-progress", expect.anything());
+    expect(store.updateTask).toHaveBeenCalledWith(
+      "FN-045",
+      expect.objectContaining({ status: "queued", overlapBlockedBy: "FN-033" }),
+    );
+    expect(store.logEntry).toHaveBeenCalledWith(
+      "FN-045",
+      "queued — blocked by active file-scope lease FN-033 (column=in-progress)",
+    );
+    expect(store.moveTask).toHaveBeenCalledWith("FN-078", "in-progress", expect.anything());
+    expect(store.logEntry).not.toHaveBeenCalledWith(
+      "FN-078",
+      "queued — deferred for higher-priority runnable queued task FN-045 (overlap)",
+    );
+  });
+
+  it("clears stale overlapBlockedBy when no runnable queued overlap blocker exists", async () => {
+    const tasks = [
+      makeTask({ id: "FN-100", column: "todo", priority: "normal", overlapBlockedBy: "FN-070" }),
+      makeTask({ id: "FN-070", column: "todo", status: "queued", priority: "urgent", dependencies: ["FN-069"] }),
+      makeTask({ id: "FN-069", column: "todo", status: "queued", priority: "high" }),
+    ];
+    const store = createStore(tasks, {
+      "FN-100": ["packages/engine/src/scheduler.ts"],
+      "FN-070": ["packages/engine/src/scheduler.ts"],
+      "FN-069": ["packages/core/src/store.ts"],
+    });
+
+    const scheduler = new Scheduler(store);
+    (scheduler as any).running = true;
+    await scheduler.schedule();
+
+    expect(store.updateTask).toHaveBeenCalledWith("FN-100", { overlapBlockedBy: null });
+    expect(store.moveTask).toHaveBeenCalledWith("FN-100", "in-progress", expect.anything());
+    expect(store.logEntry).not.toHaveBeenCalledWith(
+      "FN-100",
+      "queued — deferred for higher-priority runnable queued task FN-070 (overlap)",
+    );
+  });
+
+});

packages/engine/src/scheduler.ts

@@ -126,6 +126,34 @@ export interface QueuedOverlapCandidate {
   scope: string[];
 }
 
+export function getUnmetSchedulingDependencies(task: Task, tasks: Task[]): string[] {
+  return task.dependencies.filter((depId) => {
+    const dep = tasks.find((candidate) => candidate.id === depId);
+    return dep && dep.column !== "done" && dep.column !== "in-review" && dep.column !== "archived";
+  });
+}
+
+export function isRunnableQueuedOverlapCandidate(
+  task: Task,
+  tasks: Task[],
+  now = Date.now(),
+  activeScopes?: Map<string, string[]>,
+  scope: string[] = [],
+): boolean {
+  if (task.column !== "todo" || task.status !== "queued") return false;
+  if (task.paused || task.userPaused) return false;
+  if (task.nextRecoveryAt && new Date(task.nextRecoveryAt).getTime() > now) return false;
+  if (getUnmetSchedulingDependencies(task, tasks).length > 0) return false;
+  if (!activeScopes || activeScopes.size === 0) return true;
+
+  if (scope.length === 0) return true;
+  for (const activeScope of activeScopes.values()) {
+    if (!activeScope.length) continue;
+    if (pathsOverlap(scope, activeScope)) return false;
+  }
+  return true;
+}
+
 export function findHigherPriorityQueuedOverlap(
   candidate: QueuedOverlapCandidate,
   queuedScopes: QueuedOverlapCandidate[],
@@ -1097,29 +1125,30 @@ export class Scheduler {
        * subsequent todo tasks in the same pass also see them.
        */
       const activeScopes = new Map<string, string[]>();
+      const activeScopeColumns = new Map<string, Task["column"]>();
+      const setActiveScopeLease = (taskId: string, scope: string[], column: Task["column"]): void => {
+        activeScopes.set(taskId, scope);
+        activeScopeColumns.set(taskId, column);
+      };
       const inversionEmitted = new Set<string>();
       const queuedHigherPriorityScopes: QueuedOverlapCandidate[] = [];
+      const queuedHigherPriorityTaskById = new Map<string, Task>();
+      const overlapIgnorePaths = settings.overlapIgnorePaths ?? [];
+      const filteredScopeByTaskId = new Map<string, string[]>();
+      const getFilteredFileScope = async (taskId: string): Promise<string[]> => {
+        const cached = filteredScopeByTaskId.get(taskId);
+        if (cached) return cached;
+        const scope = await this.store.parseFileScopeFromPrompt(taskId);
+        const filteredScope = filterPathsByIgnoreList(scope, overlapIgnorePaths);
+        filteredScopeByTaskId.set(taskId, filteredScope);
+        return filteredScope;
+      };
       if (settings.groupOverlappingFiles) {
-        const overlapIgnorePaths = settings.overlapIgnorePaths ?? [];
         // In-progress tasks
         for (const t of inProgress) {
-          const scope = await this.store.parseFileScopeFromPrompt(t.id);
-          const filteredScope = filterPathsByIgnoreList(scope, overlapIgnorePaths);
-          if (filteredScope.length > 0) activeScopes.set(t.id, filteredScope);
+          const filteredScope = await getFilteredFileScope(t.id);
+          if (filteredScope.length > 0) setActiveScopeLease(t.id, filteredScope, "in-progress");
         }
-        for (const t of todo) {
-          if (t.status !== "queued" || t.paused || t.userPaused) continue;
-          const scope = await this.store.parseFileScopeFromPrompt(t.id);
-          const filteredScope = filterPathsByIgnoreList(scope, overlapIgnorePaths);
-          if (filteredScope.length === 0) continue;
-          queuedHigherPriorityScopes.push({
-            id: t.id,
-            priority: t.priority,
-            createdAt: t.createdAt,
-            scope: filteredScope,
-          });
-        }
-
         // Only live in-review tasks with a worktree belong in activeScopes.
         // Paused in-review tasks (e.g., failed-merge tasks awaiting human triage) cannot
         // make progress, so they must not contribute to overlap blockers; including them
@@ -1133,9 +1162,21 @@ export class Scheduler {
           (t) => t.column === "in-review" && Boolean(t.worktree) && !t.paused && t.status !== "failed",
         );
         for (const t of inReviewWithWorktree) {
-          const scope = await this.store.parseFileScopeFromPrompt(t.id);
-          const filteredScope = filterPathsByIgnoreList(scope, overlapIgnorePaths);
-          if (filteredScope.length > 0) activeScopes.set(t.id, filteredScope);
+          const filteredScope = await getFilteredFileScope(t.id);
+          if (filteredScope.length > 0) setActiveScopeLease(t.id, filteredScope, "in-review");
+        }
+
+        for (const t of todo) {
+          const filteredScope = await getFilteredFileScope(t.id);
+          if (filteredScope.length === 0) continue;
+          if (!isRunnableQueuedOverlapCandidate(t, tasks, now, activeScopes, filteredScope)) continue;
+          queuedHigherPriorityScopes.push({
+            id: t.id,
+            priority: t.priority,
+            createdAt: t.createdAt,
+            scope: filteredScope,
+          });
+          queuedHigherPriorityTaskById.set(t.id, t);
         }
       }
 
@@ -1162,10 +1203,7 @@ export class Scheduler {
         }
 
         // Check all deps are satisfied (done, in-review, or archived)
-        const unmetDeps = task.dependencies.filter((depId) => {
-          const dep = tasks.find((t) => t.id === depId);
-          return dep && dep.column !== "done" && dep.column !== "in-review" && dep.column !== "archived";
-        });
+        const unmetDeps = getUnmetSchedulingDependencies(task, tasks);
 
         if (unmetDeps.length > 0) {
           await this.store.updateTask(task.id, {
@@ -1212,11 +1250,7 @@ export class Scheduler {
 
         // Check file scope overlap when enabled
         if (settings.groupOverlappingFiles) {
-          const overlapIgnorePaths = settings.overlapIgnorePaths ?? [];
-          const taskScope = filterPathsByIgnoreList(
-            await this.store.parseFileScopeFromPrompt(task.id),
-            overlapIgnorePaths,
-          );
+          const taskScope = await getFilteredFileScope(task.id);
           if (taskScope.length > 0) {
             const activeScopeEntries = Array.from(activeScopes.entries()).sort(([aId], [bId]) => aId.localeCompare(bId));
             const overlapBlockerId = task.overlapBlockedBy || task.blockedBy;
@@ -1236,6 +1270,12 @@ export class Scheduler {
               ? overlapBlockerId
               : activeScopeEntries.find(([, ipScope]) => this.pathsOverlap(taskScope, ipScope))?.[0] ?? null;
 
+            const runnableQueuedHigherPriorityScopes = queuedHigherPriorityScopes.filter((queuedCandidate) => {
+              const queuedTask = queuedHigherPriorityTaskById.get(queuedCandidate.id);
+              if (!queuedTask) return false;
+              return isRunnableQueuedOverlapCandidate(queuedTask, tasks, now, activeScopes, queuedCandidate.scope);
+            });
+
             const higherPriorityQueuedOverlap = findHigherPriorityQueuedOverlap(
               {
                 id: task.id,
@@ -1243,7 +1283,7 @@ export class Scheduler {
                 createdAt: task.createdAt,
                 scope: taskScope,
               },
-              queuedHigherPriorityScopes,
+              runnableQueuedHigherPriorityScopes,
               this.pathsOverlap.bind(this),
             );
 
@@ -1263,7 +1303,7 @@ export class Scheduler {
               await this.rollbackRunningAgentsForQueuedTodoTask(task.id);
               await this.logDispatchQueuedReason(
                 task.id,
-                `queued — deferred for higher-priority queued task ${higherPriorityQueuedOverlap.id} (overlap)`,
+                `queued — deferred for higher-priority runnable queued task ${higherPriorityQueuedOverlap.id} (overlap)`,
               );
               continue;
             }
@@ -1305,7 +1345,7 @@ export class Scheduler {
                       blockerId: overlapBlockerTask.id,
                       blockerPriority: overlapBlockerTask.priority ?? null,
                       blockerCreatedAt: overlapBlockerTask.createdAt ?? null,
-                      blockerColumn: overlapBlockerTask.column,
+                      blockerColumn: activeScopeColumns.get(overlappingTaskId) ?? overlapBlockerTask.column,
                       source: "scheduler.overlap-priority-inversion",
                     },
                   });
@@ -1317,7 +1357,11 @@ export class Scheduler {
               }
 
               await this.rollbackRunningAgentsForQueuedTodoTask(task.id);
-              await this.logDispatchQueuedReason(task.id, `queued — file scope overlap with ${overlappingTaskId}`);
+              const activeLeaseColumn = activeScopeColumns.get(overlappingTaskId) ?? overlapBlockerTask?.column ?? "unknown";
+              await this.logDispatchQueuedReason(
+                task.id,
+                `queued — blocked by active file-scope lease ${overlappingTaskId} (column=${activeLeaseColumn})`,
+              );
               continue;
             }
 
@@ -1591,11 +1635,8 @@ export class Scheduler {
 
         // Track newly started task's file scope for overlap with remaining todo tasks
         if (settings.groupOverlappingFiles) {
-          const scope = filterPathsByIgnoreList(
-            await this.store.parseFileScopeFromPrompt(task.id),
-            settings.overlapIgnorePaths,
-          );
-          if (scope.length > 0) activeScopes.set(task.id, scope);
+          const scope = await getFilteredFileScope(task.id);
+          if (scope.length > 0) setActiveScopeLease(task.id, scope, "in-progress");
         }
       }
 

packages/engine/src/self-healing.ts

@@ -3731,7 +3731,7 @@ export class SelfHealingManager {
           const dep = taskById.get(depId);
           // listTasks excludes soft-deleted rows, so missing dependency IDs are
           // treated as resolved here by design.
-          return dep && dep.column !== "done" && dep.column !== "in-review" && dep.column !== "archived";
+          return dep && !dep.deletedAt && dep.column !== "done" && dep.column !== "in-review" && dep.column !== "archived";
         });
         const overlapBlocker = task.overlapBlockedBy ? taskById.get(task.overlapBlockedBy) : undefined;
         const hasActiveOverlapBlocker = Boolean(
@@ -3762,6 +3762,9 @@ export class SelfHealingManager {
               reasonCode = "missing-blocker";
               reason = `blocker ${blockerId} missing`;
             }
+          } else if (blocker.deletedAt) {
+            reasonCode = "soft-deleted-blocker";
+            reason = `blocker ${blockerId} soft-deleted at ${blocker.deletedAt}`;
           } else if (blocker.column === "done") {
             reasonCode = "blocker-done";
             reason = `blocker ${blockerId} is done`;