Merge branch 'claudedo/5c80a0aba5d9468a96cf809fc7a6e7a1'

src/ClaudeDo.Worker/External/BatchMcpTools.cs

@@ -217,7 +217,7 @@ public sealed class BatchMcpTools
             {
                 var created = await _svc.AddTask(
                     listId, item.Title, item.Description, createdBy,
-                    queueImmediately, item.Model, cancellationToken);
+                    queueImmediately, item.Model, cancellationToken: cancellationToken);
                 results.Add(new BatchAddTaskResult(i, item.Title, true, created.Task, created.PossibleDuplicates, null));
             }
             catch (OperationCanceledException) { throw; }

src/ClaudeDo.Worker/External/ExternalMcpService.cs

@@ -51,7 +51,14 @@ public sealed record TaskDto(
     // field. Lets a caller triage without pulling get_task_log's raw NDJSON.
     string? FailureReason = null,
     int? FailureTurnsUsed = null,
-    int? FailureMaxTurns = null);
+    int? FailureMaxTurns = null,
+    // A user/MCP-declared predecessor (set via add_task/update_task), distinct from the
+    // planning chain's own internal BlockedByTaskId link.
+    string? DependsOnTaskId = null,
+    // True only while Status is Queued and the picker will not claim this task yet -- either a
+    // planning-chain predecessor or DependsOnTaskId hasn't reached Done. See BlockedReason.
+    bool Blocked = false,
+    string? BlockedReason = null);
 
 // Lean counterpart to TaskDto for writing/status-changing tools: echoes back what changed
 // without re-sending Description/Result, which the caller just sent or already has.
@@ -65,7 +72,10 @@ public sealed record TaskRefDto(
     int RoadblockCount = 0,
     string? FailureReason = null,
     int? FailureTurnsUsed = null,
-    int? FailureMaxTurns = null);
+    int? FailureMaxTurns = null,
+    string? DependsOnTaskId = null,
+    bool Blocked = false,
+    string? BlockedReason = null);
 
 // tasks is populated when includeDescription=false (the default): lean references, no
 // Description/Result. tasksFull is populated when includeDescription=true: full tasks incl.
@@ -119,11 +129,18 @@ public sealed record ResolveConflictHunkResultDto(
 // of its output in VerifyOutputTail.
 public sealed record MergePreviewToolDto(
     string Status, IReadOnlyList<string> ConflictFiles, int ChangedFileCount, int Behind, bool IsEmpty = false,
-    int? VerifyExitCode = null, long? VerifyDurationMs = null, string? VerifyOutputTail = null);
+    int? VerifyExitCode = null, long? VerifyDurationMs = null, string? VerifyOutputTail = null,
+    // Files this branch touches that the target branch ALSO touched since the branch's fork
+    // point -- an honest staleness signal `behind` alone can't give (a branch can be far behind
+    // yet touch nothing the target changed, or close behind yet collide on the one file that
+    // matters). Empty for a worktree-less handler task, which commits straight onto the list's
+    // working dir and has no fork point to compare against.
+    IReadOnlyList<string>? StaleFiles = null);
 
 public sealed record MergePreviewSetEntryDto(
     string TaskId, string Status, IReadOnlyList<string> ConflictFiles, int ChangedFileCount, int Behind, string? Error, bool IsEmpty = false,
-    int? VerifyExitCode = null, long? VerifyDurationMs = null, string? VerifyOutputTail = null);
+    int? VerifyExitCode = null, long? VerifyDurationMs = null, string? VerifyOutputTail = null,
+    IReadOnlyList<string>? StaleFiles = null);
 
 public sealed record FileOverlapDto(string File, IReadOnlyList<string> TaskIds);
 
@@ -234,9 +251,59 @@ public sealed class ExternalMcpService
             query = query.Where(t => t.Status == statusFilter);
 
         var filtered = query.ToList();
+        var blocked = await ComputeBlockedInfoAsync(filtered, cancellationToken);
         return includeDescription
-            ? new ListTasksResult(true, null, filtered.Select(ToDto).ToList())
-            : new ListTasksResult(false, filtered.Select(ToRefDto).ToList(), null);
+            ? new ListTasksResult(true, null, filtered.Select(t => ToDto(t, blocked[t.Id].Blocked, blocked[t.Id].Reason)).ToList())
+            : new ListTasksResult(false, filtered.Select(t => ToRefDto(t, blocked[t.Id].Blocked, blocked[t.Id].Reason)).ToList(), null);
+    }
+
+    // Batch-resolves, for each task, whether the picker is currently skipping it (Queued with
+    // either a planning-chain BlockedByTaskId or an unmet DependsOnTaskId) and why. Only Queued
+    // tasks can be blocked -- once a task has run, or hasn't been queued yet, blocking is moot.
+    private async Task<Dictionary<string, (bool Blocked, string? Reason)>> ComputeBlockedInfoAsync(
+        IReadOnlyList<TaskEntity> tasks, CancellationToken ct)
+    {
+        var dependencyIds = tasks
+            .Where(t => t.Status == TaskStatus.Queued && t.BlockedByTaskId is null && t.DependsOnTaskId is not null)
+            .Select(t => t.DependsOnTaskId!)
+            .Distinct()
+            .ToList();
+
+        var dependencyStatuses = new Dictionary<string, TaskStatus>();
+        if (dependencyIds.Count > 0)
+        {
+            await using var ctx = await _dbFactory.CreateDbContextAsync(ct);
+            dependencyStatuses = await ctx.Tasks.AsNoTracking()
+                .Where(t => dependencyIds.Contains(t.Id))
+                .Select(t => new { t.Id, t.Status })
+                .ToDictionaryAsync(t => t.Id, t => t.Status, ct);
+        }
+
+        var result = new Dictionary<string, (bool Blocked, string? Reason)>();
+        foreach (var t in tasks)
+        {
+            if (t.Status != TaskStatus.Queued)
+            {
+                result[t.Id] = (false, null);
+            }
+            else if (t.BlockedByTaskId is not null)
+            {
+                result[t.Id] = (true, $"Blocked by planning-chain predecessor {t.BlockedByTaskId}.");
+            }
+            else if (t.DependsOnTaskId is not null)
+            {
+                var known = dependencyStatuses.TryGetValue(t.DependsOnTaskId, out var depStatus);
+                result[t.Id] = known && depStatus == TaskStatus.Done
+                    ? (false, null)
+                    : (true, $"Blocked: depends on task {t.DependsOnTaskId} (status: " +
+                             (known ? depStatus.ToString() : "not found") + ").");
+            }
+            else
+            {
+                result[t.Id] = (false, null);
+            }
+        }
+        return result;
     }
 
     [McpServerTool, Description(
@@ -251,7 +318,8 @@ public sealed class ExternalMcpService
     {
         var task = await _tasks.GetByIdAsync(taskId, cancellationToken)
             ?? throw new InvalidOperationException($"Task {taskId} not found.");
-        return ToDto(task);
+        var blocked = await ComputeBlockedInfoAsync([task], cancellationToken);
+        return ToDto(task, blocked[task.Id].Blocked, blocked[task.Id].Reason);
     }
 
     // Lean counterpart to GetTask, used internally by BatchGetTasks' default (includeDescription=false)
@@ -260,7 +328,8 @@ public sealed class ExternalMcpService
     {
         var task = await _tasks.GetByIdAsync(taskId, cancellationToken)
             ?? throw new InvalidOperationException($"Task {taskId} not found.");
-        return ToRefDto(task);
+        var blocked = await ComputeBlockedInfoAsync([task], cancellationToken);
+        return ToRefDto(task, blocked[task.Id].Blocked, blocked[task.Id].Reason);
     }
 
     [McpServerTool, Description(
@@ -278,6 +347,11 @@ public sealed class ExternalMcpService
                      "for normal coding, 'opus' only for complex or cross-cutting work. null inherits the " +
                      "list/global default (normally sonnet).")]
         string? model = null,
+        [Description("Id of a task that must reach Done (i.e. be merged) before the picker will claim this one, " +
+                     "even once queued. Rejected if it doesn't exist, is this task's own id, or would create a " +
+                     "dependency cycle. If that predecessor instead ends up Failed or Cancelled, this task simply " +
+                     "stays blocked rather than starving silently -- check get_task/list_tasks' blocked field.")]
+        string? dependsOnTaskId = null,
         CancellationToken cancellationToken = default)
     {
         if (string.IsNullOrWhiteSpace(listId))
@@ -306,6 +380,14 @@ public sealed class ExternalMcpService
         };
         await _tasks.AddAsync(entity, cancellationToken);
 
+        if (dependsOnTaskId is not null)
+        {
+            var dependsResult = await _state.SetDependsOnAsync(entity.Id, dependsOnTaskId, cancellationToken);
+            if (!dependsResult.Ok)
+                throw new InvalidOperationException(dependsResult.Reason ?? "Cannot set dependsOnTaskId.");
+            entity.DependsOnTaskId = dependsOnTaskId;
+        }
+
         if (queueImmediately)
         {
             var enqueue = await _state.EnqueueAsync(entity.Id, cancellationToken);
@@ -315,7 +397,8 @@ public sealed class ExternalMcpService
         }
 
         await _broadcaster.TaskUpdated(entity.Id);
-        return new AddTaskResult(ToRefDto(entity), possibleDuplicates);
+        var blocked = await ComputeBlockedInfoAsync([entity], cancellationToken);
+        return new AddTaskResult(ToRefDto(entity, blocked[entity.Id].Blocked, blocked[entity.Id].Reason), possibleDuplicates);
     }
 
     // Non-terminal: a task still open enough that a new, similarly-titled task might be a duplicate
@@ -389,13 +472,17 @@ public sealed class ExternalMcpService
     }
 
     [McpServerTool, Description(
-        "Update an existing task's title, description, and/or commit type. Pass null to leave a field unchanged." +
-        McpToolDocs.NotWhileRunning + McpToolDocs.LeanTaskRef)]
+        "Update an existing task's title, description, commit type, and/or dependsOn link. Pass null to leave a " +
+        "field unchanged." + McpToolDocs.NotWhileRunning + McpToolDocs.LeanTaskRef)]
     public async Task<TaskRefDto> UpdateTask(
         string taskId,
         string? title = null,
         string? description = null,
         string? commitType = null,
+        [Description("Id of a task that must reach Done before the picker will claim this one. Pass an empty " +
+                     "string to clear an existing link; null leaves it unchanged. Rejected if it doesn't exist, " +
+                     "is this task's own id, or would create a dependency cycle.")]
+        string? dependsOnTaskId = null,
         CancellationToken cancellationToken = default)
     {
         var task = await _tasks.GetByIdAsync(taskId, cancellationToken)
@@ -408,9 +495,17 @@ public sealed class ExternalMcpService
         if (commitType is not null) task.CommitType = commitType;
         await _tasks.UpdateAsync(task, cancellationToken);
 
+        if (dependsOnTaskId is not null)
+        {
+            var dependsResult = await _state.SetDependsOnAsync(taskId, dependsOnTaskId.NullIfBlank(), cancellationToken);
+            if (!dependsResult.Ok)
+                throw new InvalidOperationException(dependsResult.Reason ?? "Cannot set dependsOnTaskId.");
+        }
+
         var reload = (await _tasks.GetByIdAsync(taskId, cancellationToken))!;
         await _broadcaster.TaskUpdated(taskId);
-        return ToRefDto(reload);
+        var blocked = await ComputeBlockedInfoAsync([reload], cancellationToken);
+        return ToRefDto(reload, blocked[reload.Id].Blocked, blocked[reload.Id].Reason);
     }
 
     [McpServerTool, Description(
@@ -1079,17 +1174,21 @@ public sealed class ExternalMcpService
         "verifyExitCode 0 means it built clean, non-zero or -1 (timeout/failed to start) means it doesn't, with the " +
         "tail of its output in verifyOutputTail; verifyExitCode stays null when no verify command is configured. " +
         "isEmpty=true means the task's review range contributed nothing; check that flag rather than reading a " +
-        "small changedFileCount as empty. Throws if the task has neither an active worktree nor a handler commit " +
-        "range, or the list's working directory is missing from disk.")]
+        "small changedFileCount as empty. staleFiles lists files this branch touches that the target branch ALSO " +
+        "changed since this branch's fork point — a more honest staleness signal than `behind` alone, since a " +
+        "branch can be far behind yet touch nothing the target changed, or barely behind yet collide on the one " +
+        "file that matters (always empty for a worktree-less handler task, which has no fork point). Throws if the " +
+        "task has neither an active worktree nor a handler commit range, or the list's working directory is missing " +
+        "from disk.")]
     public async Task<MergePreviewToolDto> PreviewMerge(
         string taskId,
         [Description("Branch to preview against; defaults to the repo's current branch.")]
         string? targetBranch = null,
         CancellationToken cancellationToken = default)
     {
-        var (preview, behind, _, isEmpty) = await PreviewMergeCoreAsync(taskId, targetBranch, runVerify: true, cancellationToken);
+        var (preview, behind, _, isEmpty, staleFiles) = await PreviewMergeCoreAsync(taskId, targetBranch, runVerify: true, cancellationToken);
         return new MergePreviewToolDto(preview.Status, preview.ConflictFiles, preview.ChangedFileCount, behind, isEmpty,
-            preview.VerifyExitCode, preview.VerifyDurationMs, preview.VerifyOutputTail);
+            preview.VerifyExitCode, preview.VerifyDurationMs, preview.VerifyOutputTail, staleFiles);
     }
 
     [McpServerTool, Description(
@@ -1124,10 +1223,10 @@ public sealed class ExternalMcpService
         {
             try
             {
-                var (preview, behind, changedFiles, isEmpty) = await PreviewMergeCoreAsync(taskId, targetBranch, runVerify, cancellationToken);
+                var (preview, behind, changedFiles, isEmpty, staleFiles) = await PreviewMergeCoreAsync(taskId, targetBranch, runVerify, cancellationToken);
                 entries.Add(new MergePreviewSetEntryDto(
                     taskId, preview.Status, preview.ConflictFiles, preview.ChangedFileCount, behind, null, isEmpty,
-                    preview.VerifyExitCode, preview.VerifyDurationMs, preview.VerifyOutputTail));
+                    preview.VerifyExitCode, preview.VerifyDurationMs, preview.VerifyOutputTail, staleFiles));
                 filesByTask[taskId] = changedFiles;
             }
             catch (InvalidOperationException ex)
@@ -1184,7 +1283,7 @@ public sealed class ExternalMcpService
     // (its commits already sit on the list's working dir) — falls back to the fixed
     // HandlerBaseCommit..HandlerHeadCommit range, reporting a synthetic "clean" preview of that
     // range's own diff-stat instead of throwing "has no worktree".
-    private async Task<(MergePreviewResult Preview, int Behind, IReadOnlyList<string> ChangedFiles, bool IsEmpty)> PreviewMergeCoreAsync(
+    private async Task<(MergePreviewResult Preview, int Behind, IReadOnlyList<string> ChangedFiles, bool IsEmpty, IReadOnlyList<string> StaleFiles)> PreviewMergeCoreAsync(
         string taskId, string? targetBranch, bool runVerify, CancellationToken ct)
     {
         using var ctx = _dbFactory.CreateDbContext();
@@ -1216,7 +1315,16 @@ public sealed class ExternalMcpService
                 ? ParseDiffStatFileNames(await _git.DiffStatAsync(wt.Path, wt.BaseCommit, "HEAD", ct: ct))
                 : Array.Empty<string>();
 
-            return (preview, behind, changedFiles, changedFiles.Count == 0);
+            // What the target itself picked up since this branch's fork point, so `behind`
+            // (a commit count) doesn't have to stand in for "does this collide" -- a branch can
+            // be far behind but touch nothing the target changed, or close behind and collide on
+            // the one file that matters.
+            var targetChangedSinceFork = await _git.GetChangedFileNamesAsync(list.WorkingDir, wt.BaseCommit, target, ct);
+            var staleFiles = changedFiles
+                .Intersect(targetChangedSinceFork, StringComparer.OrdinalIgnoreCase)
+                .ToList();
+
+            return (preview, behind, changedFiles, changedFiles.Count == 0, staleFiles);
         }
 
         if (task.HandlerBaseCommit is { Length: > 0 } handlerBase && task.HandlerHeadCommit is { Length: > 0 } handlerHead)
@@ -1230,7 +1338,10 @@ public sealed class ExternalMcpService
                 : ParseDiffStatFileNames(await _git.DiffStatAsync(list.WorkingDir, handlerBase, handlerHead, ct: ct));
 
             var preview = new MergePreviewResult(TaskMergeService.PreviewClean, Array.Empty<string>(), changedFiles.Count);
-            return (preview, 0, changedFiles, isEmpty);
+            // No fork point to diff against: a handler task commits straight onto the list's
+            // working dir instead of a branch, so there is nothing else that could have "changed
+            // in the target since the fork".
+            return (preview, 0, changedFiles, isEmpty, Array.Empty<string>());
         }
 
         throw new InvalidOperationException($"Task {taskId} has no worktree.");
@@ -1497,7 +1608,7 @@ public sealed class ExternalMcpService
         return files;
     }
 
-    private static TaskDto ToDto(TaskEntity t) => new(
+    private static TaskDto ToDto(TaskEntity t, bool blocked = false, string? blockedReason = null) => new(
         t.Id,
         t.ListId,
         t.Title,
@@ -1513,9 +1624,12 @@ public sealed class ExternalMcpService
         t.RoadblockCount,
         FailureReasonOf(t),
         t.Status == TaskStatus.Failed ? t.FailureTurnsUsed : null,
-        t.Status == TaskStatus.Failed ? t.FailureMaxTurns : null);
+        t.Status == TaskStatus.Failed ? t.FailureMaxTurns : null,
+        t.DependsOnTaskId,
+        blocked,
+        blockedReason);
 
-    private static TaskRefDto ToRefDto(TaskEntity t) => new(
+    private static TaskRefDto ToRefDto(TaskEntity t, bool blocked = false, string? blockedReason = null) => new(
         t.Id,
         t.ListId,
         t.Title,
@@ -1525,7 +1639,10 @@ public sealed class ExternalMcpService
         t.RoadblockCount,
         FailureReasonOf(t),
         t.Status == TaskStatus.Failed ? t.FailureTurnsUsed : null,
-        t.Status == TaskStatus.Failed ? t.FailureMaxTurns : null);
+        t.Status == TaskStatus.Failed ? t.FailureMaxTurns : null,
+        t.DependsOnTaskId,
+        blocked,
+        blockedReason);
 
     // "unknown" covers a Failed task that predates this field (never got a classified reason
     // stamped) — a defined value rather than null so callers don't have to special-case it.

src/ClaudeDo.Worker/External/TaskWaitMcpTools.cs

@@ -7,7 +7,9 @@ using TaskStatus = ClaudeDo.Data.Models.TaskStatus;
 
 namespace ClaudeDo.Worker.External;
 
-public sealed record TaskStatusChangeDto(string TaskId, string Status);
+// BlockedReason is set only when Status is "Blocked" -- a Queued task the picker will not
+// claim yet, either because of a planning-chain predecessor or an unmet depends-on link.
+public sealed record TaskStatusChangeDto(string TaskId, string Status, string? BlockedReason = null);
 public sealed record WaitForTaskChangeResult(IReadOnlyList<TaskStatusChangeDto> Changed, bool TimedOut);
 
 [McpServerToolType]
@@ -42,9 +44,12 @@ public sealed class TaskWaitMcpTools
     [McpServerTool, Description(
         "Blocks until at least one of the given tasks leaves Queued/Running -- use this instead of " +
         "polling get_task in a loop. Returns immediately if a task is already outside Queued/Running " +
-        "(an unknown id reports status \"NotFound\" and counts as changed). Pitfall: a planning parent " +
-        "goes Running -> WaitingForChildren while its children are still working, so by default " +
-        "waiting on a parent returns early; see treatWaitingForChildrenAsBusy. Sends MCP progress " +
+        "(an unknown id reports status \"NotFound\" and counts as changed). A Queued task the picker " +
+        "will not claim yet (a planning-chain predecessor, or a depends_on link whose target isn't " +
+        "Done) also reports immediately as status \"Blocked\" with blockedReason set, instead of " +
+        "silently waiting out the full timeout. Pitfall: a planning parent goes Running -> " +
+        "WaitingForChildren while its children are still working, so by default waiting on a parent " +
+        "returns early; see treatWaitingForChildrenAsBusy. Sends MCP progress " +
         "pings every 30s while waiting so a long wait survives the calling client's own idle-silence " +
         "abort (Claude Code defaults to killing an MCP call after ~300s of silence) -- this is not " +
         "guaranteed by every possible MCP client.")]
@@ -101,22 +106,60 @@ public sealed class TaskWaitMcpTools
         var rows = await ctx.Tasks
             .AsNoTracking()
             .Where(t => taskIds.Contains(t.Id))
-            .Select(t => new { t.Id, t.Status })
+            .Select(t => new { t.Id, t.Status, t.BlockedByTaskId, t.DependsOnTaskId })
             .ToListAsync(ct);
 
-        var byId = rows.ToDictionary(r => r.Id, r => r.Status);
+        var byId = rows.ToDictionary(r => r.Id, r => r);
+
+        // A Queued task with an unmet depends_on link never becomes "changed" by itself -- the
+        // picker will not touch it. Batch-resolve those dependencies' statuses once instead of a
+        // query per candidate.
+        var dependencyIds = rows
+            .Where(r => r.Status == TaskStatus.Queued && r.BlockedByTaskId is null && r.DependsOnTaskId is not null)
+            .Select(r => r.DependsOnTaskId!)
+            .Distinct()
+            .ToList();
+        var dependencyStatuses = dependencyIds.Count == 0
+            ? new Dictionary<string, TaskStatus>()
+            : await ctx.Tasks.AsNoTracking()
+                .Where(t => dependencyIds.Contains(t.Id))
+                .Select(t => new { t.Id, t.Status })
+                .ToDictionaryAsync(t => t.Id, t => t.Status, ct);
+
         var result = new List<TaskStatusChangeDto>();
         foreach (var id in taskIds)
         {
-            if (!byId.TryGetValue(id, out var status))
+            if (!byId.TryGetValue(id, out var row))
             {
                 result.Add(new TaskStatusChangeDto(id, "NotFound"));
                 continue;
             }
-            var busy = status == TaskStatus.Queued || status == TaskStatus.Running
-                || (treatWaitingForChildrenAsBusy && status == TaskStatus.WaitingForChildren);
+
+            if (row.Status == TaskStatus.Queued)
+            {
+                if (row.BlockedByTaskId is not null)
+                {
+                    result.Add(new TaskStatusChangeDto(id, "Blocked",
+                        $"Blocked by planning-chain predecessor {row.BlockedByTaskId}."));
+                    continue;
+                }
+                if (row.DependsOnTaskId is not null)
+                {
+                    var known = dependencyStatuses.TryGetValue(row.DependsOnTaskId, out var depStatus);
+                    if (!known || depStatus != TaskStatus.Done)
+                    {
+                        result.Add(new TaskStatusChangeDto(id, "Blocked",
+                            $"Blocked: depends on task {row.DependsOnTaskId} (status: " +
+                            (known ? depStatus.ToString() : "not found") + ")."));
+                        continue;
+                    }
+                }
+            }
+
+            var busy = row.Status == TaskStatus.Queued || row.Status == TaskStatus.Running
+                || (treatWaitingForChildrenAsBusy && row.Status == TaskStatus.WaitingForChildren);
             if (!busy)
-                result.Add(new TaskStatusChangeDto(id, status.ToString()));
+                result.Add(new TaskStatusChangeDto(id, row.Status.ToString()));
         }
         return result;
     }