Усунення проблем — діагностика проблем

Авторизація

401 — Невалідний токен

Симптом: API повертає "Missing authorization" або дашборд показує "Unauthorized"
Причини: Токен відсутній, прострочений (TTL 24 години) або формат заголовка неправильний
Рішення: Залогінься знову. Для SSE/WebSocket токен передається через ?token=. JWT оновлюється кожні 24 години

401 — Email не підтверджено

Симптом: Логін успішний, але повертає requires_verification: true
Причини: Посилання у листі підтвердження не натиснуто (TTL 24 години)
Рішення: Перевір пошту й натисни посилання. Або попроси адміна підтвердити вручну. Користувачі OAuth підтверджуються автоматично

403 — Немає доступу до проєкту

Симптом: Файлові операції або WebSocket-термінал повертають Forbidden
Причини: Multi-tenancy — користувач не є власником проєкту. Або було заблоковано спробу path traversal
Рішення: Перевір власника проєкту. Інтерактивний термінал доступний лише admin/CEO

Воркери та боти

Воркер не відповідає

Симптом: Повідомлення надіслано, але відповіді немає
Причини: Процес Claude зайнятий, tmux-сесія впала, порт зайнятий
Діагностика: Перевір /health або /ping у Telegram. У CRM — іконку статусу біля воркера
Рішення: Натисни STOP і спробуй знову. Або перезапусти через CRM Settings → Restart

Статус: "degraded"

Симптом: Health check повертає status: "degraded" замість "ok"
Причини: 3+ послідовні помилки підпроцесу Claude
Рішення: Зачекай — watchdog перезапустить його автоматично. Або перезапусти вручну через /watchdog у Telegram

Таймаут (5 хвилин)

Симптом: Бот повертає "Claude timeout (5 min limit)"
Причини: Задача занадто складна для одного повідомлення, великі файли
Рішення: Розбий задачу на менші кроки. Перемкнися на швидшу модель (Haiku)

Max turns reached

Симптом: "Reached max turns" — Claude зупинився після N кроків
Причини: Задача потребує більше викликів інструментів, ніж ліміт (за замовчуванням 20 для Developer, 10 для Consultant)
Рішення: Розбий задачу. Або збільш max_turns через Worker Studio

Watchdog вимкнув бота

Симптом: "Permanently disabled after 10 consecutive failures"
Причини: 10 послідовних збоїв (відсутній токен, видалені файли, зайнятий порт)
Рішення: Усунь першопричину, потім перезапусти через Master Bot /deploy або CRM Restart

Семантичний пошук / RAG (Phase 71)

`arc kb search` повертає порожній результат для свіжого проєкту

Симптом: новий проєкт без вікі/задач — пошук повертає No content found...
Причина: Хуки RAG (Phase 71.5) повторно ембедять вміст на запис, але до перших записів індекс порожній. CLI-fallback на пошук за ключовими словами по wiki/tree теж нічого не знаходить.
Рішення: запиши щось у вікі/задачу/скіл — ембединг з'явиться за 1-2 секунди. Або форсуй через arc memory refresh (повторно ембедить MANIFEST + ROADMAP + усі файли вікі).

Cohere 401 Unauthorized

Симптом: у логах master видно [rag-hook] ... failed: Cohere auth rejected (401)
Причина: COHERE_API_KEY у vault прострочений або ротований неправильно.
Рішення: Platform Settings → RAG / Semantic search → Rotate. Жива кнопка Test перевіряє новий ключ через /v2/embed.

Cohere 429 Rate Limited

Симптом: Backfill або хуки падають із 429.
Причина: Trial-tier ключ Cohere має ліміт 1000 викликів/місяць; для продакшену потрібен Production tier.
Рішення: апгрейд на https://dashboard.cohere.com/billing. Перший прод-backfill 2026-06-05 вигорів саме на цьому — після переходу на Production цикл на 178 документів завершився з 0/178 помилок.

Хвіст latency >500мс

Симптом: окремі пошукові запити повертаються повільно.
Причина: дисперсія хвоста upstream Cohere — наш p50 стабільно ~195мс, але окремі виклики /v2/embed можуть тривати 800-1000мс.
Рішення: дивись docs/architecture/PHASE_71_SOAK_2026-06-05.md — це задокументоване upstream-обмеження, а не наш код. Майбутні фази: LRU-кеш query-embed, region pinning для Cohere.

Фронтенд і зв'язок

WebSocket відключається

Симптом: Термінал або чат відключається з кодом 1008
Причини: JWT-токен прострочився під час сесії (TTL 24 години)
Рішення: Онови сторінку (F5) — токен оновлюється автоматично

SSE-стрімінг не працює

Симптом: Відповідь воркера не з'являється в реальному часі
Причини: Проєкт не знайдено в реєстрі, або в nginx увімкнено буферизацію
Рішення: Перевір назву проєкту. SSE потребує proxy_buffering off у nginx

Помилка CORS

Симптом: Консоль браузера показує CORS blocked
Причини: Origin не в whitelist CRM_ALLOWED_ORIGINS
Рішення: Додай origin до змінної CRM_ALLOWED_ORIGINS і перезапусти Master Bot

Повідомлення обрізається

Симптом: Відповідь у Telegram урізана
Причини: Ліміт Telegram у 4096 символів
Рішення: Бот автоматично розбиває на частини [1/3] [2/3] [3/3]. Якщо ні — це баг у логіці розбиття

База даних

"Database not initialized"

Симптом: Бот падає з "Database not initialized. Call initDb() first."
Причини: initDb() не було викликано перед першим запитом, або файл DB видалено
Рішення: Перезапусти Master Bot — він автоматично ініціалізує DB і виконує міграції

"Database locked"

Симптом: Випадкові помилки 500 під високим навантаженням
Причини: SQLite пишеться кількома процесами одночасно
Рішення: Режим WAL увімкнено за замовчуванням. Перезапусти завислі процеси

Швидкий довідник

Проблема	Що перевірити першим	Швидке рішення
Бот не відповідає	`/health` або `/ping`	Перезапуск через CRM
401 Unauthorized	Час створення токена	Залогінитися знову
403 Forbidden	Власник проєкту	Перевірити owner_id
Статус degraded	`consecutiveFailures`	Зачекати на watchdog
Таймаут 5хв	Складність задачі	Розбити на менші кроки
Помилка Bridge	`google_auth` у /health	`arc memory refresh`
CORS blocked	CRM_ALLOWED_ORIGINS	Додати origin
Відключення WebSocket	Час життя JWT (24г)	Оновити сторінку

Корисні діагностичні команди

# Health checks
curl -s http://localhost:19210/api/master/health | jq .
curl -s http://localhost:19211/api/child/health | jq .

# Check tmux sessions
tmux list-sessions

# Master Bot logs
tmux capture-pane -t citadel-master -p | tail -20

# Child Bot logs
tmux capture-pane -t ws-arc-v2 -p | tail -20

# Check ports
ss -tlnp | grep '192[0-9][0-9]'

# Database state
sqlite3 data/citadel.db "PRAGMA integrity_check;"

Контроль документації (Phase 49.1+)

`git push` заблоковано з "doc-coverage check failed"

Pre-push hook вимагає оновлення документації, коли змінюється код. STDERR показує саме те, які файли треба оновити.

Швидкі рішення:

Авто-чернетка: arc wrapup --generate → заповни TODO → commit
Вручну: дивись мапінг у CLAUDE.md (Documentation Law)
Аварійний обхід: git push --no-verify (залишає слід у git log)

Hook не запускається на свіжому клоні

bash scripts/setup-hooks.sh   # one-time per clone
git config core.hooksPath     # verify it equals ".githooks"

Інтеграція з GitHub (Phase 49.3)

Webhook повертає 401

Content-Type: application/json у GitHub webhook (не form-urlencoded)
Secret має збігатися з виводом arc github link
Втратив secret → видали webhook у GitHub UI + arc github unlink, створи новий

Стрічка GitHub у сайдбарі порожня

ContextRail видно при viewport ≥1280px
Hard refresh (Ctrl+Shift+R)
Перевірка DB: sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Rate limit "429 Rate limited"

Ліміт = 100 req/min/project. Підніми його в shared/routes/github.ts:RATE_MAX.

Детальніше: Налаштування інтеграції з GitHub.