feat(teams): improve task dispatch, concurrency, and tool ergonomics

- Move task dispatch from mid-turn to post-turn to prevent dependent
  tasks from completing before the current agent's run finishes
- Add team create lock to serialize list→create flows across concurrent
  group chat sessions, preventing duplicate task creation
- Require list-before-create gate: agents must call team_tasks(list)
  before creating tasks
- Make assignee required on task creation
- Add pagination (50 per page) to task list with offset support
- Slim task list/get/search responses with dedicated structs to reduce
  context token usage
- Add task board snapshot in announce messages to leader
- Workspace: allow subdirectory paths in read/delete, show directories
  in list output
- UI: reduce kanban card title font size for better visual balance

Author: viettranx

cmd/gateway_consumer_handlers.go

@@ -563,10 +563,6 @@ func handleTeammateMessage(
 										ActorID:   toAgent,
 									},
 								})
-								// FailTask also unblocks dependent tasks.
-								if postTurn != nil {
-									postTurn.DispatchUnblockedTasks(ctx, teamID)
-								}
 							}
 						} else {
 							result := outcome.Result.Content
@@ -591,13 +587,15 @@ func handleTeammateMessage(
 										ActorID:       toAgent,
 									},
 								})
-								// Dispatch newly-unblocked dependent tasks.
-								if postTurn != nil {
-									postTurn.DispatchUnblockedTasks(ctx, teamID)
-								}
 							}
 						}
 					}
+					// Always dispatch unblocked tasks after member turn ends,
+					// regardless of whether the task was already completed by the tool.
+					// This ensures dependent tasks start only after the member's run finishes.
+					if postTurn != nil {
+						postTurn.DispatchUnblockedTasks(ctx, teamID)
+					}
 				}
 			}
 		}
@@ -645,14 +643,25 @@ func handleTeammateMessage(
 		}
 		memberAgent := inMeta["to_agent"]
 
+		// Build task board snapshot scoped to this batch (same origin_trace_id).
+		taskBoardSnapshot := ""
+		if teamIDStr := inMeta["team_id"]; teamIDStr != "" {
+			if teamUUID, err := uuid.Parse(teamIDStr); err == nil {
+				taskBoardSnapshot = buildTaskBoardSnapshot(ctx, teamStore, teamUUID, inMeta["origin_chat_id"], inMeta["origin_trace_id"])
+			}
+		}
+
 		announceContent := fmt.Sprintf(
-			"[System Message] Team member %q completed task.\n\nResult:\n%s\n\n"+
-				"Present this result to the user. Any media files are forwarded automatically. Do NOT search for files — the result above contains all relevant information.",
+			"[System Message] Team member %q completed task.\n\nResult:\n%s",
 			memberAgent, outcome.Result.Content,
 		)
+		if taskBoardSnapshot != "" {
+			announceContent += "\n\n" + taskBoardSnapshot
+		}
+		announceContent += "\n\nPresent this result to the user. Any media files are forwarded automatically. Do NOT search for files — the result above contains all relevant information."
 		// Append team workspace path so lead can locate files without searching.
 		if ws := inMeta["team_workspace"]; ws != "" {
-			announceContent += fmt.Sprintf("\n[Team workspace: %s — use read_file with path relative to workspace root, e.g. read_file(path=\"teams/...\")]", ws)
+			announceContent += fmt.Sprintf("\n[Team workspace: %s — use workspace_read to read files, e.g. workspace_read(file_name=\"filename.md\")]", ws)
 		}
 
 		// Route to the lead's session on the original channel/chat.
@@ -699,6 +708,9 @@ func handleTeammateMessage(
 		announceOutCh := sched.Schedule(announceCtx, scheduler.LaneSubagent, announceReq)
 		announceOutcome := <-announceOutCh
 
+		// Release team create lock — tasks already visible in DB, safe for other goroutines to list.
+		announcePtd.ReleaseTeamLock()
+
 		// Post-turn: dispatch pending team tasks created during announce.
 		if postTurn != nil {
 			for tid, tIDs := range announcePtd.Drain() {
@@ -845,3 +857,42 @@ func handleStopCommand(
 
 	return true
 }
+
+// buildTaskBoardSnapshot returns a formatted summary of batch task statuses
+// for inclusion in the announce message to the leader. Scoped by (teamID, chatID)
+// and filtered by origin_trace_id to show only tasks from the current batch.
+func buildTaskBoardSnapshot(ctx context.Context, teamStore store.TeamStore, teamID uuid.UUID, chatID, originTraceID string) string {
+	if teamStore == nil || originTraceID == "" {
+		return ""
+	}
+	allTasks, err := teamStore.ListTasks(ctx, teamID, "", store.TeamTaskFilterAll, "", "", chatID, 0)
+	if err != nil || len(allTasks) == 0 {
+		return ""
+	}
+
+	// Filter to current batch by origin_trace_id stored in task metadata.
+	var active, completed int
+	var activeLines []string
+	for _, t := range allTasks {
+		tid, _ := t.Metadata["origin_trace_id"].(string)
+		if tid != originTraceID {
+			continue
+		}
+		switch t.Status {
+		case store.TeamTaskStatusCompleted, store.TeamTaskStatusCancelled, store.TeamTaskStatusFailed:
+			completed++
+		default:
+			active++
+			activeLines = append(activeLines, fmt.Sprintf("  #%d %s — %s", t.TaskNumber, t.Subject, t.Status))
+		}
+	}
+	total := active + completed
+	if total == 0 {
+		return ""
+	}
+	if active == 0 {
+		return fmt.Sprintf("=== Task board (this batch) ===\nAll %d tasks completed.", total)
+	}
+	return fmt.Sprintf("=== Task board (this batch) ===\nTask progress: %d/%d completed, %d active:\n%s",
+		completed, total, active, strings.Join(activeLines, "\n"))
+}

cmd/gateway_consumer_normal.go

@@ -333,6 +333,9 @@ func processNormalMessage(
 	go func(agentKey, channel, chatID, session, rID string, meta map[string]string, blockReplyEnabled bool, ptd *tools.PendingTeamDispatch) {
 		outcome := <-outCh
 
+		// Release team create lock — tasks already visible in DB, other goroutines can list.
+		ptd.ReleaseTeamLock()
+
 		// Post-turn: dispatch pending team tasks created during this turn.
 		if postTurn != nil {
 			for teamID, taskIDs := range ptd.Drain() {

internal/agent/loop.go

@@ -331,7 +331,7 @@ func (l *Loop) runLoop(ctx context.Context, req RunRequest) (*RunResult, error)
 			if recovered, err := l.teamStore.RecoverStaleTasks(ctx, team.ID); err == nil && recovered > 0 {
 				slog.Info("recovered stale tasks", "team", team.ID, "count", recovered)
 			}
-			if tasks, err := l.teamStore.ListTasks(ctx, team.ID, "newest", "", req.UserID, "", ""); err == nil {
+			if tasks, err := l.teamStore.ListTasks(ctx, team.ID, "newest", "", req.UserID, "", "", 0); err == nil {
 				var stale []string
 				var inProgress []string
 				for _, t := range tasks {
@@ -608,7 +608,7 @@ func (l *Loop) runLoop(ctx context.Context, req RunRequest) (*RunResult, error)
 			if teamTaskCreates > teamTaskSpawns && !teamTaskRetried {
 				if l.teamStore != nil && l.agentUUID != uuid.Nil {
 					if team, _ := l.teamStore.GetTeamForAgent(ctx, l.agentUUID); team != nil && tools.IsTeamV2(team) {
-						if tasks, err := l.teamStore.ListTasks(ctx, team.ID, "newest", "", req.UserID, "", ""); err == nil {
+						if tasks, err := l.teamStore.ListTasks(ctx, team.ID, "newest", "", req.UserID, "", "", 0); err == nil {
 							var pendingIDs []string
 							for _, t := range tasks {
 								if t.Status == store.TeamTaskStatusPending {

internal/agent/resolver_helpers.go

@@ -83,6 +83,7 @@ func buildTeamMD(team *store.TeamData, members []store.TeamMemberData, selfID uu
 			sb.WriteString("Do NOT use `spawn` for team delegation — `spawn` is only for self-clone subagent work.\n\n")
 			sb.WriteString("Rules:\n")
 			sb.WriteString("- Always specify `assignee` — match member expertise from the list above\n")
+			sb.WriteString("- **Check task board first** — ALWAYS call `team_tasks(action=\"list\")` before creating tasks. The system blocks creation if you skip this step\n")
 			sb.WriteString("- Create all tasks first, then briefly tell the user what you delegated\n")
 			sb.WriteString("- Do NOT add confirmations (\"Done!\", \"Got it!\") — just state what was assigned\n")
 			sb.WriteString("- Results arrive automatically — do NOT present partial results\n")

internal/channels/telegram/commands_tasks.go

@@ -81,7 +81,7 @@ func (c *Channel) handleTasksList(ctx context.Context, chatID int64, isGroup boo
 		return
 	}
 
-	tasks, err := c.teamStore.ListTasks(ctx, team.ID, "newest", store.TeamTaskFilterAll, taskUserID(c.Name(), chatID, isGroup), "", "")
+	tasks, err := c.teamStore.ListTasks(ctx, team.ID, "newest", store.TeamTaskFilterAll, taskUserID(c.Name(), chatID, isGroup), "", "", 0)
 	if err != nil {
 		slog.Warn("tasks command: ListTasks failed", "error", err)
 		send("Failed to list tasks. Please try again.")
@@ -173,7 +173,7 @@ func (c *Channel) handleTaskDetail(ctx context.Context, chatID int64, text strin
 		return
 	}
 
-	tasks, err := c.teamStore.ListTasks(ctx, team.ID, "newest", store.TeamTaskFilterAll, taskUserID(c.Name(), chatID, isGroup), "", "")
+	tasks, err := c.teamStore.ListTasks(ctx, team.ID, "newest", store.TeamTaskFilterAll, taskUserID(c.Name(), chatID, isGroup), "", "", 0)
 	if err != nil {
 		slog.Warn("task_detail command: ListTasks failed", "error", err)
 		send("Failed to list tasks. Please try again.")
@@ -236,7 +236,7 @@ func (c *Channel) handleCallbackQuery(ctx context.Context, query *telego.Callbac
 		return
 	}
 
-	tasks, err := c.teamStore.ListTasks(ctx, team.ID, "newest", store.TeamTaskFilterAll, taskUserID(c.Name(), chatID, isGroup), "", "")
+	tasks, err := c.teamStore.ListTasks(ctx, team.ID, "newest", store.TeamTaskFilterAll, taskUserID(c.Name(), chatID, isGroup), "", "", 0)
 	if err != nil {
 		send("Failed to list tasks.")
 		return

internal/gateway/methods/teams_crud.go

@@ -156,7 +156,7 @@ func (m *TeamsMethods) handleTaskList(ctx context.Context, client *gateway.Clien
 		return
 	}
 
-	tasks, err := m.teamStore.ListTasks(ctx, teamID, "newest", params.Status, "", params.Channel, params.ChatID)
+	tasks, err := m.teamStore.ListTasks(ctx, teamID, "newest", params.Status, "", params.Channel, params.ChatID, 0)
 	if err != nil {
 		slog.Warn("teams.tasks.list failed", "team_id", teamID, "status_filter", params.Status, "error", err)
 		client.SendResponse(protocol.NewErrorResponse(req.ID, protocol.ErrInternal, err.Error()))

internal/store/pg/teams_tasks.go

@@ -163,7 +163,7 @@ func (s *PGTeamStore) UpdateTask(ctx context.Context, taskID uuid.UUID, updates
 	return execMapUpdate(ctx, s.db, "team_tasks", taskID, updates)
 }
 
-func (s *PGTeamStore) ListTasks(ctx context.Context, teamID uuid.UUID, orderBy string, statusFilter string, userID string, channel string, chatID string) ([]store.TeamTaskData, error) {
+func (s *PGTeamStore) ListTasks(ctx context.Context, teamID uuid.UUID, orderBy string, statusFilter string, userID string, channel string, chatID string, offset int) ([]store.TeamTaskData, error) {
 	orderClause := "t.priority DESC, t.created_at"
 	if orderBy == "newest" {
 		orderClause = "t.created_at DESC"
@@ -187,7 +187,7 @@ func (s *PGTeamStore) ListTasks(ctx context.Context, teamID uuid.UUID, orderBy s
 		 `+taskJoinClause+`
 		 WHERE t.team_id = $1 AND ($2 = '' OR t.user_id = $2) `+statusWhere+` `+scopeWhere+`
 		 ORDER BY `+orderClause+`
-		 LIMIT $3`, teamID, userID, maxListTasksRows, channel, chatID)
+		 LIMIT $3 OFFSET $6`, teamID, userID, maxListTasksRows+1, channel, chatID, offset)
 	if err != nil {
 		return nil, err
 	}

internal/store/team_store.go

@@ -320,7 +320,7 @@ type TeamStore interface {
 	// statusFilter: "" = non-completed (default), "completed", "all".
 	// userID: if non-empty, filter to tasks created by this user.
 	// channel+chatID: if either is non-empty, filter to that exact scope.
-	ListTasks(ctx context.Context, teamID uuid.UUID, orderBy string, statusFilter string, userID string, channel string, chatID string) ([]TeamTaskData, error)
+	ListTasks(ctx context.Context, teamID uuid.UUID, orderBy string, statusFilter string, userID string, channel string, chatID string, offset int) ([]TeamTaskData, error)
 	// GetTask returns a single task by ID with joined agent info.
 	GetTask(ctx context.Context, taskID uuid.UUID) (*TeamTaskData, error)
 	// GetTasksByIDs returns multiple tasks by IDs in a single query.

internal/tools/context_keys.go

@@ -286,8 +286,10 @@ const ctxPendingDispatch toolContextKey = "tool_pending_team_dispatch"
 // After the turn ends, the consumer drains and dispatches them.
 // Thread-safe: tools may execute in parallel goroutines.
 type PendingTeamDispatch struct {
-	mu    sync.Mutex
-	tasks map[uuid.UUID][]uuid.UUID // teamID → []taskID
+	mu       sync.Mutex
+	tasks    map[uuid.UUID][]uuid.UUID // teamID → []taskID
+	listed   bool                      // true after list called in this turn
+	teamLock *sync.Mutex               // acquired on list, released before post-turn dispatch
 }
 
 func NewPendingTeamDispatch() *PendingTeamDispatch {
@@ -310,6 +312,37 @@ func (p *PendingTeamDispatch) Drain() map[uuid.UUID][]uuid.UUID {
 	return out
 }
 
+// MarkListed records that list was called in this turn.
+func (p *PendingTeamDispatch) MarkListed() {
+	p.mu.Lock()
+	p.listed = true
+	p.mu.Unlock()
+}
+
+// HasListed reports whether list was called in this turn.
+func (p *PendingTeamDispatch) HasListed() bool {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return p.listed
+}
+
+// SetTeamLock stores the acquired team create lock so it can be released post-turn.
+func (p *PendingTeamDispatch) SetTeamLock(m *sync.Mutex) {
+	p.mu.Lock()
+	p.teamLock = m
+	p.mu.Unlock()
+}
+
+// ReleaseTeamLock releases the held team create lock, if any.
+func (p *PendingTeamDispatch) ReleaseTeamLock() {
+	p.mu.Lock()
+	if p.teamLock != nil {
+		p.teamLock.Unlock()
+		p.teamLock = nil
+	}
+	p.mu.Unlock()
+}
+
 func WithPendingTeamDispatch(ctx context.Context, ptd *PendingTeamDispatch) context.Context {
 	return context.WithValue(ctx, ctxPendingDispatch, ptd)
 }

internal/tools/team_tasks_lifecycle.go

@@ -87,10 +87,11 @@ func (t *TeamTasksTool) executeComplete(ctx context.Context, args map[string]any
 		ActorID:          ownerKey,
 	})
 
-	// Immediately dispatch any newly-unblocked tasks.
-	t.manager.DispatchUnblockedTasks(ctx, team.ID)
+	// Dependent tasks are dispatched by the consumer after this agent's turn ends
+	// (post-turn), not mid-turn. This prevents dependent tasks from completing and
+	// announcing to the leader before this agent's own run finishes.
 
-	return NewResult(fmt.Sprintf("Task %s completed. Dependent tasks have been unblocked.", taskID))
+	return NewResult(fmt.Sprintf("Task %s completed. Dependent tasks will be dispatched after this turn ends.", taskID))
 }
 
 func (t *TeamTasksTool) executeCancel(ctx context.Context, args map[string]any) *Result {
@@ -135,10 +136,9 @@ func (t *TeamTasksTool) executeCancel(ctx context.Context, args map[string]any)
 		ActorID:   t.manager.agentKeyFromID(ctx, agentID),
 	})
 
-	// Immediately dispatch any newly-unblocked tasks.
-	t.manager.DispatchUnblockedTasks(ctx, team.ID)
+	// Dependent tasks are dispatched by the consumer after this agent's turn ends (post-turn).
 
-	return NewResult(fmt.Sprintf("Task %s cancelled. Any running delegation has been stopped and dependent tasks unblocked.", taskID))
+	return NewResult(fmt.Sprintf("Task %s cancelled. Dependent tasks will be unblocked after this turn ends.", taskID))
 }
 
 func (t *TeamTasksTool) executeReview(ctx context.Context, args map[string]any) *Result {