Диагностика

Большинство проблем команды попадает в четыре группы: runtime setup, launch confirmation, task parsing и provider limits.

Команда не запускается

Проверьте последовательно:

1. Runtime установлен — выбранный CLI (claude, codex, opencode) установлен
2. Доступен в PATH — бинарник доступен в переменной окружения PATH
3. Доступ к модели — у провайдера есть доступ к запрошенной модели (особенно для OpenCode, важны точные имена провайдера и модели)
4. Путь к проекту — директория проекта существует и доступна для чтения
5. Сеть / VPN — некоторые провайдеры блокируют трафик при активном VPN

TIP

Запустите бинарник рантайма в терминале, чтобы проверить PATH и авторизацию. Например: claude --version или opencode --version.

OpenCode: registered, но bootstrap не подтверждён

Если OpenCode показывает registered, но bootstrap не подтверждён, сначала inspect artifacts, прежде чем менять team prompts.

Contributor/debugging details находятся в Архитектуре для контрибьюторов, где есть ссылка на canonical debugging runbook для agent teams.

Посмотрите на последний artifact неудачного запуска:

~/.claude/teams/<team>/launch-failure-artifacts/latest.json

Манифест внутри включает:

• classification — почему запуск считался неудачным
• bootstrapTransportBreadcrumb — использованный путь доставки
• Статусы старта участников
• Редактированные логи и трейсы

Также проверьте lane manifest:

jq '.lanes' ~/.claude/teams/<team>/.opencode-runtime/lanes.json
jq '.activeRunId, .entries' ~/.claude/teams/<team>/.opencode-runtime/lanes/<lane>/manifest.json

Не гадайте по UI

Всегда сопоставляйте UI-диагностику с сохранёнными файлами (launch-state.json, bootstrap-journal.jsonl) и runtime-специфичными доказательствами.

Общая диагностика

Начинайте с сохранённых файлов на диске, а не только с UI.

Корневая директория команды

~/.claude/teams/<team>/

Ключевые файлы и что они показывают:

• launch-state.json — состояние запуска/активности участников (.teamLaunchState, .summary, .members)
• bootstrap-journal.jsonl — упорядоченные события bootstrap от CLI/runtime (tail -80)
• bootstrap-state.json — сводка фазы bootstrap
• config.json — конфигурация провайдера, модели и проекта
• inboxes/*.json и sentMessages.json — состояние доставки сообщений

jq '.teamLaunchState, .summary, .members' ~/.claude/teams/<team>/launch-state.json
tail -80 ~/.claude/teams/<team>/bootstrap-journal.jsonl 2>/dev/null

OpenCode runtime evidence

Для OpenCode участников доказательство сессии находится в lane runtime store:

• .opencode-runtime/lanes.json — индекс lane с состоянием
• .opencode-runtime/lanes/<lane>/manifest.json — activeRunId и записи evidence
• .opencode-runtime/lanes/<lane>/opencode-sessions.json — зафиксированные записи сессий

Ожидаемое здоровое состояние: состояние lane active, manifest содержит activeRunId хотя бы с одной записью evidence, участник имеет bootstrapConfirmed: true.

jq '.lanes' ~/.claude/teams/<team>/.opencode-runtime/lanes.json 2>/dev/null
find ~/.claude/teams/<team>/.opencode-runtime -maxdepth 3 -type f | sort

Артефакты неудачного запуска

Когда запуск помечен как неудачный, проверьте latest.json:

~/.claude/teams/<team>/launch-failure-artifacts/latest.json

Манифест включает:

• classification — почему запуск считался неудачным
• bootstrapTransportBreadcrumb — использованный путь доставки
• Статусы старта участников и редактированные логи/трейсы

Не видны ответы агента

Откройте task logs и teammate messages. Пропавшие replies часто связаны с:

• Runtime delivery retry — агент мог ответить, но сообщение не доставлено в приложение. Проверьте delivery ledger.
• Parsing или filtering — вывод агента не содержал ожидаемых маркеров или task references.
• Task attribution — работа выполнялась в рамках сессии, но не была привязана к задаче, потому что в выводе отсутствовал корректный task id.

Не считайте молчание игнорированием

Не считайте, что модель проигнорировала сообщение, пока это не подтверждено логами.

Changes не связаны с tasks

Используйте task-specific logs и code review links. Если diff выглядит detached:

• Проверьте, был ли task id или task reference в output агента.
• Убедитесь, что агент вызвал task_add_comment перед правками.
• Убедитесь, что агент вызвал task_start, чтобы доска знала о начале работы.

Для OpenCode teammates авторитетным доказательством принадлежности сессии к задаче служат opencode-sessions.json и запись в lane manifest, а не только UI message stream.

Rate limits

Если провайдер сообщает известное время сброса (reset time), Agent Teams может подтолкнуть lead продолжить после cooldown. Если reset time неизвестен, подождите или смените provider/runtime path.

Поведение провайдера	Рекомендуемое действие
Отображается известное reset time	Дождитесь cooldown и продолжите
Reset time не показан	Смените провайдера или runtime path
Повторяющиеся 429	Снизьте concurrency или используйте другую model lane

Проблемы авторизации CLI

claude login не сохраняется

Если CLI авторизован в одном терминале, но приложение говорит, что нет — проверьте, что auth сохранён по ожидаемому пути конфигурации, и что процесс приложения видит тот же $HOME.

OpenCode: ключ провайдера отклонён

• Убедитесь, что имя провайдера в config.json совпадает с префиксом провайдера в строке модели
• Проверьте, что ключ не просрочен и не отозван в dashboard провайдера

Диагностический лог авторизации

Каждый вызов CliInstallerService.getStatus() дописывает одну строку в claude-cli-auth-diag.ndjson в папке логов Electron (обычно ~/Library/Logs/<product-name>/ на macOS). Если файл превышает 512 KiB, он обнуляется перед следующей записью.

Проверьте этот файл, если видите «Not logged in» или ошибки авторизации в упакованном приложении.

Lane bootstrap stuck

Для OpenCode secondary lanes:

• Отсутствие inboxes/<member>.json автоматически не является багом. OpenCode lanes не обязаны быть созданы через primary inbox перед стартом.
• Если UI показывает, что команда всё ещё запускается, в то время как primary participants уже работоспособны, ожидание «all teammates joined» связано с secondary lanes.
• Если зависает Prepared communication channels for X/Y members, проверьте, не включает ли Y некорректно secondary OpenCode members.

Lane manifest empty entries

Если bridge сообщает, что bootstrap успешен, но manifest.json показывает entries: [], проблема в evidence commit, а не в поведении модели. Участник не должен считаться deliverable, пока opencode-sessions.json и запись в manifest не существуют.

Распространённые состояния member

Состояние	Значение
confirmed_alive + bootstrapConfirmed	Здоров и готов к работе
registered / runtime_pending_bootstrap	Процесс или lane существует, но bootstrap proof ещё не закоммичен
failed_to_start + runtime_process	Процесс есть, но launch gate не прошёл. Смотрите diagnostics
failed_to_start + stale_metadata	Сохранённый pid/session устарел или мёртв

WARNING

member_briefing сам по себе НЕ является runtime evidence. Для OpenCode авторитетным доказательством служит committed runtime evidence, такая как opencode-sessions.json и запись в manifest.

Режим отладки рантайма

Для локальной отладки можно принудительно запускать teammates в tmux-панелях:

# Запуск из терминала
CLAUDE_TEAM_TEAMMATE_MODE=tmux pnpm dev

# Или добавьте в custom CLI args
--teammate-mode tmux

Используйте это для инспекции интерактивного поведения CLI. Не считайте поведение полностью эквивалентным process backend.

Безопасная очистка

При очистке stale processes:

1. Определите pid и убедитесь, что он принадлежит текущей команде / lane.
2. Останавливайте только процессы, явно принадлежащие smoke test или отлаживаемому launch.
3. Не убивайте все процессы OpenCode или shared hosts в качестве shortcut.

Какие данные собрать

Соберите:

• task id (short или full)
• team name
• runtime path (claude, codex, или opencode)
• launch log excerpt (из latest.json или bootstrap-journal.jsonl)
• provider / model
• точный time window

Этого обычно хватает для диагностики launch и task lifecycle issues.

TIP

Если проблема не устраняется, откройте persisted files команды под ~/.claude/teams/<teamName>/ и сопоставьте UI diagnostics с live process state, прежде чем менять код.