Fix overlay and task sync across worktrees

Author: ishashankmi

src/cli/commands/task.ts

@@ -112,6 +112,8 @@ interface RuntimePaths {
   eventsPath: string;
 }
 
+type PersistedTaskContractStatus = 'pending' | 'in_progress' | 'done';
+
 interface TaskFixAction {
   task_id: string;
   action: 'reset' | 'block' | 'migrate';
@@ -308,6 +310,26 @@ async function writeRuntimeState(runtimeFilePath: string, runtimeState: RuntimeS
   await writeJsonAtomic(runtimeFilePath, runtimeState);
 }
 
+async function syncTaskContractStatus(task: Pick<ParsedTask, 'task_file_path'>, status: PersistedTaskContractStatus): Promise<void> {
+  if (!task.task_file_path) {
+    return;
+  }
+
+  let currentContent: string;
+  try {
+    currentContent = await fs.readFile(task.task_file_path, 'utf-8');
+  } catch {
+    return;
+  }
+
+  const nextContent = currentContent.replace(/^status:\s*.+$/m, `status: ${status}`);
+  if (nextContent === currentContent) {
+    return;
+  }
+
+  await fs.writeFile(task.task_file_path, nextContent, 'utf-8');
+}
+
 function createEmptyRuntimeState(): RuntimeState {
   return {
     changes: {},
@@ -1927,6 +1949,7 @@ async function startTask(taskId: string, command = 'task start'): Promise<TaskCo
   }
 
   if (existingTaskState?.status === 'in_progress') {
+    await syncTaskContractStatus(matchedTask, 'in_progress');
     return {
       ok: true,
       data: {
@@ -1987,6 +2010,7 @@ async function startTask(taskId: string, command = 'task start'): Promise<TaskCo
   if (persistResult) {
     return persistResult;
   }
+  await syncTaskContractStatus(matchedTask, 'in_progress');
   await appendEvent(runtimePaths.eventsPath, 'task.started', taskRef, { command });
   if (matchedTask.change_id) {
     await syncChangeMetrics(matchedTask.change_id);
@@ -2047,6 +2071,7 @@ async function resumeTask(taskId: string, command = 'task resume'): Promise<Task
   }
 
   if (existingTaskState?.status === 'in_progress') {
+    await syncTaskContractStatus(matchedTask, 'in_progress');
     return {
       ok: true,
       data: {
@@ -2112,6 +2137,7 @@ async function resumeTask(taskId: string, command = 'task resume'): Promise<Task
   if (persistResult) {
     return persistResult;
   }
+  await syncTaskContractStatus(matchedTask, 'in_progress');
   await appendEvent(runtimePaths.eventsPath, 'task.resumed', taskRef, { command });
   if (matchedTask.change_id) {
     await syncChangeMetrics(matchedTask.change_id);
@@ -2323,6 +2349,7 @@ async function completeTask(taskId: string, command = 'task review complete'): P
   });
 
   await writeRuntimeState(runtimePaths.tasksPath, runtimeState);
+  await syncTaskContractStatus(matchedTask, 'done');
   await appendEvent(runtimePaths.eventsPath, 'task.approved', taskRef, { command, workflowPhase: 'review' });
   const overlay = await ensureOverlayFromMergedTasks({ command });
 
@@ -2415,6 +2442,7 @@ async function completeTasks(taskIds: string[], command = 'task review complete'
       updated_at: timestamp,
     };
     setRuntimeTaskState(runtimeState, taskRef, nextTaskState);
+    await syncTaskContractStatus(task, 'done');
 
     await appendEvent(runtimePaths.eventsPath, 'task.approved', taskRef, { command, workflowPhase: 'review' });
     completedTasks.push(buildRuntimeTaskSnapshot(task, getRuntimeTaskState(runtimeState, taskRef)!));
@@ -2483,6 +2511,7 @@ async function approveTask(taskId: string, command = 'task review approve'): Pro
   });
 
   await writeRuntimeState(runtimePaths.tasksPath, runtimeState);
+  await syncTaskContractStatus(matchedTask, 'done');
   await appendEvent(runtimePaths.eventsPath, 'task.approved', taskRef, { command, workflowPhase: 'review' });
   const overlay = await ensureOverlayFromMergedTasks({ command });
 
@@ -2694,6 +2723,7 @@ async function reopenTask(taskId: string, reason?: string, command = 'task revie
   if (persistResult) {
     return persistResult;
   }
+  await syncTaskContractStatus(mergedTask, 'in_progress');
   await appendEvent(runtimePaths.eventsPath, 'task.reopened', taskRef, {
     command,
     workflowPhase: 'review',
@@ -2753,6 +2783,9 @@ async function resetTask(taskId: string, command = 'task repair reset'): Promise
   deleteRuntimeTaskState(runtimeState, resolvedTaskRef);
 
   await writeRuntimeState(runtimePaths.tasksPath, runtimeState);
+  if (matchedTask) {
+    await syncTaskContractStatus(matchedTask, 'pending');
+  }
   await appendEvent(runtimePaths.eventsPath, 'task.reset', resolvedTaskRef, { command, workflowPhase: 'runtime' });
   const overlay = await ensureOverlayFromMergedTasks({ command });
 

src/cli/overlay-runtime.ts

@@ -19,6 +19,7 @@ import {
 import { loadChangeGraph } from './graph';
 import { getTaskRef, toQualifiedTaskId } from './task-identity';
 import { formatTitleFromSlug } from './commands/scaffold';
+import { readExecutionRootsState, type ExecutionRootsState } from './execution-roots';
 import { resolveProjectIdentity } from './project-identity';
 import { resolveSuperplanRoot, resolveWorkspaceRoot } from './workspace-root';
 
@@ -59,6 +60,20 @@ interface SetOverlayVisibilityOptions {
   workspacePath?: string;
 }
 
+interface OverlayRuntimeTaskEntry {
+  status?: string;
+}
+
+interface OverlayRuntimeChangeEntry {
+  active_task_ref?: string | null;
+  tasks?: Record<string, OverlayRuntimeTaskEntry>;
+}
+
+interface OverlayRuntimeStateFile {
+  changes?: Record<string, OverlayRuntimeChangeEntry>;
+  tasks?: Record<string, OverlayRuntimeTaskEntry>;
+}
+
 async function pathExists(targetPath: string): Promise<boolean> {
   try {
     await fs.access(targetPath);
@@ -81,6 +96,13 @@ async function readOverlaySnapshot(paths: OverlayRuntimePaths): Promise<OverlayS
   }
 }
 
+async function writeOverlaySnapshot(paths: OverlayRuntimePaths, snapshot: OverlaySnapshot): Promise<void> {
+  await fs.mkdir(paths.runtime_dir, { recursive: true });
+  const tempSnapshotPath = `${paths.snapshot_path}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  await fs.writeFile(tempSnapshotPath, JSON.stringify(snapshot, null, 2), 'utf-8');
+  await fs.rename(tempSnapshotPath, paths.snapshot_path);
+}
+
 function getPriorityRank(priority: TaskPriority): number {
   if (priority === 'high') {
     return 0;
@@ -202,6 +224,101 @@ function createAlertEvents(previousEvents: OverlayEvent[], alertKinds: OverlayEv
   return [...previousEvents, ...newEvents].slice(-MAX_OVERLAY_EVENTS);
 }
 
+function getOverlaySnapshotWorkspacePaths(workspacePath: string): string[] {
+  const workspaceRoot = resolveWorkspaceRoot(workspacePath);
+  const projectRoot = resolveProjectIdentity(workspacePath).project_root;
+  return [...new Set([workspaceRoot, projectRoot])];
+}
+
+async function readOverlayRuntimeTaskRefs(workspacePath: string): Promise<string[]> {
+  const tasksPath = path.join(resolveSuperplanRoot(workspacePath), 'runtime', 'tasks.json');
+  try {
+    const parsed = JSON.parse(await fs.readFile(tasksPath, 'utf-8')) as OverlayRuntimeStateFile;
+    if (parsed && typeof parsed === 'object' && parsed.changes && typeof parsed.changes === 'object') {
+      const refs = new Set<string>();
+      for (const [changeId, changeState] of Object.entries(parsed.changes)) {
+        const activeTaskRef = typeof changeState?.active_task_ref === 'string'
+          ? changeState.active_task_ref.trim()
+          : '';
+        if (activeTaskRef) {
+          refs.add(activeTaskRef);
+          continue;
+        }
+
+        if (!changeState?.tasks || typeof changeState.tasks !== 'object') {
+          continue;
+        }
+
+        for (const [taskId, taskState] of Object.entries(changeState.tasks)) {
+          if (taskState?.status === 'in_progress') {
+            refs.add(toQualifiedTaskId(changeId, taskId));
+          }
+        }
+      }
+
+      return [...refs].sort((left, right) => left.localeCompare(right));
+    }
+
+    if (parsed && typeof parsed === 'object' && parsed.tasks && typeof parsed.tasks === 'object') {
+      return Object.entries(parsed.tasks)
+        .filter(([taskRef, taskState]) => taskRef.includes('/') && taskState?.status === 'in_progress')
+        .map(([taskRef]) => taskRef)
+        .sort((left, right) => left.localeCompare(right));
+    }
+  } catch {}
+
+  return [];
+}
+
+function getAttachedChangeIdForWorkspace(
+  executionRootsState: ExecutionRootsState,
+  workspacePath: string,
+): string | null {
+  const workspaceRoot = resolveWorkspaceRoot(workspacePath);
+  return Object.values(executionRootsState.roots)
+    .find(record => record.path === workspaceRoot)
+    ?.attached_change_id ?? null;
+}
+
+function getActiveOverlayTaskForWorkspace(
+  board: OverlaySnapshot['board'],
+  options: {
+    activeTaskRefs: string[];
+    attachedChangeId: string | null;
+  },
+): OverlayTaskSummary | null {
+  const taskByRef = new Map<string, OverlayTaskSummary>();
+  for (const task of board.in_progress) {
+    if (task.task_ref) {
+      taskByRef.set(task.task_ref, task);
+    }
+  }
+
+  if (options.attachedChangeId) {
+    const attachedActiveTaskRef = options.activeTaskRefs.find(taskRef => taskRef.startsWith(`${options.attachedChangeId}/`));
+    if (attachedActiveTaskRef) {
+      const attachedActiveTask = taskByRef.get(attachedActiveTaskRef);
+      if (attachedActiveTask) {
+        return attachedActiveTask;
+      }
+    }
+
+    const attachedTask = board.in_progress.find(task => task.change_id === options.attachedChangeId);
+    if (attachedTask) {
+      return attachedTask;
+    }
+  }
+
+  for (const taskRef of options.activeTaskRefs) {
+    const activeTask = taskByRef.get(taskRef);
+    if (activeTask) {
+      return activeTask;
+    }
+  }
+
+  return board.in_progress[0] ?? null;
+}
+
 async function getTrackedChangeTaskIds(changeDir: string): Promise<string[]> {
   const tasksDir = path.join(changeDir, 'tasks');
   let taskEntries: Array<{ isFile(): boolean; name: string }> = [];
@@ -371,11 +488,9 @@ export async function refreshOverlaySnapshot(
   tasks: OverlayTaskSource[],
   options: RefreshOverlaySnapshotOptions = {},
 ): Promise<{ paths: OverlayRuntimePaths; snapshot: OverlaySnapshot }> {
-  const workspacePath = options.workspacePath ?? resolveWorkspaceRoot();
+  const workspacePath = resolveWorkspaceRoot(options.workspacePath ?? resolveWorkspaceRoot());
   const projectIdentity = resolveProjectIdentity(workspacePath);
-  const paths = getOverlayRuntimePaths(workspacePath);
   const timestamp = new Date().toISOString();
-  const previousSnapshot = await readOverlaySnapshot(paths);
   const sortedTasks = [...tasks].sort(sortTasks);
   const trackedChanges = await collectTrackedChanges(workspacePath, sortedTasks);
   const focusedChange = toFocusedChange(trackedChanges[0]);
@@ -389,31 +504,40 @@ export async function refreshOverlaySnapshot(
     blocked: sortedTasks.filter(task => task.status === 'blocked').map(toOverlayTaskSummary),
     needs_feedback: sortedTasks.filter(task => task.status === 'needs_feedback').map(toOverlayTaskSummary),
   };
+  const [executionRootsState, activeTaskRefs] = await Promise.all([
+    readExecutionRootsState(workspacePath),
+    readOverlayRuntimeTaskRefs(workspacePath),
+  ]);
+  const targetWorkspacePaths = getOverlaySnapshotWorkspacePaths(workspacePath);
+  const snapshots = await Promise.all(targetWorkspacePaths.map(async targetWorkspacePath => {
+    const paths = getOverlayRuntimePaths(targetWorkspacePath);
+    const previousSnapshot = await readOverlaySnapshot(paths);
+    const snapshot = createOverlaySnapshot({
+      project_id: projectIdentity.project_id,
+      project_name: path.basename(projectIdentity.project_root) || path.basename(targetWorkspacePath) || 'root',
+      project_path: projectIdentity.project_root,
+      workspace_path: targetWorkspacePath,
+      session_id: `workspace:${targetWorkspacePath}`,
+      updated_at: timestamp,
+      tracked_changes: trackedChanges.map(toOverlayTrackedChange),
+      focused_change: focusedChange,
+      active_task: getActiveOverlayTaskForWorkspace(board, {
+        activeTaskRefs,
+        attachedChangeId: getAttachedChangeIdForWorkspace(executionRootsState, targetWorkspacePath),
+      }),
+      board,
+      attention_state: attentionState,
+      events: createAlertEvents(previousSnapshot?.events ?? [], alertKinds, timestamp),
+    });
 
-  const snapshot = createOverlaySnapshot({
-    project_id: projectIdentity.project_id,
-    project_name: path.basename(projectIdentity.project_root) || path.basename(workspacePath) || 'root',
-    project_path: projectIdentity.project_root,
-    workspace_path: workspacePath,
-    session_id: `workspace:${workspacePath}`,
-    updated_at: timestamp,
-    tracked_changes: trackedChanges.map(toOverlayTrackedChange),
-    focused_change: focusedChange,
-    active_task: board.in_progress[0] ?? null,
-    board,
-    attention_state: attentionState,
-    events: createAlertEvents(previousSnapshot?.events ?? [], alertKinds, timestamp),
-  });
-
-  await fs.mkdir(paths.runtime_dir, { recursive: true });
-  const tempSnapshotPath = `${paths.snapshot_path}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-  await fs.writeFile(tempSnapshotPath, JSON.stringify(snapshot, null, 2), 'utf-8');
-  await fs.rename(tempSnapshotPath, paths.snapshot_path);
+    await writeOverlaySnapshot(paths, snapshot);
+    return {
+      paths,
+      snapshot,
+    };
+  }));
 
-  return {
-    paths,
-    snapshot,
-  };
+  return snapshots.find(item => item.snapshot.workspace_path === workspacePath) ?? snapshots[0];
 }
 
 export async function setOverlayVisibilityRequest(