feat: implement task dependencies with validation and update handling

backend/app/api/agent.py

@@ -26,8 +26,15 @@ from app.models.board_memory import BoardMemory
 from app.models.board_onboarding import BoardOnboardingSession
 from app.models.boards import Board
 from app.models.gateways import Gateway
+from app.models.task_dependencies import TaskDependency
 from app.models.tasks import Task
-from app.schemas.agents import AgentCreate, AgentHeartbeat, AgentHeartbeatCreate, AgentNudge, AgentRead
+from app.schemas.agents import (
+    AgentCreate,
+    AgentHeartbeat,
+    AgentHeartbeatCreate,
+    AgentNudge,
+    AgentRead,
+)
 from app.schemas.approvals import ApprovalCreate, ApprovalRead, ApprovalStatus
 from app.schemas.board_memory import BoardMemoryCreate, BoardMemoryRead
 from app.schemas.board_onboarding import BoardOnboardingAgentUpdate, BoardOnboardingRead
@@ -36,6 +43,11 @@ from app.schemas.common import OkResponse
 from app.schemas.pagination import DefaultLimitOffsetPage
 from app.schemas.tasks import TaskCommentCreate, TaskCommentRead, TaskCreate, TaskRead, TaskUpdate
 from app.services.activity_log import record_activity
+from app.services.task_dependencies import (
+    blocked_by_dependency_ids,
+    dependency_status_by_id,
+    validate_dependency_update,
+)
 
 router = APIRouter(prefix="/agent", tags=["agent"])
 
@@ -131,14 +143,39 @@ async def create_task(
     board: Board = Depends(get_board_or_404),
     session: AsyncSession = Depends(get_session),
     agent_ctx: AgentAuthContext = Depends(get_agent_auth_context),
-) -> Task:
+) -> TaskRead:
     _guard_board_access(agent_ctx, board)
     if not agent_ctx.agent.is_board_lead:
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
-    task = Task.model_validate(payload)
+    data = payload.model_dump()
+    depends_on_task_ids = cast(list[UUID], data.pop("depends_on_task_ids", []) or [])
+
+    task = Task.model_validate(data)
     task.board_id = board.id
     task.auto_created = True
     task.auto_reason = f"lead_agent:{agent_ctx.agent.id}"
+
+    normalized_deps = await validate_dependency_update(
+        session,
+        board_id=board.id,
+        task_id=task.id,
+        depends_on_task_ids=depends_on_task_ids,
+    )
+    dep_status = await dependency_status_by_id(
+        session,
+        board_id=board.id,
+        dependency_ids=normalized_deps,
+    )
+    blocked_by = blocked_by_dependency_ids(dependency_ids=normalized_deps, status_by_id=dep_status)
+
+    if blocked_by and (task.assigned_agent_id is not None or task.status != "inbox"):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={
+                "message": "Task is blocked by incomplete dependencies.",
+                "blocked_by_task_ids": [str(value) for value in blocked_by],
+            },
+        )
     if task.assigned_agent_id:
         agent = await session.get(Agent, task.assigned_agent_id)
         if agent is None:
@@ -151,6 +188,14 @@ async def create_task(
         if agent.board_id and agent.board_id != board.id:
             raise HTTPException(status_code=status.HTTP_409_CONFLICT)
     session.add(task)
+    for dep_id in normalized_deps:
+        session.add(
+            TaskDependency(
+                board_id=board.id,
+                task_id=task.id,
+                depends_on_task_id=dep_id,
+            )
+        )
     await session.commit()
     await session.refresh(task)
     record_activity(
@@ -170,7 +215,13 @@ async def create_task(
                 task=task,
                 agent=assigned_agent,
             )
-    return task
+    return TaskRead.model_validate(task, from_attributes=True).model_copy(
+        update={
+            "depends_on_task_ids": normalized_deps,
+            "blocked_by_task_ids": blocked_by,
+            "is_blocked": bool(blocked_by),
+        }
+    )
 
 
 @router.patch("/boards/{board_id}/tasks/{task_id}", response_model=TaskRead)
@@ -179,7 +230,7 @@ async def update_task(
     task: Task = Depends(get_task_or_404),
     session: AsyncSession = Depends(get_session),
     agent_ctx: AgentAuthContext = Depends(get_agent_auth_context),
-) -> Task:
+) -> TaskRead:
     if agent_ctx.agent.board_id and task.board_id and agent_ctx.agent.board_id != task.board_id:
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
     return await tasks_api.update_task(

backend/app/api/agents.py

@@ -27,7 +27,6 @@ from app.models.agents import Agent
 from app.models.boards import Board
 from app.models.gateways import Gateway
 from app.models.tasks import Task
-from app.schemas.common import OkResponse
 from app.schemas.agents import (
     AgentCreate,
     AgentHeartbeat,
@@ -35,6 +34,7 @@ from app.schemas.agents import (
     AgentRead,
     AgentUpdate,
 )
+from app.schemas.common import OkResponse
 from app.schemas.pagination import DefaultLimitOffsetPage
 from app.services.activity_log import record_activity
 from app.services.agent_provisioning import (
@@ -97,7 +97,9 @@ async def _require_board(session: AsyncSession, board_id: UUID | str | None) ->
     return board
 
 
-async def _require_gateway(session: AsyncSession, board: Board) -> tuple[Gateway, GatewayClientConfig]:
+async def _require_gateway(
+    session: AsyncSession, board: Board
+) -> tuple[Gateway, GatewayClientConfig]:
     if not board.gateway_id:
         raise HTTPException(
             status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
@@ -155,7 +157,9 @@ async def _find_gateway_for_main_session(
 ) -> Gateway | None:
     if not session_key:
         return None
-    return (await session.exec(select(Gateway).where(Gateway.main_session_key == session_key))).first()
+    return (
+        await session.exec(select(Gateway).where(Gateway.main_session_key == session_key))
+    ).first()
 
 
 async def _ensure_gateway_session(
@@ -211,7 +215,9 @@ def _record_heartbeat(session: AsyncSession, agent: Agent) -> None:
     )
 
 
-def _record_instruction_failure(session: AsyncSession, agent: Agent, error: str, action: str) -> None:
+def _record_instruction_failure(
+    session: AsyncSession, agent: Agent, error: str, action: str
+) -> None:
     action_label = action.replace("_", " ").capitalize()
     record_activity(
         session,
@@ -275,7 +281,9 @@ async def stream_agents(
                 break
             async with async_session_maker() as session:
                 agents = await _fetch_agent_events(session, board_id, last_seen)
-                main_session_keys = await _get_gateway_main_session_keys(session) if agents else set()
+                main_session_keys = (
+                    await _get_gateway_main_session_keys(session) if agents else set()
+                )
             for agent in agents:
                 updated_at = agent.updated_at or agent.last_seen_at or utcnow()
                 if updated_at > last_seen:

backend/app/api/approvals.py

@@ -131,7 +131,9 @@ async def stream_approvals(
                         )
                     ).one()
                 )
-                task_ids = {approval.task_id for approval in approvals if approval.task_id is not None}
+                task_ids = {
+                    approval.task_id for approval in approvals if approval.task_id is not None
+                }
                 counts_by_task_id: dict[UUID, tuple[int, int]] = {}
                 if task_ids:
                     rows = list(

backend/app/api/board_memory.py

@@ -77,17 +77,15 @@ async def _fetch_memory_events(
     is_chat: bool | None = None,
 ) -> list[BoardMemory]:
     statement = (
-        select(BoardMemory)
-        .where(col(BoardMemory.board_id) == board_id)
+        select(BoardMemory).where(col(BoardMemory.board_id) == board_id)
         # Old/invalid rows (empty/whitespace-only content) can exist; exclude them to
         # satisfy the NonEmptyStr response schema.
         .where(func.length(func.trim(col(BoardMemory.content))) > 0)
     )
     if is_chat is not None:
         statement = statement.where(col(BoardMemory.is_chat) == is_chat)
-    statement = (
-        statement.where(col(BoardMemory.created_at) >= since)
-        .order_by(col(BoardMemory.created_at))
+    statement = statement.where(col(BoardMemory.created_at) >= since).order_by(
+        col(BoardMemory.created_at)
     )
     return list(await session.exec(statement))
 
@@ -162,8 +160,7 @@ async def list_board_memory(
         if actor.agent.board_id and actor.agent.board_id != board.id:
             raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
     statement = (
-        select(BoardMemory)
-        .where(col(BoardMemory.board_id) == board.id)
+        select(BoardMemory).where(col(BoardMemory.board_id) == board.id)
         # Old/invalid rows (empty/whitespace-only content) can exist; exclude them to
         # satisfy the NonEmptyStr response schema.
         .where(func.length(func.trim(col(BoardMemory.content))) > 0)

backend/app/api/board_onboarding.py

@@ -22,9 +22,9 @@ from app.models.board_onboarding import BoardOnboardingSession
 from app.models.boards import Board
 from app.models.gateways import Gateway
 from app.schemas.board_onboarding import (
-    BoardOnboardingAnswer,
     BoardOnboardingAgentComplete,
     BoardOnboardingAgentUpdate,
+    BoardOnboardingAnswer,
     BoardOnboardingConfirm,
     BoardOnboardingLeadAgentDraft,
     BoardOnboardingRead,
@@ -251,9 +251,7 @@ async def answer_onboarding(
         answer_text = f"{payload.answer}: {payload.other_text}"
 
     messages = list(onboarding.messages or [])
-    messages.append(
-        {"role": "user", "content": answer_text, "timestamp": utcnow().isoformat()}
-    )
+    messages.append({"role": "user", "content": answer_text, "timestamp": utcnow().isoformat()})
 
     try:
         await ensure_session(onboarding.session_key, config=config, label="Main Agent")

backend/app/api/boards.py

@@ -4,8 +4,7 @@ import re
 from uuid import UUID, uuid4
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
-from sqlalchemy import delete
-from sqlalchemy import func
+from sqlalchemy import delete, func
 from sqlmodel import col, select
 from sqlmodel.ext.asyncio.session import AsyncSession
 
@@ -31,8 +30,8 @@ from app.models.boards import Board
 from app.models.gateways import Gateway
 from app.models.task_fingerprints import TaskFingerprint
 from app.models.tasks import Task
-from app.schemas.common import OkResponse
 from app.schemas.boards import BoardCreate, BoardRead, BoardUpdate
+from app.schemas.common import OkResponse
 from app.schemas.pagination import DefaultLimitOffsetPage
 from app.schemas.view_models import BoardSnapshot
 from app.services.board_snapshot import build_board_snapshot
@@ -229,10 +228,14 @@ async def delete_board(
 
     if task_ids:
         await session.execute(delete(ActivityEvent).where(col(ActivityEvent.task_id).in_(task_ids)))
-        await session.execute(delete(TaskFingerprint).where(col(TaskFingerprint.board_id) == board.id))
+        await session.execute(
+            delete(TaskFingerprint).where(col(TaskFingerprint.board_id) == board.id)
+        )
     if agents:
         agent_ids = [agent.id for agent in agents]
-        await session.execute(delete(ActivityEvent).where(col(ActivityEvent.agent_id).in_(agent_ids)))
+        await session.execute(
+            delete(ActivityEvent).where(col(ActivityEvent.agent_id).in_(agent_ids))
+        )
         await session.execute(delete(Agent).where(col(Agent.id).in_(agent_ids)))
     await session.execute(delete(Approval).where(col(Approval.board_id) == board.id))
     await session.execute(delete(BoardMemory).where(col(BoardMemory.board_id) == board.id))

backend/app/api/tasks.py

@@ -3,16 +3,16 @@ from __future__ import annotations
 import asyncio
 import json
 from collections import deque
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Sequence
 from datetime import datetime, timezone
 from typing import cast
 from uuid import UUID
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
-from sqlalchemy import asc, delete, desc
+from sqlalchemy import asc, delete, desc, or_
 from sqlmodel import col, select
-from sqlmodel.sql.expression import Select
 from sqlmodel.ext.asyncio.session import AsyncSession
+from sqlmodel.sql.expression import Select
 from sse_starlette.sse import EventSourceResponse
 
 from app.api.deps import (
@@ -33,13 +33,23 @@ from app.models.agents import Agent
 from app.models.approvals import Approval
 from app.models.boards import Board
 from app.models.gateways import Gateway
+from app.models.task_dependencies import TaskDependency
 from app.models.task_fingerprints import TaskFingerprint
 from app.models.tasks import Task
 from app.schemas.common import OkResponse
+from app.schemas.errors import BlockedTaskError
 from app.schemas.pagination import DefaultLimitOffsetPage
 from app.schemas.tasks import TaskCommentCreate, TaskCommentRead, TaskCreate, TaskRead, TaskUpdate
 from app.services.activity_log import record_activity
 from app.services.mentions import extract_mentions, matches_agent_mention
+from app.services.task_dependencies import (
+    blocked_by_dependency_ids,
+    dependency_ids_by_task_id,
+    dependency_status_by_id,
+    dependent_task_ids,
+    replace_task_dependencies,
+    validate_dependency_update,
+)
 
 router = APIRouter(prefix="/boards/{board_id}/tasks", tags=["tasks"])
 
@@ -60,6 +70,16 @@ def _comment_validation_error() -> HTTPException:
     )
 
 
+def _blocked_task_error(blocked_by_task_ids: Sequence[UUID]) -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_409_CONFLICT,
+        detail={
+            "message": "Task is blocked by incomplete dependencies.",
+            "blocked_by_task_ids": [str(value) for value in blocked_by_task_ids],
+        },
+    )
+
+
 async def has_valid_recent_comment(
     session: AsyncSession,
     task: Task,
@@ -124,6 +144,75 @@ def _lead_created_task(task: Task, lead: Agent) -> bool:
     return task.auto_reason == f"lead_agent:{lead.id}"
 
 
+async def _reconcile_dependents_for_dependency_toggle(
+    session: AsyncSession,
+    *,
+    board_id: UUID,
+    dependency_task: Task,
+    previous_status: str,
+    actor_agent_id: UUID | None,
+) -> None:
+    done_toggled = (previous_status == "done") != (dependency_task.status == "done")
+    if not done_toggled:
+        return
+
+    dependent_ids = await dependent_task_ids(
+        session,
+        board_id=board_id,
+        dependency_task_id=dependency_task.id,
+    )
+    if not dependent_ids:
+        return
+
+    dependents = list(
+        await session.exec(
+            select(Task)
+            .where(col(Task.board_id) == board_id)
+            .where(col(Task.id).in_(dependent_ids))
+        )
+    )
+    reopened = previous_status == "done" and dependency_task.status != "done"
+
+    for dependent in dependents:
+        if dependent.status == "done":
+            continue
+        if reopened:
+            should_reset = (
+                dependent.status != "inbox"
+                or dependent.assigned_agent_id is not None
+                or dependent.in_progress_at is not None
+            )
+            if should_reset:
+                dependent.status = "inbox"
+                dependent.assigned_agent_id = None
+                dependent.in_progress_at = None
+                dependent.updated_at = utcnow()
+                session.add(dependent)
+                record_activity(
+                    session,
+                    event_type="task.status_changed",
+                    task_id=dependent.id,
+                    message=f"Task returned to inbox: dependency reopened ({dependency_task.title}).",
+                    agent_id=actor_agent_id,
+                )
+            else:
+                record_activity(
+                    session,
+                    event_type="task.updated",
+                    task_id=dependent.id,
+                    message=f"Dependency completion changed: {dependency_task.title}.",
+                    agent_id=actor_agent_id,
+                )
+        else:
+            record_activity(
+                session,
+                event_type="task.updated",
+                task_id=dependent.id,
+                message=f"Dependency completion changed: {dependency_task.title}.",
+                agent_id=actor_agent_id,
+            )
+
+
 async def _fetch_task_events(
     session: AsyncSession,
     board_id: UUID,
@@ -144,12 +233,6 @@ async def _fetch_task_events(
     return list(await session.exec(statement))
 
 
-def _serialize_task(task: Task | None) -> dict[str, object] | None:
-    if task is None:
-        return None
-    return TaskRead.model_validate(task).model_dump(mode="json")
-
-
 def _serialize_comment(event: ActivityEvent) -> dict[str, object]:
     return TaskCommentRead.model_validate(event).model_dump(mode="json")
 
@@ -372,8 +455,30 @@ async def stream_tasks(
         while True:
             if await request.is_disconnected():
                 break
+            deps_map: dict[UUID, list[UUID]] = {}
+            dep_status: dict[UUID, str] = {}
             async with async_session_maker() as session:
                 rows = await _fetch_task_events(session, board.id, last_seen)
+                task_ids = [
+                    task.id
+                    for event, task in rows
+                    if task is not None and event.event_type != "task.comment"
+                ]
+                if task_ids:
+                    deps_map = await dependency_ids_by_task_id(
+                        session,
+                        board_id=board.id,
+                        task_ids=list({*task_ids}),
+                    )
+                    dep_ids: list[UUID] = []
+                    for value in deps_map.values():
+                        dep_ids.extend(value)
+                    if dep_ids:
+                        dep_status = await dependency_status_by_id(
+                            session,
+                            board_id=board.id,
+                            dependency_ids=list({*dep_ids}),
+                        )
             for event, task in rows:
                 if event.id in seen_ids:
                     continue
@@ -388,7 +493,27 @@ async def stream_tasks(
                 if event.event_type == "task.comment":
                     payload["comment"] = _serialize_comment(event)
                 else:
-                    payload["task"] = _serialize_task(task)
+                    if task is None:
+                        payload["task"] = None
+                    else:
+                        dep_list = deps_map.get(task.id, [])
+                        blocked_by = blocked_by_dependency_ids(
+                            dependency_ids=dep_list,
+                            status_by_id=dep_status,
+                        )
+                        if task.status == "done":
+                            blocked_by = []
+                        payload["task"] = (
+                            TaskRead.model_validate(task, from_attributes=True)
+                            .model_copy(
+                                update={
+                                    "depends_on_task_ids": dep_list,
+                                    "blocked_by_task_ids": blocked_by,
+                                    "is_blocked": bool(blocked_by),
+                                }
+                            )
+                            .model_dump(mode="json")
+                        )
                 yield {"event": "task", "data": json.dumps(payload)}
             await asyncio.sleep(2)
 
@@ -422,21 +547,80 @@ async def list_tasks(
     if unassigned:
         statement = statement.where(col(Task.assigned_agent_id).is_(None))
     statement = statement.order_by(col(Task.created_at).desc())
-    return await paginate(session, statement)
+
+    async def _transform(items: Sequence[object]) -> Sequence[object]:
+        tasks = cast(Sequence[Task], items)
+        if not tasks:
+            return []
+        task_ids = [task.id for task in tasks]
+        deps_map = await dependency_ids_by_task_id(session, board_id=board.id, task_ids=task_ids)
+        dep_ids: list[UUID] = []
+        for value in deps_map.values():
+            dep_ids.extend(value)
+        dep_status = await dependency_status_by_id(
+            session,
+            board_id=board.id,
+            dependency_ids=list({*dep_ids}),
+        )
+
+        output: list[TaskRead] = []
+        for task in tasks:
+            dep_list = deps_map.get(task.id, [])
+            blocked_by = blocked_by_dependency_ids(dependency_ids=dep_list, status_by_id=dep_status)
+            if task.status == "done":
+                blocked_by = []
+            output.append(
+                TaskRead.model_validate(task, from_attributes=True).model_copy(
+                    update={
+                        "depends_on_task_ids": dep_list,
+                        "blocked_by_task_ids": blocked_by,
+                        "is_blocked": bool(blocked_by),
+                    }
+                )
+            )
+        return output
+
+    return await paginate(session, statement, transformer=_transform)
 
 
-@router.post("", response_model=TaskRead)
+@router.post("", response_model=TaskRead, responses={409: {"model": BlockedTaskError}})
 async def create_task(
     payload: TaskCreate,
     board: Board = Depends(get_board_or_404),
     session: AsyncSession = Depends(get_session),
     auth: AuthContext = Depends(require_admin_auth),
-) -> Task:
-    task = Task.model_validate(payload)
+) -> TaskRead:
+    data = payload.model_dump()
+    depends_on_task_ids = cast(list[UUID], data.pop("depends_on_task_ids", []) or [])
+
+    task = Task.model_validate(data)
     task.board_id = board.id
     if task.created_by_user_id is None and auth.user is not None:
         task.created_by_user_id = auth.user.id
+
+    normalized_deps = await validate_dependency_update(
+        session,
+        board_id=board.id,
+        task_id=task.id,
+        depends_on_task_ids=depends_on_task_ids,
+    )
+    dep_status = await dependency_status_by_id(
+        session,
+        board_id=board.id,
+        dependency_ids=normalized_deps,
+    )
+    blocked_by = blocked_by_dependency_ids(dependency_ids=normalized_deps, status_by_id=dep_status)
+    if blocked_by and (task.assigned_agent_id is not None or task.status != "inbox"):
+        raise _blocked_task_error(blocked_by)
     session.add(task)
+    for dep_id in normalized_deps:
+        session.add(
+            TaskDependency(
+                board_id=board.id,
+                task_id=task.id,
+                depends_on_task_id=dep_id,
+            )
+        )
     await session.commit()
     await session.refresh(task)
 
@@ -457,59 +641,128 @@ async def create_task(
                 task=task,
                 agent=assigned_agent,
             )
-    return task
+    return TaskRead.model_validate(task, from_attributes=True).model_copy(
+        update={
+            "depends_on_task_ids": normalized_deps,
+            "blocked_by_task_ids": blocked_by,
+            "is_blocked": bool(blocked_by),
+        }
+    )
 
 
-@router.patch("/{task_id}", response_model=TaskRead)
+@router.patch(
+    "/{task_id}",
+    response_model=TaskRead,
+    responses={409: {"model": BlockedTaskError}},
+)
 async def update_task(
     payload: TaskUpdate,
     task: Task = Depends(get_task_or_404),
     session: AsyncSession = Depends(get_session),
     actor: ActorContext = Depends(require_admin_or_agent),
-) -> Task:
+) -> TaskRead:
+    if task.board_id is None:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail="Task board_id is required.",
+        )
+    board_id = task.board_id
+
     previous_status = task.status
     previous_assigned = task.assigned_agent_id
     updates = payload.model_dump(exclude_unset=True)
     comment = updates.pop("comment", None)
+    depends_on_task_ids = cast(list[UUID] | None, updates.pop("depends_on_task_ids", None))
 
+    requested_fields = set(updates)
+    if comment is not None:
+        requested_fields.add("comment")
+    if depends_on_task_ids is not None:
+        requested_fields.add("depends_on_task_ids")
+
+    async def _current_dep_ids() -> list[UUID]:
+        deps_map = await dependency_ids_by_task_id(session, board_id=board_id, task_ids=[task.id])
+        return deps_map.get(task.id, [])
+
+    async def _blocked_by(dep_ids: Sequence[UUID]) -> list[UUID]:
+        if not dep_ids:
+            return []
+        dep_status = await dependency_status_by_id(
+            session,
+            board_id=board_id,
+            dependency_ids=list(dep_ids),
+        )
+        return blocked_by_dependency_ids(dependency_ids=list(dep_ids), status_by_id=dep_status)
+
+    # Lead agent: delegation only (assign/unassign, resolve review, manage dependencies).
     if actor.actor_type == "agent" and actor.agent and actor.agent.is_board_lead:
-        allowed_fields = {"assigned_agent_id", "status"}
-        if comment is not None or not set(updates).issubset(allowed_fields):
+        allowed_fields = {"assigned_agent_id", "status", "depends_on_task_ids"}
+        if comment is not None or not requested_fields.issubset(allowed_fields):
             raise HTTPException(
                 status_code=status.HTTP_403_FORBIDDEN,
-                detail="Board leads can only assign or unassign tasks.",
+                detail=(
+                    "Board leads can only assign/unassign tasks, update dependencies, or resolve review tasks."
+                ),
             )
-        if "assigned_agent_id" in updates:
-            assigned_id = updates["assigned_agent_id"]
-            if assigned_id:
-                agent = await session.get(Agent, assigned_id)
-                if agent is None:
-                    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
-                if agent.is_board_lead:
+
+        normalized_deps: list[UUID] | None = None
+        if depends_on_task_ids is not None:
+            if task.status == "done":
+                raise HTTPException(
+                    status_code=status.HTTP_409_CONFLICT,
+                    detail=("Cannot change task dependencies after a task is done."),
+                )
+            normalized_deps = await replace_task_dependencies(
+                session,
+                board_id=board_id,
+                task_id=task.id,
+                depends_on_task_ids=depends_on_task_ids,
+            )
+
+        effective_deps = (
+            normalized_deps if normalized_deps is not None else await _current_dep_ids()
+        )
+        blocked_by = await _blocked_by(effective_deps)
+
+        # Blocked tasks cannot be assigned or moved out of inbox (unless already done).
+        if blocked_by and task.status != "done":
+            task.status = "inbox"
+            task.assigned_agent_id = None
+            task.in_progress_at = None
+        else:
+            if "assigned_agent_id" in updates:
+                assigned_id = updates["assigned_agent_id"]
+                if assigned_id:
+                    agent = await session.get(Agent, assigned_id)
+                    if agent is None:
+                        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+                    if agent.is_board_lead:
+                        raise HTTPException(
+                            status_code=status.HTTP_403_FORBIDDEN,
+                            detail="Board leads cannot assign tasks to themselves.",
+                        )
+                    if agent.board_id and task.board_id and agent.board_id != task.board_id:
+                        raise HTTPException(status_code=status.HTTP_409_CONFLICT)
+                    task.assigned_agent_id = agent.id
+                else:
+                    task.assigned_agent_id = None
+
+            if "status" in updates:
+                if task.status != "review":
                     raise HTTPException(
                         status_code=status.HTTP_403_FORBIDDEN,
-                        detail="Board leads cannot assign tasks to themselves.",
+                        detail="Board leads can only change status when a task is in review.",
                     )
-                if agent.board_id and task.board_id and agent.board_id != task.board_id:
-                    raise HTTPException(status_code=status.HTTP_409_CONFLICT)
-                task.assigned_agent_id = agent.id
-            else:
-                task.assigned_agent_id = None
-        if "status" in updates:
-            if task.status != "review":
-                raise HTTPException(
-                    status_code=status.HTTP_403_FORBIDDEN,
-                    detail="Board leads can only change status when a task is in review.",
-                )
-            if updates["status"] not in {"done", "inbox"}:
-                raise HTTPException(
-                    status_code=status.HTTP_403_FORBIDDEN,
-                    detail="Board leads can only move review tasks to done or inbox.",
-                )
-            if updates["status"] == "inbox":
-                task.assigned_agent_id = None
-                task.in_progress_at = None
-            task.status = updates["status"]
+                if updates["status"] not in {"done", "inbox"}:
+                    raise HTTPException(
+                        status_code=status.HTTP_403_FORBIDDEN,
+                        detail="Board leads can only move review tasks to done or inbox.",
+                    )
+                if updates["status"] == "inbox":
+                    task.assigned_agent_id = None
+                    task.in_progress_at = None
+                task.status = updates["status"]
+
         task.updated_at = utcnow()
         session.add(task)
         if task.status != previous_status:
@@ -525,12 +778,17 @@ async def update_task(
             message=message,
             agent_id=actor.agent.id,
         )
+        await _reconcile_dependents_for_dependency_toggle(
+            session,
+            board_id=board_id,
+            dependency_task=task,
+            previous_status=previous_status,
+            actor_agent_id=actor.agent.id,
+        )
         await session.commit()
         await session.refresh(task)
 
         if task.assigned_agent_id and task.assigned_agent_id != previous_assigned:
-            if actor.actor_type == "agent" and actor.agent and task.assigned_agent_id == actor.agent.id:
-                return task
             assigned_agent = await session.get(Agent, task.assigned_agent_id)
             if assigned_agent:
                 board = await session.get(Board, task.board_id) if task.board_id else None
@@ -541,15 +799,33 @@ async def update_task(
                         task=task,
                         agent=assigned_agent,
                     )
-        return task
+
+        dep_ids = await _current_dep_ids()
+        blocked_ids = await _blocked_by(dep_ids)
+        if task.status == "done":
+            blocked_ids = []
+        return TaskRead.model_validate(task, from_attributes=True).model_copy(
+            update={
+                "depends_on_task_ids": dep_ids,
+                "blocked_by_task_ids": blocked_ids,
+                "is_blocked": bool(blocked_ids),
+            }
+        )
+
+    # Non-lead agent: can only change status + comment, and cannot start blocked tasks.
     if actor.actor_type == "agent":
         if actor.agent and actor.agent.board_id and task.board_id:
             if actor.agent.board_id != task.board_id:
                 raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
         allowed_fields = {"status", "comment"}
-        if not set(updates).issubset(allowed_fields):
+        if depends_on_task_ids is not None or not set(updates).issubset(allowed_fields):
             raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
         if "status" in updates:
+            if updates["status"] != "inbox":
+                dep_ids = await _current_dep_ids()
+                blocked_ids = await _blocked_by(dep_ids)
+                if blocked_ids:
+                    raise _blocked_task_error(blocked_ids)
             if updates["status"] == "inbox":
                 task.assigned_agent_id = None
                 task.in_progress_at = None
@@ -557,18 +833,51 @@ async def update_task(
                 task.assigned_agent_id = actor.agent.id if actor.agent else None
                 if updates["status"] == "in_progress":
                     task.in_progress_at = utcnow()
-    elif "status" in updates:
-        if updates["status"] == "inbox":
+    else:
+        # Admin user: dependencies can be edited until the task is done.
+        admin_normalized_deps: list[UUID] | None = None
+        if depends_on_task_ids is not None:
+            if task.status == "done":
+                raise HTTPException(
+                    status_code=status.HTTP_409_CONFLICT,
+                    detail=("Cannot change task dependencies after a task is done."),
+                )
+            admin_normalized_deps = await replace_task_dependencies(
+                session,
+                board_id=board_id,
+                task_id=task.id,
+                depends_on_task_ids=depends_on_task_ids,
+            )
+
+        effective_deps = (
+            admin_normalized_deps if admin_normalized_deps is not None else await _current_dep_ids()
+        )
+        blocked_ids = await _blocked_by(effective_deps)
+
+        target_status = cast(str, updates.get("status", task.status))
+        if blocked_ids and not (task.status == "done" and target_status == "done"):
+            # Blocked tasks cannot be assigned or moved out of inbox. If the task is already in
+            # flight, force it back to inbox and unassign it.
+            task.status = "inbox"
             task.assigned_agent_id = None
             task.in_progress_at = None
-        elif updates["status"] == "in_progress":
-            task.in_progress_at = utcnow()
-    if "assigned_agent_id" in updates and updates["assigned_agent_id"]:
-        agent = await session.get(Agent, updates["assigned_agent_id"])
-        if agent is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
-        if agent.board_id and task.board_id and agent.board_id != task.board_id:
-            raise HTTPException(status_code=status.HTTP_409_CONFLICT)
+            updates["status"] = "inbox"
+            updates["assigned_agent_id"] = None
+
+        if "status" in updates:
+            if updates["status"] == "inbox":
+                task.assigned_agent_id = None
+                task.in_progress_at = None
+            elif updates["status"] == "in_progress":
+                task.in_progress_at = utcnow()
+
+        if "assigned_agent_id" in updates and updates["assigned_agent_id"]:
+            agent = await session.get(Agent, updates["assigned_agent_id"])
+            if agent is None:
+                raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+            if agent.board_id and task.board_id and agent.board_id != task.board_id:
+                raise HTTPException(status_code=status.HTTP_409_CONFLICT)
+
     for key, value in updates.items():
         setattr(task, key, value)
     task.updated_at = utcnow()
@@ -606,14 +915,23 @@ async def update_task(
     else:
         event_type = "task.updated"
         message = f"Task updated: {task.title}."
+    actor_agent_id = actor.agent.id if actor.actor_type == "agent" and actor.agent else None
     record_activity(
         session,
         event_type=event_type,
         task_id=task.id,
         message=message,
-        agent_id=actor.agent.id if actor.actor_type == "agent" and actor.agent else None,
+        agent_id=actor_agent_id,
+    )
+    await _reconcile_dependents_for_dependency_toggle(
+        session,
+        board_id=board_id,
+        dependency_task=task,
+        previous_status=previous_status,
+        actor_agent_id=actor_agent_id,
     )
     await session.commit()
+
     if task.status == "inbox" and task.assigned_agent_id is None:
         if previous_status != "inbox" or previous_assigned is not None:
             board = await session.get(Board, task.board_id) if task.board_id else None
@@ -625,18 +943,31 @@ async def update_task(
                 )
     if task.assigned_agent_id and task.assigned_agent_id != previous_assigned:
         if actor.actor_type == "agent" and actor.agent and task.assigned_agent_id == actor.agent.id:
-            return task
-        assigned_agent = await session.get(Agent, task.assigned_agent_id)
-        if assigned_agent:
-            board = await session.get(Board, task.board_id) if task.board_id else None
-            if board:
-                await _notify_agent_on_task_assign(
-                    session=session,
-                    board=board,
-                    task=task,
-                    agent=assigned_agent,
-                )
-    return task
+            # Don't notify the actor about their own assignment.
+            pass
+        else:
+            assigned_agent = await session.get(Agent, task.assigned_agent_id)
+            if assigned_agent:
+                board = await session.get(Board, task.board_id) if task.board_id else None
+                if board:
+                    await _notify_agent_on_task_assign(
+                        session=session,
+                        board=board,
+                        task=task,
+                        agent=assigned_agent,
+                    )
+
+    dep_ids = await _current_dep_ids()
+    blocked_ids = await _blocked_by(dep_ids)
+    if task.status == "done":
+        blocked_ids = []
+    return TaskRead.model_validate(task, from_attributes=True).model_copy(
+        update={
+            "depends_on_task_ids": dep_ids,
+            "blocked_by_task_ids": blocked_ids,
+            "is_blocked": bool(blocked_ids),
+        }
+    )
 
 
 @router.delete("/{task_id}", response_model=OkResponse)
@@ -648,6 +979,14 @@ async def delete_task(
     await session.execute(delete(ActivityEvent).where(col(ActivityEvent.task_id) == task.id))
     await session.execute(delete(TaskFingerprint).where(col(TaskFingerprint.task_id) == task.id))
     await session.execute(delete(Approval).where(col(Approval.task_id) == task.id))
+    await session.execute(
+        delete(TaskDependency).where(
+            or_(
+                col(TaskDependency.task_id) == task.id,
+                col(TaskDependency.depends_on_task_id) == task.id,
+            )
+        )
+    )
     await session.delete(task)
     await session.commit()
     return OkResponse()