feat: agent coordination system (workflows, locks, components, messages)

Adds /api/coord/* endpoints for real-time cross-session coordination:
- coord_workflows: named units of work per project
- coord_work_items: tasks within workflows with dependency chains
- coord_session_locks: exclusive resource locks with auto-expiry (TTL)
- coord_component_states: live component state per project (upsert)
- coord_messages: cross-session messaging and broadcasts
- /api/coord/status: cross-project snapshot endpoint

Replaces PROJECT_STATE.md as the coordination layer for Claude sessions.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

api/schemas/coord_component_state.py

@@ -0,0 +1,30 @@
+"""Pydantic schemas for CoordComponentState."""
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class CoordComponentStateUpsert(BaseModel):
+    """Input schema for upserting a component state."""
+
+    state: str = Field(..., description="State: deployed, building, stable, broken, unknown", max_length=50)
+    version: Optional[str] = Field(None, description="Version string or git SHA", max_length=100)
+    notes: Optional[str] = Field(None, description="Freeform notes")
+    updated_by: str = Field(..., description="Session performing this update", max_length=200)
+
+
+class CoordComponentStateResponse(BaseModel):
+    """Output schema for a component state."""
+
+    project_key: str
+    component: str
+    state: str
+    version: Optional[str]
+    notes: Optional[str]
+    updated_by: str
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}

api/schemas/coord_message.py

@@ -0,0 +1,39 @@
+"""Pydantic schemas for CoordMessage."""
+
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class CoordMessageCreate(BaseModel):
+    """Input schema for sending a message."""
+
+    from_session: str = Field(..., description="Sending session identifier", max_length=200)
+    to_session: Optional[str] = Field(None, description="Recipient session; NULL = broadcast", max_length=200)
+    project_key: Optional[str] = Field(None, description="Optional project context", max_length=200)
+    subject: str = Field(..., description="Message subject", max_length=500)
+    body: str = Field(..., description="Message body, markdown ok")
+
+
+class CoordMessageUpdate(BaseModel):
+    """Input schema for updating a message (mark read, etc.)."""
+
+    read_at: Optional[datetime] = None
+
+
+class CoordMessageResponse(BaseModel):
+    """Output schema for a message."""
+
+    id: UUID
+    from_session: str
+    to_session: Optional[str]
+    project_key: Optional[str]
+    subject: str
+    body: str
+    read_at: Optional[datetime]
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}

api/schemas/coord_session_lock.py

@@ -0,0 +1,41 @@
+"""Pydantic schemas for CoordSessionLock."""
+
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class CoordSessionLockCreate(BaseModel):
+    """Input schema for claiming a lock."""
+
+    project_key: str = Field(..., description="Project namespace", max_length=200)
+    session_id: str = Field(..., description="Session claiming the lock", max_length=200)
+    resource: str = Field(..., description="Resource path being locked, e.g. 'server/src/'", max_length=500)
+    description: Optional[str] = Field(None, description="Why this lock is needed")
+    ttl_hours: float = Field(2.0, description="Lock lifetime in hours; 0 = no expiry", ge=0)
+
+
+class CoordSessionLockUpdate(BaseModel):
+    """Input schema for updating a lock (rarely needed directly)."""
+
+    description: Optional[str] = None
+    expires_at: Optional[datetime] = None
+
+
+class CoordSessionLockResponse(BaseModel):
+    """Output schema for a lock."""
+
+    id: UUID
+    project_key: str
+    session_id: str
+    resource: str
+    description: Optional[str]
+    acquired_at: datetime
+    expires_at: Optional[datetime]
+    released_at: Optional[datetime]
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}

api/schemas/coord_work_item.py

@@ -0,0 +1,53 @@
+"""Pydantic schemas for CoordWorkItem."""
+
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class CoordWorkItemCreate(BaseModel):
+    """Input schema for creating a work item."""
+
+    workflow_id: str = Field(..., description="Parent workflow UUID", max_length=36)
+    project_key: str = Field(..., description="Project namespace slug", max_length=200)
+    title: str = Field(..., description="Short title", max_length=500)
+    description: Optional[str] = Field(None, description="Full description, markdown ok")
+    status: str = Field("pending", description="Status: pending, in_progress, blocked, completed, cancelled")
+    priority: int = Field(0, description="Higher value = more urgent")
+    assigned_session: Optional[str] = Field(None, max_length=200)
+    depends_on_id: Optional[str] = Field(None, description="Blocking predecessor item UUID", max_length=36)
+
+
+class CoordWorkItemUpdate(BaseModel):
+    """Input schema for updating a work item. All fields optional."""
+
+    title: Optional[str] = Field(None, max_length=500)
+    description: Optional[str] = None
+    status: Optional[str] = Field(None, description="Status: pending, in_progress, blocked, completed, cancelled")
+    priority: Optional[int] = None
+    assigned_session: Optional[str] = Field(None, max_length=200)
+    depends_on_id: Optional[str] = Field(None, max_length=36)
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+
+
+class CoordWorkItemResponse(BaseModel):
+    """Output schema for a work item."""
+
+    id: UUID
+    workflow_id: str
+    project_key: str
+    title: str
+    description: Optional[str]
+    status: str
+    priority: int
+    assigned_session: Optional[str]
+    depends_on_id: Optional[str]
+    started_at: Optional[datetime]
+    completed_at: Optional[datetime]
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}

api/schemas/coord_workflow.py

@@ -0,0 +1,42 @@
+"""Pydantic schemas for CoordWorkflow."""
+
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class CoordWorkflowCreate(BaseModel):
+    """Input schema for creating a workflow."""
+
+    project_key: str = Field(..., description="Project namespace slug", max_length=200)
+    name: str = Field(..., description="Short workflow identifier", max_length=200)
+    description: Optional[str] = Field(None, description="Freeform description, markdown ok")
+    status: str = Field("planning", description="Status: planning, active, blocked, completed, cancelled")
+    created_by: str = Field(..., description="Creating session identifier", max_length=200)
+
+
+class CoordWorkflowUpdate(BaseModel):
+    """Input schema for updating a workflow. All fields optional."""
+
+    name: Optional[str] = Field(None, max_length=200)
+    description: Optional[str] = None
+    status: Optional[str] = Field(None, description="Status: planning, active, blocked, completed, cancelled")
+    completed_at: Optional[datetime] = None
+
+
+class CoordWorkflowResponse(BaseModel):
+    """Output schema for a workflow."""
+
+    id: UUID
+    project_key: str
+    name: str
+    description: Optional[str]
+    status: str
+    created_by: str
+    completed_at: Optional[datetime]
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}