управление клодкодами из чата

[ShaerWare]

управление оркестрами с мониторингом через вкладку канбана и родмапа

[ShaerWare]

# 🤖 CLAUDE CODE: Мультиагентная оркестрация — Полная реализация

## КОНТЕКСТ ПРОЕКТА

Репозиторий: `/opt/ai-secretary/`
Runtime: Python 3.12 venv (`/opt/ai-secretary/venv/`)
Framework: FastAPI (async) + Vue 3 + SQLAlchemy async + SQLite
Паттерны: Repository Pattern, Pydantic v2, Composition API, Tailwind CSS
Линтер: ruff (line-length=120), mypy strict, eslint

**ОБЯЗАТЕЛЬНО перед стартом:**
```bash
cd /opt/ai-secretary
source venv/bin/activate
gh auth status          # должен быть аутентифицирован
git status              # должна быть чистая main
python -c "import claude_code_manager" 2>/dev/null && echo "EXISTS" || echo "NEW"
```

---

## ЗАДАЧА

Реализовать систему мультиагентной оркестрации Claude Code CLI. Система позволяет запускать несколько `claude` CLI-процессов параллельно, каждый в изолированном Git Worktree, с координацией через файловые блокировки и DAG зависимостей. Прогресс отображается в реальном времени через SSE в новой 15-й вкладке Admin Panel "Агенты".

**Точка входа для пользователя:** Admin Panel → Chat → ставит задачу → я (Claude) генерирую JSON-артефакт → пользователь подтверждает → система создаёт Kanban-доску агентов и запускает их → каждый агент создаёт PR → пользователь/я одобряем PR из чата.

---

## РЕАЛИЗАЦИЯ: СТРОГО В ЭТОМ ПОРЯДКЕ

### ШАГ 1: Database models

Файл: `db/models.py`
Добавить в конец файла (не трогать существующие модели):

```python
class KanbanAgentSession(Base):
    """Multi-agent orchestration session."""
    __tablename__ = "kanban_agent_sessions"

    id: Mapped[str] = mapped_column(String(100), primary_key=True)
    title: Mapped[str] = mapped_column(String(500))
    artifact: Mapped[str] = mapped_column(Text)  # исходный JSON артефакт
    status: Mapped[str] = mapped_column(String(50), default="running")
    # running | completed | stopped | failed
    created_by: Mapped[str] = mapped_column(String(100))
    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
    completed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)

    tasks: Mapped[list["KanbanAgentTask"]] = relationship(
        "KanbanAgentTask", back_populates="session", cascade="all, delete-orphan"
    )


class KanbanAgentTask(Base):
    """Single Claude Code agent task within a session."""
    __tablename__ = "kanban_agent_tasks"

    id: Mapped[str] = mapped_column(String(100), primary_key=True)
    session_id: Mapped[str] = mapped_column(
        String(100), ForeignKey("kanban_agent_sessions.id"), index=True
    )
    title: Mapped[str] = mapped_column(String(500))
    instruction: Mapped[str] = mapped_column(Text)
    files_scope: Mapped[str] = mapped_column(Text, default="[]")   # JSON array
    depends_on: Mapped[str] = mapped_column(Text, default="[]")    # JSON array
    max_turns: Mapped[int] = mapped_column(Integer, default=50)
    branch: Mapped[str] = mapped_column(String(200))
    status: Mapped[str] = mapped_column(String(50), default="pending")
    # pending | running | paused | done | blocked | failed | review_failed

    agent_pid: Mapped[int | None] = mapped_column(Integer, nullable=True)
    turns_used: Mapped[int] = mapped_column(Integer, default=0)
    files_changed: Mapped[str] = mapped_column(Text, default="[]")  # JSON array
    current_action: Mapped[str] = mapped_column(String(300), default="")
    pr_url: Mapped[str | None] = mapped_column(String(500), nullable=True)
    pr_number: Mapped[int | None] = mapped_column(Integer, nullable=True)

    started_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
    completed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)

    session: Mapped["KanbanAgentSession"] = relationship(back_populates="tasks")
```

### ШАГ 2: Alembic миграция

```bash
cd /opt/ai-secretary
venv/bin/alembic revision --autogenerate -m "add_kanban_agent_tables"
venv/bin/alembic upgrade head
# Проверить:
sqlite3 data/secretary.db ".tables" | grep kanban_agent
```

### ШАГ 3: Repository

Создать файл `db/repositories/agent_session.py`:

```python
"""Repository for Claude Code agent sessions and tasks."""
from __future__ import annotations

import json
from datetime import datetime
from typing import Any

from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.orm import selectinload

from db.models import KanbanAgentSession, KanbanAgentTask
from db.repositories.base import BaseRepository


class AgentSessionRepository(BaseRepository[KanbanAgentSession]):
    def __init__(self, session: AsyncSession) -> None:
        super().__init__(KanbanAgentSession, session)

    async def get_with_tasks(self, session_id: str) -> KanbanAgentSession | None:
        result = await self.session.execute(
            select(KanbanAgentSession)
            .options(selectinload(KanbanAgentSession.tasks))
            .where(KanbanAgentSession.id == session_id)
        )
        return result.scalar_one_or_none()

    async def get_all_with_tasks(self) -> list[KanbanAgentSession]:
        result = await self.session.execute(
            select(KanbanAgentSession)
            .options(selectinload(KanbanAgentSession.tasks))
            .order_by(KanbanAgentSession.created_at.desc())
        )
        return list(result.scalars().all())

    async def update_status(self, session_id: str, status: str) -> None:
        extra: dict[str, Any] = {}
        if status in ("completed", "stopped", "failed"):
            extra["completed_at"] = datetime.utcnow()
        await self.session.execute(
            update(KanbanAgentSession)
            .where(KanbanAgentSession.id == session_id)
            .values(status=status, **extra)
        )
        await self.session.commit()


class AgentTaskRepository(BaseRepository[KanbanAgentTask]):
    def __init__(self, session: AsyncSession) -> None:
        super().__init__(KanbanAgentTask, session)

    async def update_task(self, task_id: str, **kwargs: Any) -> None:
        await self.session.execute(
            update(KanbanAgentTask)
            .where(KanbanAgentTask.id == task_id)
            .values(**kwargs)
        )
        await self.session.commit()

    async def get_session_tasks(self, session_id: str) -> list[KanbanAgentTask]:
        result = await self.session.execute(
            select(KanbanAgentTask)
            .where(KanbanAgentTask.session_id == session_id)
            .order_by(KanbanAgentTask.id)
        )
        return list(result.scalars().all())
```

### ШАГ 4: Git Worktree Manager

Создать файл `git_worktree_manager.py`:

```python
"""Git Worktree manager for agent isolation."""
from __future__ import annotations

import asyncio
import logging
from pathlib import Path

logger = logging.getLogger(__name__)


class GitWorktreeManager:
    def __init__(self, repo_path: str = "/opt/ai-secretary") -> None:
        self.repo_path = Path(repo_path)
        self.worktree_base = Path("/tmp/cc-agents")
        self.worktree_base.mkdir(exist_ok=True)

    def worktree_path(self, task_id: str) -> Path:
        return self.worktree_base / f"agent-{task_id}"

    async def create_worktree(self, task_id: str, branch: str) -> Path:
        path = self.worktree_path(task_id)
        if path.exists():
            await self.remove_worktree(task_id)

        proc = await asyncio.create_subprocess_exec(
            "git", "worktree", "add", str(path), "-b", branch,
            cwd=self.repo_path,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        _, stderr = await proc.communicate()
        if proc.returncode != 0:
            raise RuntimeError(f"Failed to create worktree: {stderr.decode()}")
        logger.info(f"Created worktree: {path} branch={branch}")
        return path

    async def remove_worktree(self, task_id: str) -> None:
        path = self.worktree_path(task_id)
        proc = await asyncio.create_subprocess_exec(
            "git", "worktree", "remove", str(path), "--force",
            cwd=self.repo_path,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        await proc.communicate()
        # Удалить ветку если осталась
        await asyncio.create_subprocess_exec(
            "git", "branch", "-D", f"server/cc-{task_id}",
            cwd=self.repo_path,
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.DEVNULL,
        )
        logger.info(f"Removed worktree: {path}")

    async def create_pr(
        self,
        branch: str,
        title: str,
        body: str,
        worktree_path: Path,
    ) -> tuple[str, int]:
        """Create PR via gh CLI. Returns (pr_url, pr_number)."""
        proc = await asyncio.create_subprocess_exec(
            "gh", "pr", "create",
            "--title", title,
            "--body", body,
            "--base", "main",
            "--head", branch,
            cwd=worktree_path,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        stdout, stderr = await proc.communicate()
        if proc.returncode != 0:
            raise RuntimeError(f"gh pr create failed: {stderr.decode()}")

        pr_url = stdout.decode().strip()
        # Извлечь номер PR из URL
        pr_number = int(pr_url.rstrip("/").split("/")[-1])
        return pr_url, pr_number

    async def get_diff_stat(self, branch: str) -> str:
        proc = await asyncio.create_subprocess_exec(
            "git", "diff", "main", branch, "--stat",
            cwd=self.repo_path,
            stdout=asyncio.subprocess.PIPE,
        )
        stdout, _ = await proc.communicate()
        return stdout.decode()

    async def check_gh_auth(self) -> bool:
        proc = await asyncio.create_subprocess_exec(
            "gh", "auth", "status",
            stdout=asyncio.subprocess.DEVNULL,
            stderr=asyncio.subprocess.DEVNULL,
        )
        await proc.communicate()
        return proc.returncode == 0
```

### ШАГ 5: Claude Code Manager (ядро)

Создать файл `claude_code_manager.py`:

```python
"""Claude Code CLI multi-agent manager."""
from __future__ import annotations

import asyncio
import json
import logging
import os
import signal
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import Any, Callable, Coroutine

logger = logging.getLogger(__name__)

# Тип SSE-колбэка
SSECallback = Callable[[dict[str, Any]], Coroutine[Any, Any, None]]


@dataclass
class AgentInstance:
    task_id: str
    process: asyncio.subprocess.Process
    worktree_path: Path
    branch: str
    session_id: str
    max_turns: int = 50
    pid: int = 0
    turns_used: int = 0
    files_changed: list[str] = field(default_factory=list)
    current_action: str = "initializing"
    is_paused: bool = False


class ClaudeCodeManager:
    """Manages multiple Claude Code CLI agent processes."""

    def __init__(self, repo_path: str = "/opt/ai-secretary") -> None:
        self.repo_path = Path(repo_path)
        self.agents: dict[str, AgentInstance] = {}
        self._sse_callbacks: list[SSECallback] = []
        self._completion_callbacks: dict[str, list[Callable]] = {}

    async def spawn_agent(
        self,
        task_id: str,
        session_id: str,
        instruction: str,
        branch: str,
        worktree_path: Path,
        max_turns: int = 50,
    ) -> AgentInstance:
        """Spawn a Claude Code agent in an isolated worktree."""
        cmd = [
            "claude",
            "--print",
            "--output-format", "stream-json",
            "--max-turns", str(max_turns),
            instruction,
        ]

        process = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
            cwd=worktree_path,
        )

        agent = AgentInstance(
            task_id=task_id,
            session_id=session_id,
            process=process,
            worktree_path=worktree_path,
            branch=branch,
            max_turns=max_turns,
            pid=process.pid or 0,
        )
        self.agents[task_id] = agent

        asyncio.create_task(self._monitor_agent(agent))
        logger.info(f"Spawned agent task_id={task_id} pid={process.pid}")
        return agent

    async def _monitor_agent(self, agent: AgentInstance) -> None:
        """Parse stream-json output and broadcast status updates."""
        assert agent.process.stdout is not None

        async for raw_line in agent.process.stdout:
            line = raw_line.decode().strip()
            if not line:
                continue
            try:
                event = json.loads(line)
                await self._process_stream_event(agent, event)
            except json.JSONDecodeError:
                # Не JSON — игнорируем (stderr может попасть сюда)
                pass

        return_code = await agent.process.wait()
        await self._on_agent_finished(agent, return_code)

    async def _process_stream_event(
        self, agent: AgentInstance, event: dict[str, Any]
    ) -> None:
        """Handle individual stream-json event."""
        event_type = event.get("type", "")

        if event_type == "assistant":
            content = event.get("message", {}).get("content", [])
            for block in content:
                if isinstance(block, dict) and block.get("type") == "text":
                    text = block["text"]
                    # Обрезаем до 200 символов для SSE
                    agent.current_action = text[:200].replace("\n", " ")

        elif event_type == "tool_use" or event_type == "tool_result":
            tool_name = event.get("name", event.get("type", "tool"))
            input_data = event.get("input", {})

            # Отслеживаем изменённые файлы
            file_path = (
                input_data.get("path")
                or input_data.get("file_path")
                or input_data.get("target_file")
            )
            if file_path and any(
                kw in tool_name.lower()
                for kw in ("write", "edit", "create", "str_replace")
            ):
                if file_path not in agent.files_changed:
                    agent.files_changed.append(file_path)

            agent.current_action = f"[{tool_name}] {str(file_path or '')[:80]}"

        elif event_type == "system":
            subtype = event.get("subtype", "")
            if subtype == "turn_count":
                agent.turns_used = event.get("turn_count", agent.turns_used)

        # Получить turn count из любого события если есть
        if "turn_count" in event:
            agent.turns_used = event["turn_count"]

        await self._broadcast({
            "type": "agent_update",
            "task_id": agent.task_id,
            "session_id": agent.session_id,
            "pid": agent.pid,
            "turns_used": agent.turns_used,
            "max_turns": agent.max_turns,
            "files_changed_count": len(agent.files_changed),
            "files_changed": agent.files_changed[-5:],  # последние 5
            "current_action": agent.current_action,
            "is_paused": agent.is_paused,
        })

    async def _on_agent_finished(
        self, agent: AgentInstance, return_code: int
    ) -> None:
        """Called when agent process exits."""
        status = "done" if return_code == 0 else "failed"
        logger.info(f"Agent {agent.task_id} finished rc={return_code}")

        await self._broadcast({
            "type": "agent_finished",
            "task_id": agent.task_id,
            "session_id": agent.session_id,
            "status": status,
            "return_code": return_code,
            "turns_used": agent.turns_used,
            "files_changed": agent.files_changed,
        })

        # Вызвать колбэки завершения (для ProjectCoordinator)
        for cb in self._completion_callbacks.get(agent.task_id, []):
            asyncio.create_task(cb(agent, status))

        del self.agents[agent.task_id]

    def on_agent_complete(
        self, task_id: str, callback: Callable
    ) -> None:
        """Register callback for when agent completes."""
        self._completion_callbacks.setdefault(task_id, []).append(callback)

    async def pause_agent(self, task_id: str) -> bool:
        agent = self.agents.get(task_id)
        if not agent or agent.is_paused:
            return False
        try:
            os.kill(agent.pid, signal.SIGSTOP)
            agent.is_paused = True
            await self._broadcast({
                "type": "agent_paused",
                "task_id": task_id,
                "session_id": agent.session_id,
            })
            return True
        except ProcessLookupError:
            return False

    async def resume_agent(self, task_id: str) -> bool:
        agent = self.agents.get(task_id)
        if not agent or not agent.is_paused:
            return False
        try:
            os.kill(agent.pid, signal.SIGCONT)
            agent.is_paused = False
            await self._broadcast({
                "type": "agent_resumed",
                "task_id": task_id,
                "session_id": agent.session_id,
            })
            return True
        except ProcessLookupError:
            return False

    async def kill_agent(self, task_id: str) -> bool:
        agent = self.agents.get(task_id)
        if not agent:
            return False
        try:
            agent.process.terminate()
            await asyncio.sleep(2)
            if agent.process.returncode is None:
                agent.process.kill()
            return True
        except Exception as e:
            logger.error(f"Kill agent {task_id} error: {e}")
            return False

    def register_sse_callback(self, cb: SSECallback) -> None:
        self._sse_callbacks.append(cb)

    def unregister_sse_callback(self, cb: SSECallback) -> None:
        self._sse_callbacks.discard(cb) if hasattr(
            self._sse_callbacks, "discard"
        ) else None
        if cb in self._sse_callbacks:
            self._sse_callbacks.remove(cb)

    async def _broadcast(self, data: dict[str, Any]) -> None:
        for cb in list(self._sse_callbacks):
            try:
                await cb(data)
            except Exception as e:
                logger.warning(f"SSE broadcast error: {e}")

    def get_all_status(self) -> list[dict[str, Any]]:
        return [
            {
                "task_id": a.task_id,
                "session_id": a.session_id,
                "pid": a.pid,
                "turns_used": a.turns_used,
                "max_turns": a.max_turns,
                "files_changed_count": len(a.files_changed),
                "current_action": a.current_action,
                "is_paused": a.is_paused,
                "branch": a.branch,
            }
            for a in self.agents.values()
        ]

    async def watchdog_cleanup(
        self, running_tasks: list[dict[str, Any]]
    ) -> list[str]:
        """
        На старте orchestrator: проверить PID из БД.
        Вернуть task_id которые надо пометить blocked.
        """
        dead_task_ids: list[str] = []
        for task in running_tasks:
            pid = task.get("agent_pid")
            task_id = task["id"]
            if not pid:
                dead_task_ids.append(task_id)
                continue
            try:
                os.kill(pid, 0)  # 0 = проверка без сигнала
            except ProcessLookupError:
                dead_task_ids.append(task_id)
        return dead_task_ids


# Singleton
claude_code_manager = ClaudeCodeManager()
```

### ШАГ 6: Project Coordinator

Создать файл `project_coordinator.py`:

```python
"""Coordinates multiple Claude Code agents within a project session."""
from __future__ import annotations

import asyncio
import json
import logging
import uuid
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import Any

from claude_code_manager import AgentInstance, ClaudeCodeManager
from git_worktree_manager import GitWorktreeManager

logger = logging.getLogger(__name__)


@dataclass
class ArtifactAgent:
    """Single agent definition from artifact JSON."""
    id: str
    title: str
    instruction: str
    files_scope: list[str]
    depends_on: list[str]
    max_turns: int
    branch: str


@dataclass
class SessionState:
    session_id: str
    agents_map: dict[str, ArtifactAgent]          # id → ArtifactAgent
    file_locks: dict[str, str] = field(default_factory=dict)   # path → task_id
    completed: set[str] = field(default_factory=set)
    failed: set[str] = field(default_factory=set)
    pending: list[str] = field(default_factory=list)          # task_ids


def validate_artifact(artifact: dict[str, Any]) -> list[str]:
    """
    Validate artifact JSON. Returns list of error strings.
    Checks: unique ids, no circular deps (DFS), no overlapping file scopes.
    """
    errors: list[str] = []
    agents = artifact.get("agents", [])

    if not agents:
        return ["Artifact has no agents"]

    ids = [a["id"] for a in agents]

    # Уникальность ID
    if len(ids) != len(set(ids)):
        errors.append("Duplicate agent IDs in artifact")

    id_set = set(ids)

    # Все depends_on существуют
    for a in agents:
        for dep in a.get("depends_on", []):
            if dep not in id_set:
                errors.append(f"Agent {a['id']} depends on unknown {dep}")

    # Проверка циклов (DFS)
    dep_map: dict[str, list[str]] = {
        a["id"]: a.get("depends_on", []) for a in agents
    }
    visited: set[str] = set()
    rec_stack: set[str] = set()

    def has_cycle(node: str) -> bool:
        visited.add(node)
        rec_stack.add(node)
        for neighbor in dep_map.get(node, []):
            if neighbor not in visited:
                if has_cycle(neighbor):
                    return True
            elif neighbor in rec_stack:
                return True
        rec_stack.discard(node)
        return False

    for node in ids:
        if node not in visited:
            if has_cycle(node):
                errors.append(f"Circular dependency detected involving {node}")
                break

    # Пересечение файловых scope
    all_scopes: dict[str, str] = {}  # file → agent_id
    for a in agents:
        for f in a.get("files_scope", []):
            if f in all_scopes:
                errors.append(
                    f"File scope conflict: '{f}' claimed by "
                    f"{all_scopes[f]} and {a['id']}"
                )
            else:
                all_scopes[f] = a["id"]

    return errors


class ProjectCoordinator:
    """Manages lifecycle of a multi-agent session."""

    def __init__(
        self,
        manager: ClaudeCodeManager,
        worktree_mgr: GitWorktreeManager,
        repo_path: str = "/opt/ai-secretary",
    ) -> None:
        self.manager = manager
        self.worktree_mgr = worktree_mgr
        self.repo_path = Path(repo_path)
        self.sessions: dict[str, SessionState] = {}
        self._db_update_callback: Any = None  # set by orchestrator

    def set_db_update_callback(self, cb: Any) -> None:
        """Callback(session_id, task_id, **kwargs) for DB updates."""
        self._db_update_callback = cb

    async def start_session(
        self,
        artifact: dict[str, Any],
        created_by: str,
    ) -> str:
        """
        Parse artifact, validate, create worktrees, spawn ready agents.
        Returns session_id.
        """
        session_id = artifact.get("session_id") or str(uuid.uuid4())[:8]

        agents_map = {
            a["id"]: ArtifactAgent(
                id=a["id"],
                title=a["title"],
                instruction=a["instruction"],
                files_scope=a.get("files_scope", []),
                depends_on=a.get("depends_on", []),
                max_turns=a.get("max_turns", 50),
                branch=a.get("branch", f"server/cc-{session_id}-{a['id']}"),
            )
            for a in artifact["agents"]
        }

        state = SessionState(
            session_id=session_id,
            agents_map=agents_map,
            pending=list(agents_map.keys()),
        )
        self.sessions[session_id] = state

        # Запустить агентов у которых нет зависимостей
        await self._spawn_ready_agents(state)

        return session_id

    async def _spawn_ready_agents(self, state: SessionState) -> None:
        """Spawn all agents whose dependencies are satisfied."""
        still_pending = []
        for task_id in state.pending:
            agent_def = state.agents_map[task_id]
            deps_done = all(d in state.completed for d in agent_def.depends_on)

            if not deps_done:
                still_pending.append(task_id)
                continue

            # Проверить файловые конфликты
            conflicts = [
                f for f in agent_def.files_scope
                if f in state.file_locks
            ]
            if conflicts:
                logger.warning(
                    f"Agent {task_id} has file conflicts: {conflicts}, deferring"
                )
                still_pending.append(task_id)
                continue

            # Спавним
            await self._spawn_one(state, agent_def)

        state.pending = still_pending

    async def _spawn_one(
        self, state: SessionState, agent_def: ArtifactAgent
    ) -> None:
        """Create worktree and spawn single agent."""
        try:
            worktree_path = await self.worktree_mgr.create_worktree(
                agent_def.id, agent_def.branch
            )
        except Exception as e:
            logger.error(f"Worktree creation failed for {agent_def.id}: {e}")
            state.failed.add(agent_def.id)
            if self._db_update_callback:
                await self._db_update_callback(
                    state.session_id, agent_def.id,
                    status="failed", current_action=str(e)
                )
            return

        # Обогатить инструкцию контекстом
        other_locked = {
            f: owner for f, owner in state.file_locks.items()
        }
        enriched = self._enrich_instruction(agent_def, other_locked)

        # Зарегистрировать файловые блокировки
        for f in agent_def.files_scope:
            state.file_locks[f] = agent_def.id

        # Зарегистрировать колбэк завершения
        self.manager.on_agent_complete(
            agent_def.id,
            lambda inst, status, _aid=agent_def.id, _sid=state.session_id: (
                self._on_agent_done(state, _aid, inst, status)
            ),
        )

        agent = await self.manager.spawn_agent(
            task_id=agent_def.id,
            session_id=state.session_id,
            instruction=enriched,
            branch=agent_def.branch,
            worktree_path=worktree_path,
            max_turns=agent_def.max_turns,
        )

        if self._db_update_callback:
            await self._db_update_callback(
                state.session_id, agent_def.id,
                status="running",
                agent_pid=agent.pid,
                started_at=datetime.utcnow(),
            )

        logger.info(
            f"Session {state.session_id}: spawned {agent_def.id} pid={agent.pid}"
        )

    async def _on_agent_done(
        self,
        state: SessionState,
        task_id: str,
        agent: AgentInstance,
        status: str,
    ) -> None:
        """Called when agent finishes. Create PR, release locks, spawn next."""
        agent_def = state.agents_map[task_id]

        # Создать PR
        pr_url: str | None = None
        pr_number: int | None = None
        if status == "done":
            try:
                body = (
                    f"**Session:** {state.session_id}\n"
                    f"**Agent:** {task_id} — {agent_def.title}\n\n"
                    f"**Files changed:** {', '.join(agent.files_changed) or 'none'}\n"
                    f"**Turns used:** {agent.turns_used}/{agent_def.max_turns}\n\n"
                    f"*Auto-created by Claude Code multi-agent system*"
                )
                pr_url, pr_number = await self.worktree_mgr.create_pr(
                    branch=agent_def.branch,
                    title=f"[{state.session_id}][{task_id}] {agent_def.title}",
                    body=body,
                    worktree_path=agent.worktree_path,
                )
                state.completed.add(task_id)
                logger.info(f"PR created: {pr_url}")
            except Exception as e:
                logger.error(f"PR creation failed for {task_id}: {e}")
                status = "failed"
                state.failed.add(task_id)
        else:
            state.failed.add(task_id)

        # Освободить файловые блокировки
        for f in agent_def.files_scope:
            state.file_locks.pop(f, None)

        # Почистить worktree
        try:
            await self.worktree_mgr.remove_worktree(task_id)
        except Exception as e:
            logger.warning(f"Worktree cleanup warning: {e}")

        # Обновить БД
        if self._db_update_callback:
            await self._db_update_callback(
                state.session_id, task_id,
                status=status,
                pr_url=pr_url,
                pr_number=pr_number,
                turns_used=agent.turns_used,
                files_changed=json.dumps(agent.files_changed),
                completed_at=datetime.utcnow(),
            )

        # Проверить — можно ли запустить следующих
        if state.pending:
            await self._spawn_ready_agents(state)

        # Проверить завершение сессии
        all_ids = set(state.agents_map.keys())
        done_or_failed = state.completed | state.failed
        if done_or_failed >= all_ids:
            final_status = "completed" if not state.failed else "failed"
            logger.info(
                f"Session {state.session_id} finished: {final_status}"
            )
            if self._db_update_callback:
                await self._db_update_callback(
                    state.session_id, None,
                    session_status=final_status,
                )
            del self.sessions[state.session_id]

    async def stop_session(self, session_id: str) -> None:
        """Kill all running agents in a session."""
        state = self.sessions.get(session_id)
        if not state:
            return
        for task_id in list(self.manager.agents.keys()):
            agent = self.manager.agents.get(task_id)
            if agent and agent.session_id == session_id:
                await self.manager.kill_agent(task_id)
        state.pending = []

    def _enrich_instruction(
        self,
        agent_def: ArtifactAgent,
        locked_files: dict[str, str],
    ) -> str:
        forbidden = "\n".join(f"  ❌ {f} (занят агентом {owner})"
                              for f, owner in locked_files.items())
        allowed = "\n".join(f"  ✅ {f}" for f in agent_def.files_scope)

        return f"""# Claude Code Agent Task
Session agent: {agent_def.id}

## Твои файлы (можешь изменять):
{allowed or "  (все файлы проекта)"}

## ЗАПРЕЩЕНО изменять (другие агенты работают):
{forbidden or "  (нет ограничений)"}

## Задача:
{agent_def.instruction}

## Требования к выполнению:
1. Соблюдай паттерны проекта: Repository Pattern, async/await, Pydantic v2
2. Python: type hints обязательны, line-length=120
3. Vue: Composition API + TypeScript + Tailwind CSS
4. После реализации: `ruff check . --fix && ruff format .`
5. Проверь синтаксис Python: `python -m py_compile <file>`
6. Если тест падает — почини и повтори

## Стек проекта:
- Backend: FastAPI async, SQLAlchemy async, Pydantic v2, SQLite
- Frontend: Vue 3 + TypeScript + Vite + Tailwind + Pinia + TanStack Query
- Auth: JWT multi-role (admin/operator/viewer)
- Real-time: SSE (Server-Sent Events)
"""


# Singletons
git_worktree_manager = GitWorktreeManager()
project_coordinator = ProjectCoordinator(claude_code_manager, git_worktree_manager)
```

### ШАГ 7: Agent Settings (через system_config)

Создать файл `agent_settings_manager.py`:

```python
"""Agent settings management via system_config table."""
from __future__ import annotations

import json
from typing import Any

from pydantic import BaseModel, Field


class AgentSettings(BaseModel):
    max_concurrent_agents: int = Field(default=5, ge=1, le=50)
    default_max_turns: int = Field(default=50, ge=5, le=500)
    auto_review_enabled: bool = True
    worktree_base_path: str = "/tmp/cc-agents"
    turn_warning_threshold_pct: int = Field(default=80, ge=10, le=99)

    class Config:
        extra = "ignore"


SETTINGS_KEY = "claude_code_agent_settings"


async def get_agent_settings(db_session: Any) -> AgentSettings:
    """Load settings from system_config."""
    from db.repositories.config import ConfigRepository
    repo = ConfigRepository(db_session)
    raw = await repo.get(SETTINGS_KEY)
    if raw is None:
        return AgentSettings()
    try:
        data = json.loads(raw) if isinstance(raw, str) else raw
        return AgentSettings(**data)
    except Exception:
        return AgentSettings()


async def save_agent_settings(db_session: Any, settings: AgentSettings) -> None:
    """Save settings to system_config."""
    from db.repositories.config import ConfigRepository
    repo = ConfigRepository(db_session)
    await repo.set(SETTINGS_KEY, settings.model_dump())
```

### ШАГ 8: Endpoints в orchestrator.py

Найти в `orchestrator.py` место после последнего `@app.` endpoint и добавить новый раздел:

```python
# ============================================================
# CLAUDE CODE MULTI-AGENT ORCHESTRATION
# ============================================================

from claude_code_manager import claude_code_manager
from project_coordinator import project_coordinator, validate_artifact
from agent_settings_manager import AgentSettings, get_agent_settings, save_agent_settings
from db.repositories.agent_session import AgentSessionRepository, AgentTaskRepository


# --- Pydantic schemas ---

class ArtifactAgentSchema(BaseModel):
    id: str
    title: str
    instruction: str
    files_scope: list[str] = []
    depends_on: list[str] = []
    max_turns: int = 50
    branch: str = ""


class SessionArtifact(BaseModel):
    session_id: str | None = None
    title: str
    description: str = ""
    agents: list[ArtifactAgentSchema]


class AgentSettingsUpdate(BaseModel):
    max_concurrent_agents: int | None = None
    default_max_turns: int | None = None
    auto_review_enabled: bool | None = None
    worktree_base_path: str | None = None
    turn_warning_threshold_pct: int | None = None


# --- DB update callback для ProjectCoordinator ---

async def _db_update(
    session_id: str,
    task_id: str | None,
    session_status: str | None = None,
    **kwargs: Any,
) -> None:
    """Callback from ProjectCoordinator to update DB."""
    async with AsyncSessionLocal() as db:
        if session_status:
            repo = AgentSessionRepository(db)
            await repo.update_status(session_id, session_status)
        if task_id:
            repo_t = AgentTaskRepository(db)
            await repo_t.update_task(task_id, **kwargs)


project_coordinator.set_db_update_callback(_db_update)


# --- Endpoints ---

@app.post("/admin/claude-code/session/validate")
async def validate_session_artifact(
    artifact: SessionArtifact,
    _user: dict = Depends(require_role("admin")),
) -> dict:
    """Validate artifact JSON before starting session."""
    errors = validate_artifact(artifact.model_dump())
    return {"valid": not errors, "errors": errors}


@app.post("/admin/claude-code/session/start")
async def start_agent_session(
    artifact: SessionArtifact,
    _user: dict = Depends(require_role("admin")),
    db: AsyncSession = Depends(get_db),
) -> dict:
    """Start a multi-agent session from artifact JSON."""
    # Валидация
    errors = validate_artifact(artifact.model_dump())
    if errors:
        raise HTTPException(status_code=422, detail={"errors": errors})

    # Проверить gh auth
    from git_worktree_manager import git_worktree_manager as gwm
    if not await gwm.check_gh_auth():
        raise HTTPException(
            status_code=503,
            detail="gh CLI not authenticated. Run: gh auth login"
        )

    # Проверить лимит параллельных агентов
    settings = await get_agent_settings(db)
    active_count = len(claude_code_manager.agents)
    if active_count >= settings.max_concurrent_agents:
        raise HTTPException(
            status_code=429,
            detail=f"Max concurrent agents limit ({settings.max_concurrent_agents}) reached"
        )

    # Создать запись сессии в БД
    import json as _json
    session_repo = AgentSessionRepository(db)
    task_repo = AgentTaskRepository(db)

    artifact_dict = artifact.model_dump()
    session_id = artifact.session_id or str(uuid.uuid4())[:8]
    artifact_dict["session_id"] = session_id

    from db.models import KanbanAgentSession, KanbanAgentTask
    db_session = KanbanAgentSession(
        id=session_id,
        title=artifact.title,
        artifact=_json.dumps(artifact_dict),
        status="running",
        created_by=_user.get("username", "admin"),
    )
    db.add(db_session)

    for agent in artifact.agents:
        branch = agent.branch or f"server/cc-{session_id}-{agent.id}"
        db_task = KanbanAgentTask(
            id=agent.id,
            session_id=session_id,
            title=agent.title,
            instruction=agent.instruction,
            files_scope=_json.dumps(agent.files_scope),
            depends_on=_json.dumps(agent.depends_on),
            max_turns=agent.max_turns or settings.default_max_turns,
            branch=branch,
            status="pending",
        )
        db.add(db_task)
        # Обновить branch в artifact
        artifact_dict["agents"] = [
            {**a, "branch": f"server/cc-{session_id}-{a['id']}"}
            if not a.get("branch") else a
            for a in artifact_dict["agents"]
        ]

    await db.commit()

    # Запустить координатор
    asyncio.create_task(
        project_coordinator.start_session(artifact_dict, _user.get("username", "admin"))
    )

    return {"session_id": session_id, "status": "started", "agents": len(artifact.agents)}


@app.post("/admin/claude-code/session/{session_id}/stop")
async def stop_agent_session(
    session_id: str,
    _user: dict = Depends(require_role("admin")),
    db: AsyncSession = Depends(get_db),
) -> dict:
    await project_coordinator.stop_session(session_id)
    repo = AgentSessionRepository(db)
    await repo.update_status(session_id, "stopped")
    return {"status": "stopped"}


@app.get("/admin/claude-code/sessions")
async def list_agent_sessions(
    _user: dict = Depends(require_role("operator")),
    db: AsyncSession = Depends(get_db),
) -> list[dict]:
    repo = AgentSessionRepository(db)
    sessions = await repo.get_all_with_tasks()
    result = []
    for s in sessions:
        result.append({
            "id": s.id,
            "title": s.title,
            "status": s.status,
            "created_by": s.created_by,
            "created_at": s.created_at.isoformat(),
            "completed_at": s.completed_at.isoformat() if s.completed_at else None,
            "tasks": [
                {
                    "id": t.id,
                    "title": t.title,
                    "status": t.status,
                    "turns_used": t.turns_used,
                    "max_turns": t.max_turns,
                    "files_changed": json.loads(t.files_changed or "[]"),
                    "current_action": t.current_action,
                    "pr_url": t.pr_url,
                    "pr_number": t.pr_number,
                    "branch": t.branch,
                    "agent_pid": t.agent_pid,
                    "started_at": t.started_at.isoformat() if t.started_at else None,
                    "completed_at": t.completed_at.isoformat() if t.completed_at else None,
                }
                for t in s.tasks
            ],
        })
    return result


@app.get("/admin/claude-code/sessions/{session_id}")
async def get_agent_session(
    session_id: str,
    _user: dict = Depends(require_role("operator")),
    db: AsyncSession = Depends(get_db),
) -> dict:
    repo = AgentSessionRepository(db)
    s = await repo.get_with_tasks(session_id)
    if not s:
        raise HTTPException(status_code=404, detail="Session not found")
    return {
        "id": s.id,
        "title": s.title,
        "status": s.status,
        "artifact": json.loads(s.artifact),
        "tasks": [{"id": t.id, "title": t.title, "status": t.status} for t in s.tasks],
    }


@app.get("/admin/claude-code/agents")
async def list_active_agents(
    _user: dict = Depends(require_role("operator")),
) -> list[dict]:
    return claude_code_manager.get_all_status()


@app.post("/admin/claude-code/{task_id}/pause")
async def pause_agent(
    task_id: str,
    _user: dict = Depends(require_role("admin")),
) -> dict:
    ok = await claude_code_manager.pause_agent(task_id)
    return {"status": "paused" if ok else "not_found"}


@app.post("/admin/claude-code/{task_id}/resume")
async def resume_agent(
    task_id: str,
    _user: dict = Depends(require_role("admin")),
) -> dict:
    ok = await claude_code_manager.resume_agent(task_id)
    return {"status": "resumed" if ok else "not_found"}


@app.delete("/admin/claude-code/{task_id}")
async def kill_agent(
    task_id: str,
    _user: dict = Depends(require_role("admin")),
    db: AsyncSession = Depends(get_db),
) -> dict:
    ok = await claude_code_manager.kill_agent(task_id)
    if ok:
        repo = AgentTaskRepository(db)
        await repo.update_task(task_id, status="failed")
    return {"status": "killed" if ok else "not_found"}


@app.get("/admin/claude-code/settings")
async def get_settings(
    _user: dict = Depends(require_role("admin")),
    db: AsyncSession = Depends(get_db),
) -> dict:
    settings = await get_agent_settings(db)
    return settings.model_dump()


@app.put("/admin/claude-code/settings")
async def update_settings(
    update: AgentSettingsUpdate,
    _user: dict = Depends(require_role("admin")),
    db: AsyncSession = Depends(get_db),
) -> dict:
    current = await get_agent_settings(db)
    patch = update.model_dump(exclude_none=True)
    updated = current.model_copy(update=patch)
    await save_agent_settings(db, updated)
    return updated.model_dump()


@app.get("/admin/claude-code/stream")
async def claude_code_sse_stream(
    _user: dict = Depends(require_role("operator")),
) -> StreamingResponse:
    """SSE stream for real-time agent progress."""
    queue: asyncio.Queue[dict] = asyncio.Queue(maxsize=100)

    async def on_event(data: dict) -> None:
        try:
            queue.put_nowait(data)
        except asyncio.QueueFull:
            pass  # drop if slow consumer

    claude_code_manager.register_sse_callback(on_event)

    async def event_generator():
        try:
            while True:
                try:
                    data = await asyncio.wait_for(queue.get(), timeout=25)
                    yield f"data: {json.dumps(data)}\n\n"
                except asyncio.TimeoutError:
                    yield "data: {\"type\":\"ping\"}\n\n"
        finally:
            claude_code_manager.unregister_sse_callback(on_event)

    return StreamingResponse(event_generator(), media_type="text/event-stream")
```

### ШАГ 9: Watchdog при старте orchestrator.py

Найти в `orchestrator.py` функцию `startup` или `lifespan` и добавить:

```python
# В startup/lifespan event:
async def _watchdog_on_startup() -> None:
    """Fix stuck 'running' tasks on restart."""
    async with AsyncSessionLocal() as db:
        from sqlalchemy import select
        from db.models import KanbanAgentTask
        result = await db.execute(
            select(KanbanAgentTask).where(KanbanAgentTask.status == "running")
        )
        running = result.scalars().all()
        if running:
            dead_ids = await claude_code_manager.watchdog_cleanup(
                [{"id": t.id, "agent_pid": t.agent_pid} for t in running]
            )
            for t in running:
                if t.id in dead_ids:
                    t.status = "blocked"
                    t.current_action = "Process died (server restart)"
            await db.commit()
            logger.info(f"Watchdog: marked {len(dead_ids)} tasks as blocked")

# Вызвать в startup:
asyncio.create_task(_watchdog_on_startup())
```

---

### ШАГ 10: Frontend — Pinia Store

Создать `admin/src/stores/claudeCode.ts`:

```typescript
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { useAuthStore } from './auth'

export interface AgentTaskState {
  id: string
  title: string
  status: 'pending' | 'running' | 'paused' | 'done' | 'blocked' | 'failed' | 'review_failed'
  turns_used: number
  max_turns: number
  files_changed_count: number
  files_changed: string[]
  current_action: string
  is_paused: boolean
  branch: string
  agent_pid: number | null
  pr_url: string | null
  pr_number: number | null
  started_at: string | null
  completed_at: string | null
}

export interface SessionState {
  id: string
  title: string
  status: string
  created_by: string
  created_at: string
  completed_at: string | null
  tasks: AgentTaskState[]
}

export interface AgentSettings {
  max_concurrent_agents: number
  default_max_turns: number
  auto_review_enabled: boolean
  worktree_base_path: string
  turn_warning_threshold_pct: number
}

export const useClaudeCodeStore = defineStore('claudeCode', () => {
  const sessions = ref<Record<string, SessionState>>({})
  const activeAgents = ref<Record<string, AgentTaskState>>({})
  const settings = ref<AgentSettings | null>(null)
  const isConnected = ref(false)

  let eventSource: EventSource | null = null
  let reconnectTimer: ReturnType<typeof setTimeout> | null = null

  const authStore = useAuthStore()

  // --- SSE ---
  function connectSSE() {
    if (eventSource) return
    eventSource = new EventSource('/admin/claude-code/stream', {
      // withCredentials если нужно
    })

    eventSource.onopen = () => {
      isConnected.value = true
    }

    eventSource.onmessage = (e) => {
      try {
        const data = JSON.parse(e.data)
        handleSSEEvent(data)
      } catch {}
    }

    eventSource.onerror = () => {
      isConnected.value = false
      eventSource?.close()
      eventSource = null
      reconnectTimer = setTimeout(connectSSE, 3000)
    }
  }

  function disconnectSSE() {
    eventSource?.close()
    eventSource = null
    if (reconnectTimer) clearTimeout(reconnectTimer)
    isConnected.value = false
  }

  function handleSSEEvent(data: Record<string, unknown>) {
    const type = data.type as string
    const taskId = data.task_id as string | undefined
    const sessionId = data.session_id as string | undefined

    if (type === 'agent_update' && taskId) {
      // Обновить активный агент
      activeAgents.value[taskId] = {
        ...(activeAgents.value[taskId] || {}),
        ...data,
      } as AgentTaskState

      // Обновить задачу в сессии
      if (sessionId && sessions.value[sessionId]) {
        const task = sessions.value[sessionId].tasks.find(t => t.id === taskId)
        if (task) Object.assign(task, data)
      }
    }

    if (type === 'agent_finished' && taskId) {
      delete activeAgents.value[taskId]
      if (sessionId && sessions.value[sessionId]) {
        const task = sessions.value[sessionId].tasks.find(t => t.id === taskId)
        if (task) {
          task.status = data.status as string as AgentTaskState['status']
        }
      }
      // Перезагрузить сессии после завершения
      loadSessions()
    }

    if (type === 'agent_paused' && taskId) {
      if (activeAgents.value[taskId]) activeAgents.value[taskId].is_paused = true
    }
    if (type === 'agent_resumed' && taskId) {
      if (activeAgents.value[taskId]) activeAgents.value[taskId].is_paused = false
    }
  }

  // --- API calls ---
  async function loadSessions() {
    const res = await fetch('/admin/claude-code/sessions', {
      headers: { Authorization: `Bearer ${authStore.token}` },
    })
    if (res.ok) {
      const data: SessionState[] = await res.json()
      sessions.value = Object.fromEntries(data.map(s => [s.id, s]))
    }
  }

  async function validateArtifact(artifact: Record<string, unknown>) {
    const res = await fetch('/admin/claude-code/session/validate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${authStore.token}`,
      },
      body: JSON.stringify(artifact),
    })
    return res.json() as Promise<{ valid: boolean; errors: string[] }>
  }

  async function startSession(artifact: Record<string, unknown>) {
    const res = await fetch('/admin/claude-code/session/start', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${authStore.token}`,
      },
      body: JSON.stringify(artifact),
    })
    if (!res.ok) throw new Error(await res.text())
    await loadSessions()
    return res.json()
  }

  async function stopSession(sessionId: string) {
    await fetch(`/admin/claude-code/session/${sessionId}/stop`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${authStore.token}` },
    })
    await loadSessions()
  }

  async function pauseAgent(taskId: string) {
    await fetch(`/admin/claude-code/${taskId}/pause`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${authStore.token}` },
    })
  }

  async function resumeAgent(taskId: string) {
    await fetch(`/admin/claude-code/${taskId}/resume`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${authStore.token}` },
    })
  }

  async function killAgent(taskId: string) {
    await fetch(`/admin/claude-code/${taskId}`, {
      method: 'DELETE',
      headers: { Authorization: `Bearer ${authStore.token}` },
    })
  }

  async function loadSettings() {
    const res = await fetch('/admin/claude-code/settings', {
      headers: { Authorization: `Bearer ${authStore.token}` },
    })
    if (res.ok) settings.value = await res.json()
  }

  async function updateSettings(patch: Partial<AgentSettings>) {
    const res = await fetch('/admin/claude-code/settings', {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${authStore.token}`,
      },
      body: JSON.stringify(patch),
    })
    if (res.ok) settings.value = await res.json()
  }

  // --- Computed ---
  const activeCount = computed(() => Object.keys(activeAgents.value).length)
  const sessionList = computed(() => Object.values(sessions.value))
  const runningSessions = computed(() =>
    sessionList.value.filter(s => s.status === 'running')
  )

  return {
    sessions,
    activeAgents,
    settings,
    isConnected,
    activeCount,
    sessionList,
    runningSessions,
    connectSSE,
    disconnectSSE,
    loadSessions,
    validateArtifact,
    startSession,
    stopSession,
    pauseAgent,
    resumeAgent,
    killAgent,
    loadSettings,
    updateSettings,
  }
})
```

### ШАГ 11: Frontend — AgentKanbanView.vue (15-я вкладка)

Создать `admin/src/views/AgentKanbanView.vue`:

```vue
<template>
  <div class="p-6 space-y-6">
    <!-- Header -->
    <div class="flex items-center justify-between">
      <div>
        <h1 class="text-2xl font-bold text-gray-900 dark:text-white flex items-center gap-2">
          🤖 {{ $t('agents.title') }}
        </h1>
        <p class="text-sm text-gray-500 mt-1">
          {{ $t('agents.subtitle') }}
          <span class="ml-2 px-2 py-0.5 bg-orange-100 text-orange-700 rounded-full text-xs font-medium">
            {{ store.activeCount }} {{ $t('agents.active') }}
          </span>
          <span
            class="ml-1 w-2 h-2 rounded-full inline-block"
            :class="store.isConnected ? 'bg-green-500' : 'bg-red-500'"
          />
        </p>
      </div>
      <div class="flex gap-2">
        <button
          @click="showSettings = !showSettings"
          class="btn btn-secondary text-sm"
        >
          ⚙️ {{ $t('agents.settings') }}
        </button>
        <button @click="openNewSession" class="btn btn-primary text-sm">
          ＋ {{ $t('agents.newSession') }}
        </button>
      </div>
    </div>

    <!-- Settings Panel (collapsible) -->
    <AgentSettingsPanel v-if="showSettings" @close="showSettings = false" />

    <!-- New Session Modal -->
    <NewSessionModal
      v-if="showNewSession"
      @close="showNewSession = false"
      @started="onSessionStarted"
    />

    <!-- Empty state -->
    <div
      v-if="store.sessionList.length === 0"
      class="text-center py-20 text-gray-400"
    >
      <div class="text-6xl mb-4">🤖</div>
      <p class="text-xl font-medium">{{ $t('agents.noSessions') }}</p>
      <p class="mt-2 text-sm">{{ $t('agents.noSessionsHint') }}</p>
    </div>

    <!-- Sessions Board (Kanban-like columns by status) -->
    <div v-else class="space-y-4">
      <!-- Running sessions first -->
      <div
        v-for="session in store.sessionList"
        :key="session.id"
      >
        <SessionCard :session="session" />
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'
import { useClaudeCodeStore } from '@/stores/claudeCode'
import SessionCard from '@/components/agents/SessionCard.vue'
import AgentSettingsPanel from '@/components/agents/AgentSettingsPanel.vue'
import NewSessionModal from '@/components/agents/NewSessionModal.vue'

const store = useClaudeCodeStore()
const showSettings = ref(false)
const showNewSession = ref(false)

function openNewSession() {
  showNewSession.value = true
}

function onSessionStarted() {
  showNewSession.value = false
}

onMounted(async () => {
  store.connectSSE()
  await store.loadSessions()
  await store.loadSettings()
})

onUnmounted(() => {
  // Не отключаем SSE — он нужен глобально
})
</script>
```

### ШАГ 12: Frontend — SessionCard.vue компонент

Создать `admin/src/components/agents/SessionCard.vue`:

```vue
<template>
  <div
    class="rounded-xl border shadow-sm overflow-hidden"
    :class="cardClass"
  >
    <!-- Session header -->
    <div class="px-4 py-3 flex items-center justify-between">
      <div class="flex items-center gap-3">
        <span class="text-lg">{{ statusIcon(session.status) }}</span>
        <div>
          <h3 class="font-semibold text-gray-900 dark:text-white">
            {{ session.title }}
          </h3>
          <p class="text-xs text-gray-500">
            ID: {{ session.id }} · {{ session.created_by }} ·
            {{ formatDate(session.created_at) }}
          </p>
        </div>
      </div>

      <div class="flex items-center gap-2">
        <!-- Общий прогресс -->
        <div class="flex items-center gap-2 mr-3">
          <div class="w-24 bg-gray-200 rounded-full h-2">
            <div
              class="h-2 rounded-full transition-all duration-700"
              :class="progressBarClass"
              :style="{ width: `${overallProgress}%` }"
            />
          </div>
          <span class="text-xs text-gray-500 whitespace-nowrap">
            {{ completedCount }}/{{ session.tasks.length }}
          </span>
        </div>

        <!-- Контролы -->
        <button
          v-if="session.status === 'running'"
          @click="stopSession"
          class="btn btn-sm bg-red-100 text-red-700 hover:bg-red-200"
        >
          ⛔ {{ $t('agents.stopAll') }}
        </button>
        <button
          @click="expanded = !expanded"
          class="btn btn-sm btn-secondary"
        >
          {{ expanded ? '▲' : '▼' }}
        </button>
      </div>
    </div>

    <!-- Tasks list -->
    <div v-if="expanded" class="border-t divide-y dark:divide-gray-700">
      <AgentTaskRow
        v-for="task in session.tasks"
        :key="task.id"
        :task="task"
        :session-id="session.id"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue'
import type { SessionState } from '@/stores/claudeCode'
import { useClaudeCodeStore } from '@/stores/claudeCode'
import AgentTaskRow from './AgentTaskRow.vue'

const props = defineProps<{ session: SessionState }>()
const store = useClaudeCodeStore()
const expanded = ref(true)

const completedCount = computed(() =>
  props.session.tasks.filter(t =>
    ['done', 'merged'].includes(t.status)
  ).length
)

const overallProgress = computed(() =>
  props.session.tasks.length > 0
    ? (completedCount.value / props.session.tasks.length) * 100
    : 0
)

const cardClass = computed(() => ({
  'border-orange-300 bg-orange-50/30 dark:bg-orange-900/10': props.session.status === 'running',
  'border-green-300 bg-green-50/30': props.session.status === 'completed',
  'border-red-300 bg-red-50/30': props.session.status === 'failed',
  'border-gray-200 bg-gray-50/30': props.session.status === 'stopped',
}))

const progressBarClass = computed(() => ({
  'bg-orange-500': props.session.status === 'running',
  'bg-green-500': props.session.status === 'completed',
  'bg-red-500': props.session.status === 'failed',
}))

const statusIcon = (s: string) => ({
  running: '⚙️', completed: '✅', failed: '❌', stopped: '⏹️',
}[s] ?? '❓')

const formatDate = (iso: string) =>
  new Date(iso).toLocaleString('ru-RU', { dateStyle: 'short', timeStyle: 'short' })

async function stopSession() {
  if (!confirm(`Остановить все агенты сессии "${props.session.title}"?`)) return
  await store.stopSession(props.session.id)
}
</script>
```

### ШАГ 13: Frontend — AgentTaskRow.vue

Создать `admin/src/components/agents/AgentTaskRow.vue`:

```vue
<template>
  <div
    class="px-4 py-3 flex items-start gap-3"
    :class="rowClass"
  >
    <!-- Status icon -->
    <span class="text-xl mt-0.5 flex-shrink-0">{{ statusIcon }}</span>

    <!-- Content -->
    <div class="flex-1 min-w-0">
      <div class="flex items-center gap-2 flex-wrap">
        <span class="font-medium text-sm text-gray-900 dark:text-white">
          {{ task.title }}
        </span>
        <span class="text-xs text-gray-400 font-mono">{{ task.id }}</span>

        <!-- PR link -->
        <a
          v-if="task.pr_url"
          :href="task.pr_url"
          target="_blank"
          class="text-xs text-blue-600 hover:underline"
        >
          🔀 PR #{{ task.pr_number }}
        </a>
      </div>

      <!-- Progress bar (running only) -->
      <div v-if="task.status === 'running'" class="mt-2 flex items-center gap-2">
        <div class="flex-1 bg-gray-200 rounded-full h-1.5 max-w-xs">
          <div
            class="h-1.5 rounded-full transition-all duration-500"
            :class="task.turns_used / task.max_turns > 0.8
              ? 'bg-red-500' : 'bg-blue-500'"
            :style="{ width: `${Math.min((task.turns_used / task.max_turns) * 100, 100)}%` }"
          />
        </div>
        <span class="text-xs text-gray-500 whitespace-nowrap">
          {{ task.turns_used }}/{{ task.max_turns }} turns
        </span>
        <span class="text-xs text-gray-400">
          📁 {{ task.files_changed_count }}
        </span>
      </div>

      <!-- Current action -->
      <p
        v-if="task.status === 'running' && task.current_action"
        class="text-xs text-gray-500 italic mt-1 truncate"
      >
        {{ task.current_action }}
      </p>

      <!-- Branch -->
      <p v-if="task.branch" class="text-xs text-gray-400 mt-1 font-mono">
        🔀 {{ task.branch }}
      </p>
    </div>

    <!-- Controls (running only) -->
    <div v-if="task.status === 'running'" class="flex gap-1 flex-shrink-0">
      <button
        v-if="!task.is_paused"
        @click="pause"
        class="btn btn-xs bg-yellow-100 text-yellow-700 hover:bg-yellow-200"
        title="Пауза"
      >⏸</button>
      <button
        v-else
        @click="resume"
        class="btn btn-xs bg-green-100 text-green-700 hover:bg-green-200"
        title="Продолжить"
      >▶️</button>
      <button
        @click="kill"
        class="btn btn-xs bg-red-100 text-red-700 hover:bg-red-200"
        title="Остановить"
      >⛔</button>
    </div>
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import type { AgentTaskState } from '@/stores/claudeCode'
import { useClaudeCodeStore } from '@/stores/claudeCode'

const props = defineProps<{
  task: AgentTaskState
  sessionId: string
}>()

const store = useClaudeCodeStore()

const statusIcon = computed(() => ({
  pending: '⏳',
  running: props.task.is_paused ? '⏸️' : '⚙️',
  paused: '⏸️',
  done: '✅',
  blocked: '🚫',
  failed: '❌',
  review_failed: '⚠️',
}[props.task.status] ?? '❓'))

const rowClass = computed(() => ({
  'bg-blue-50/50 dark:bg-blue-900/10': props.task.status === 'running' && !props.task.is_paused,
  'bg-yellow-50/50': props.task.is_paused,
  'bg-green-50/50': props.task.status === 'done',
  'bg-red-50/50': ['failed', 'blocked', 'review_failed'].includes(props.task.status),
}))

async function pause() { await store.pauseAgent(props.task.id) }
async function resume() { await store.resumeAgent(props.task.id) }
async function kill() {
  if (!confirm(`Остановить агент "${props.task.title}"?`)) return
  await store.killAgent(props.task.id)
}
</script>
```

### ШАГ 14: Frontend — AgentSettingsPanel.vue

Создать `admin/src/components/agents/AgentSettingsPanel.vue`:

```vue
<template>
  <div class="rounded-xl border border-gray-200 bg-white dark:bg-gray-800 p-5 shadow-sm">
    <div class="flex items-center justify-between mb-4">
      <h3 class="font-semibold text-gray-900 dark:text-white">
        ⚙️ {{ $t('agents.settingsTitle') }}
      </h3>
      <button @click="$emit('close')" class="text-gray-400 hover:text-gray-600">✕</button>
    </div>

    <div v-if="form" class="grid grid-cols-1 md:grid-cols-2 gap-4">
      <div>
        <label class="label">{{ $t('agents.maxConcurrent') }}</label>
        <input
          v-model.number="form.max_concurrent_agents"
          type="number" min="1" max="50"
          class="input"
        />
      </div>
      <div>
        <label class="label">{{ $t('agents.defaultMaxTurns') }}</label>
        <input
          v-model.number="form.default_max_turns"
          type="number" min="5" max="500"
          class="input"
        />
      </div>
      <div>
        <label class="label">{{ $t('agents.turnWarning') }} ({{ form.turn_warning_threshold_pct }}%)</label>
        <input
          v-model.number="form.turn_warning_threshold_pct"
          type="range" min="10" max="99"
          class="w-full"
        />
      </div>
      <div class="flex items-center gap-3">
        <input
          v-model="form.auto_review_enabled"
          type="checkbox" id="auto-review"
          class="w-4 h-4"
        />
        <label for="auto-review" class="label mb-0">
          {{ $t('agents.autoReview') }}
        </label>
      </div>
      <div class="md:col-span-2">
        <label class="label">{{ $t('agents.worktreePath') }}</label>
        <input v-model="form.worktree_base_path" type="text" class="input font-mono" />
      </div>
    </div>

    <div class="flex gap-2 mt-4 justify-end">
      <button @click="$emit('close')" class="btn btn-secondary">
        {{ $t('common.cancel') }}
      </button>
      <button @click="save" :disabled="saving" class="btn btn-primary">
        {{ saving ? $t('common.saving') : $t('common.save') }}
      </button>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, watch, onMounted } from 'vue'
import { useClaudeCodeStore } from '@/stores/claudeCode'
import type { AgentSettings } from '@/stores/claudeCode'

defineEmits<{ close: [] }>()

const store = useClaudeCodeStore()
const form = ref<AgentSettings | null>(null)
const saving = ref(false)

onMounted(async () => {
  await store.loadSettings()
  form.value = store.settings ? { ...store.settings } : null
})

watch(() => store.settings, (s) => {
  if (s && !form.value) form.value = { ...s }
})

async function save() {
  if (!form.value) return
  saving.value = true
  try {
    await store.updateSettings(form.value)
  } finally {
    saving.value = false
  }
}
</script>
```

### ШАГ 15: Frontend — NewSessionModal.vue

Создать `admin/src/components/agents/NewSessionModal.vue`:

```vue
<template>
  <div class="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
    <div class="bg-white dark:bg-gray-800 rounded-xl shadow-2xl w-full max-w-2xl mx-4 max-h-[90vh] overflow-y-auto">
      <div class="p-5 border-b flex items-center justify-between">
        <h2 class="text-lg font-semibold">🤖 Новая агентская сессия</h2>
        <button @click="$emit('close')" class="text-gray-400 hover:text-gray-600">✕</button>
      </div>

      <div class="p-5 space-y-4">
        <p class="text-sm text-gray-600 dark:text-gray-400">
          Вставьте JSON-артефакт сессии, сгенерированный Claude в чате.
        </p>

        <textarea
          v-model="artifactJson"
          rows="15"
          placeholder='{"session_id": "...", "title": "...", "agents": [...]}'
          class="w-full font-mono text-xs border rounded-lg p-3 bg-gray-50 dark:bg-gray-900 resize-none focus:outline-none focus:ring-2 focus:ring-orange-400"
          :class="{ 'border-red-400': parseError }"
        />

        <p v-if="parseError" class="text-xs text-red-600">{{ parseError }}</p>

        <!-- Validation errors -->
        <div v-if="validationErrors.length > 0" class="bg-red-50 rounded-lg p-3">
          <p class="text-sm font-medium text-red-700 mb-1">Ошибки валидации:</p>
          <ul class="text-xs text-red-600 space-y-0.5">
            <li v-for="e in validationErrors" :key="e">• {{ e }}</li>
          </ul>
        </div>

        <!-- Preview -->
        <div v-if="parsed && !validationErrors.length" class="bg-green-50 rounded-lg p-3">
          <p class="text-sm font-medium text-green-700">✅ Артефакт валиден</p>
          <p class="text-xs text-green-600 mt-1">
            Сессия: {{ parsed.title }} · {{ parsed.agents?.length }} агентов
          </p>
          <ul class="mt-2 space-y-1">
            <li
              v-for="a in parsed.agents"
              :key="a.id"
              class="text-xs text-gray-600"
            >
              • <b>{{ a.id }}</b>: {{ a.title }}
              {{ a.depends_on?.length ? `(зависит от: ${a.depends_on.join(', ')})` : '' }}
            </li>
          </ul>
        </div>
      </div>

      <div class="p-5 border-t flex gap-2 justify-end">
        <button @click="$emit('close')" class="btn btn-secondary">Отмена</button>
        <button
          @click="validate"
          :disabled="!artifactJson || validating"
          class="btn btn-secondary"
        >
          {{ validating ? 'Проверяю...' : 'Проверить' }}
        </button>
        <button
          @click="start"
          :disabled="!parsed || validationErrors.length > 0 || starting"
          class="btn btn-primary"
        >
          {{ starting ? 'Запускаю...' : '🚀 Запустить' }}
        </button>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue'
import { useClaudeCodeStore } from '@/stores/claudeCode'

const emit = defineEmits<{ close: []; started: [] }>()

const store = useClaudeCodeStore()
const artifactJson = ref('')
const parsed = ref<Record<string, unknown> | null>(null)
const parseError = ref('')
const validationErrors = ref<string[]>([])
const validating = ref(false)
const starting = ref(false)

watch(artifactJson, (val) => {
  parseError.value = ''
  validationErrors.value = []
  parsed.value = null
  try {
    if (val.trim()) parsed.value = JSON.parse(val)
  } catch (e) {
    parseError.value = 'Невалидный JSON: ' + (e as Error).message
  }
})

async function validate() {
  if (!parsed.value) return
  validating.value = true
  try {
    const result = await store.validateArtifact(parsed.value)
    validationErrors.value = result.errors || []
  } finally {
    validating.value = false
  }
}

async function start() {
  if (!parsed.value || validationErrors.value.length > 0) return
  starting.value = true
  try {
    await store.startSession(parsed.value)
    emit('started')
  } catch (e) {
    validationErrors.value = [(e as Error).message]
  } finally {
    starting.value = false
  }
}
</script>
```

### ШАГ 16: Router и Sidebar

В `admin/src/router/index.ts` добавить маршрут:
```typescript
{
  path: '/agents',
  name: 'agents',
  component: () => import('@/views/AgentKanbanView.vue'),
  meta: { requiresAuth: true, role: 'operator' },
},
```

В sidebar/navigation добавить пункт `{ icon: 'Bot', label: 'agents.title', to: '/agents' }`.

### ШАГ 17: i18n ключи

В `admin/src/plugins/i18n/ru.ts` добавить:
```typescript
agents: {
  title: 'Агенты',
  subtitle: 'Мультиагентная оркестрация Claude Code',
  active: 'активных',
  settings: 'Настройки',
  newSession: 'Новая сессия',
  noSessions: 'Нет сессий',
  noSessionsHint: 'Создайте сессию через кнопку "Новая сессия"',
  stopAll: 'Стоп всех',
  settingsTitle: 'Настройки агентов',
  maxConcurrent: 'Макс. параллельных агентов',
  defaultMaxTurns: 'Макс. turns по умолчанию',
  turnWarning: 'Порог предупреждения',
  autoReview: 'Авто-ревью перед merge',
  worktreePath: 'Путь для worktrees',
},
```

---

## ТЕСТИРОВАНИЕ (обязательно после каждого шага)

### Backend тесты

```bash
cd /opt/ai-secretary
source venv/bin/activate

# Линтер
ruff check . --fix
ruff format .

# Проверка типов
mypy claude_code_manager.py project_coordinator.py git_worktree_manager.py agent_settings_manager.py --ignore-missing-imports

# Тест импортов
python -c "
from claude_code_manager import claude_code_manager
from project_coordinator import project_coordinator, validate_artifact
from git_worktree_manager import GitWorktreeManager
from agent_settings_manager import AgentSettings
print('✅ All imports OK')
"

# Тест валидации артефакта
python -c "
from project_coordinator import validate_artifact
# Валидный артефакт
ok = validate_artifact({'agents': [
  {'id': 'a1', 'title': 'T1', 'instruction': 'I1', 'files_scope': ['f1.py'], 'depends_on': [], 'max_turns': 10},
  {'id': 'a2', 'title': 'T2', 'instruction': 'I2', 'files_scope': ['f2.py'], 'depends_on': ['a1'], 'max_turns': 10},
]})
assert ok == [], f'Expected no errors: {ok}'

# Артефакт с циклом
bad = validate_artifact({'agents': [
  {'id': 'a1', 'files_scope': ['f1.py'], 'depends_on': ['a2'], 'title': '', 'instruction': '', 'max_turns': 10},
  {'id': 'a2', 'files_scope': ['f2.py'], 'depends_on': ['a1'], 'title': '', 'instruction': '', 'max_turns': 10},
]})
assert any('Circular' in e for e in bad), f'Expected cycle error: {bad}'

# Артефакт с конфликтом файлов
conflict = validate_artifact({'agents': [
  {'id': 'a1', 'files_scope': ['same.py'], 'depends_on': [], 'title': '', 'instruction': '', 'max_turns': 10},
  {'id': 'a2', 'files_scope': ['same.py'], 'depends_on': [], 'title': '', 'instruction': '', 'max_turns': 10},
]})
assert any('conflict' in e.lower() for e in conflict), f'Expected conflict: {conflict}'
print('✅ Validation tests passed')
"

# Тест миграции БД
venv/bin/alembic upgrade head
sqlite3 data/secretary.db ".tables" | tr ' ' '\n' | grep kanban_agent

# Тест API (запустить сервер и проверить)
systemctl restart ai-secretary
sleep 3
curl -s http://localhost:8002/health | python -m json.tool

# Получить токен admin и проверить endpoints
TOKEN=$(curl -s -X POST http://localhost:8002/admin/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"YOUR_PASS"}' | python -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# Settings
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8002/admin/claude-code/settings | python -m json.tool

# Sessions (должен вернуть [])
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8002/admin/claude-code/sessions | python -m json.tool

# Validate artifact
curl -s -X POST http://localhost:8002/admin/claude-code/session/validate \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Test",
    "agents": [
      {"id": "t1", "title": "T1", "instruction": "Test instruction", "files_scope": ["test.py"], "depends_on": [], "max_turns": 5}
    ]
  }' | python -m json.tool
# Ожидаем: {"valid": true, "errors": []}

echo "✅ API tests passed"
```

### Frontend тесты

```bash
cd /opt/ai-secretary/admin

# Линтер
npx eslint src/stores/claudeCode.ts src/views/AgentKanbanView.vue \
  src/components/agents/ --fix

# TypeScript проверка
npx vue-tsc --noEmit

# Сборка
npm run build
echo "✅ Frontend build OK"
```

---

## ЦИКЛ САМОИСПРАВЛЕНИЯ

Если что-то не работает — действуй по этому алгоритму:

```
1. Запусти тест → получи ошибку
2. Прочитай ошибку полностью
3. Найди файл и строку
4. Исправь
5. Запусти тест снова
6. Повторяй пока все тесты зелёные
```

Типичные проблемы и решения:

**`ImportError: cannot import name X`**
→ Проверь что модуль создан, нет опечаток в имени

**`alembic: Can't locate revision`**
→ `venv/bin/alembic stamp head` затем снова `upgrade head`

**`gh: not logged in`**
→ `gh auth login` (интерактивно)

**`git worktree: already exists`**
→ `git worktree list` → `git worktree remove /tmp/cc-agents/agent-XXX --force`

**`StreamingResponse not defined`**
→ Добавить в imports: `from fastapi.responses import StreamingResponse`

**`uuid not defined`**
→ Добавить `import uuid` в orchestrator.py

**Vue: `Property X does not exist`**
→ Добавить поле в соответствующий interface в `claudeCode.ts`

---

## ФИНАЛЬНАЯ ПРОВЕРКА

После всех шагов:

```bash
# 1. Все тесты проходят
cd /opt/ai-secretary && source venv/bin/activate
python -m pytest tests/ -x -q 2>/dev/null || echo "no tests yet"

# 2. Сервис работает
systemctl is-active ai-secretary && curl -sf http://localhost:8002/health

# 3. Новые таблицы созданы
sqlite3 data/secretary.db "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'kanban_agent%';"
# Ожидаем: kanban_agent_sessions, kanban_agent_tasks

# 4. Endpoints отвечают
TOKEN=$(curl -s -X POST http://localhost:8002/admin/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"YOUR_PASS"}' \
  | python -c "import sys,json; print(json.load(sys.stdin).get('access_token',''))")

for endpoint in \
  "GET /admin/claude-code/settings" \
  "GET /admin/claude-code/sessions" \
  "GET /admin/claude-code/agents"; do
  method=$(echo $endpoint | cut -d' ' -f1)
  path=$(echo $endpoint | cut -d' ' -f2)
  code=$(curl -s -o /dev/null -w "%{http_code}" \
    -X "$method" "http://localhost:8002$path" \
    -H "Authorization: Bearer $TOKEN")
  echo "$code $endpoint"
done
# Все должны вернуть 200

# 5. Frontend собран и 15-я вкладка доступна
grep -r "AgentKanban\|/agents" admin/src/router/ && echo "✅ Route exists"
ls admin/dist/assets/*.js | head -3

echo ""
echo "🎉 Система мультиагентной оркестрации готова!"
echo "Откройте Admin Panel → вкладка 'Агенты'"
```

---

## ИТОГ: ЧТО РЕАЛИЗОВАНО

```
Backend:
✅ claude_code_manager.py    — управление claude CLI процессами
✅ project_coordinator.py    — координация сессий, DAG, file locks
✅ git_worktree_manager.py   — изоляция агентов в worktrees
✅ agent_settings_manager.py — CRUD настроек через system_config
✅ db/models.py              — 2 новые модели (Session + Task)
✅ db/repositories/agent_session.py
✅ alembic миграция
✅ 11 новых endpoints в orchestrator.py
✅ SSE stream реального времени
✅ Watchdog при старте

Frontend:
✅ stores/claudeCode.ts           — Pinia store + SSE
✅ views/AgentKanbanView.vue      — 15-я вкладка
✅ components/agents/SessionCard.vue
✅ components/agents/AgentTaskRow.vue  — бегунок + контролы
✅ components/agents/AgentSettingsPanel.vue — CRUD настроек
✅ components/agents/NewSessionModal.vue   — вставка артефакта
✅ router + sidebar обновлены
✅ i18n ключи (ru/en)
```