Rozwiązywanie Problemów — Diagnostyka

Autoryzacja

401 — Nieprawidłowy Token

Objaw: API zwraca "Missing authorization" lub pulpit pokazuje "Unauthorized"
Przyczyny: Token brakuje, wygasł (TTL 24 godziny) lub nieprawidłowy format nagłówka
Rozwiązanie: Zaloguj się ponownie. W przypadku SSE/WebSocket token przekazywany jest przez ?token=. JWT jest odświeżany co 24 godziny

401 — Email Niezweryfikowany

Objaw: Logowanie udane, ale zwraca requires_verification: true
Przyczyny: Nie kliknięto linku w emailu weryfikacyjnym (TTL 24 godziny)
Rozwiązanie: Sprawdź email, kliknij link. Lub poproś admina o ręczną weryfikację. Użytkownicy OAuth są weryfikowani automatycznie

403 — Brak Dostępu do Projektu

Objaw: Operacje na plikach lub terminal WebSocket zwracają Forbidden
Przyczyny: Multi-tenancy — użytkownik nie jest właścicielem projektu. Lub próba path traversal jest blokowana
Rozwiązanie: Sprawdź własność projektu. Interaktywny terminal dostępny tylko dla admin/CEO

Workerzy i Boty

Worker Nie Odpowiada

Objaw: Wiadomość wysłana, ale nie ma odpowiedzi
Przyczyny: Proces Claude zajęty, sesja tmux się wysypała, port zajęty
Diagnostyka: Sprawdź /health lub /ping w Telegram. W CRM — ikona statusu przy workerze
Rozwiązanie: Kliknij STOP i powtórz. Lub zrestartuj przez CRM Settings → Restart

Status: "degraded"

Objaw: Health check zwraca status: "degraded" zamiast "ok"
Przyczyny: 3+ kolejnych błędów subprocess Claude
Rozwiązanie: Poczekaj — watchdog automatycznie zrestartuje. Lub zrestartuj ręcznie przez /watchdog w Telegram

Timeout (5 minut)

Objaw: Bot zwraca "Claude timeout (5 min limit)"
Przyczyny: Zadanie zbyt skomplikowane dla jednej wiadomości, duże pliki
Rozwiązanie: Podziel zadanie na mniejsze kroki. Zmień model na szybszy (Haiku)

Max turns reached

Objaw: "Reached max turns" — Claude zatrzymał się po N krokach
Przyczyny: Zadanie wymaga więcej wywołań narzędzi niż limit (domyślnie 20 dla Developer, 10 dla Consultant)
Rozwiązanie: Podziel zadanie. Lub zwiększ max_turns przez Worker Studio

Watchdog wyłączył bota

Objaw: "Permanently disabled after 10 consecutive failures"
Przyczyny: 10 kolejnych niepowodzeń (brak tokenu, usunięte pliki, zajęty port)
Rozwiązanie: Napraw przyczynę podstawową, następnie zrestartuj przez Master Bot /deploy lub CRM Restart

Semantic search / RAG (Phase 71)

`arc kb search` zwraca pusty wynik dla świeżego projektu

Objaw: nowy projekt bez wiki/zgłoszeń — wyszukiwanie zwraca No content found...
Przyczyna: hooki RAG (Phase 71.5) re-embedują treść przy zapisie, ale do pierwszych wpisów indeks jest pusty. Fallback CLI na keyword search po wiki/tree też nic nie znajduje.
Rozwiązanie: dopisz coś do wiki/zgłoszenia/skilla — embedding pojawi się po 1-2 sekundach. Albo wymuś przez arc memory refresh (re-embed MANIFEST + ROADMAP + wszystkie pliki wiki).

Cohere 401 Unauthorized

Objaw: w logach mastera [rag-hook] ... failed: Cohere auth rejected (401)
Przyczyna: COHERE_API_KEY w vault wygasł lub został niepoprawnie zrotowany.
Rozwiązanie: Platform Settings → RAG / Semantic search → Rotate. Przycisk live Test sprawdzi już nowy klucz przez /v2/embed.

Cohere 429 Rate Limited

Objaw: Backfill lub hooki padają z 429.
Przyczyna: Klucz Cohere w tierze trial ma limit 1000 wywołań/miesiąc; na produkcji potrzebny tier Production.
Rozwiązanie: upgrade na https://dashboard.cohere.com/billing. Pierwszy produkcyjny backfill 2026-06-05 spalił się dokładnie na tym — po przejściu na Production cykl 178 docs przeszedł z 0/178 błędów.

Ogon latencji >500ms

Objaw: pojedyncze zapytania search wracają wolno.
Przyczyna: Wariancja ogona po stronie Cohere — nasze p50 to ~195ms steady, ale pojedyncze wywołania /v2/embed mogą zajmować 800-1000ms.
Rozwiązanie: sprawdź docs/architecture/PHASE_71_SOAK_2026-06-05.md — to udokumentowane ograniczenie upstream, nie nasz kod. Przyszłe fazy: LRU cache dla query-embed, region pinning Cohere.

Frontend i Połączenia

WebSocket Się Rozłącza

Objaw: Terminal lub czat rozłącza się z kodem 1008
Przyczyny: Token JWT wygasł podczas sesji (TTL 24 godziny)
Rozwiązanie: Odśwież stronę (F5) — token odświeży się automatycznie

Streaming SSE Nie Działa

Objaw: Odpowiedź workera nie pojawia się w czasie rzeczywistym
Przyczyny: Projekt nie znaleziony w rejestrze, lub nginx buffering włączony
Rozwiązanie: Sprawdź nazwę projektu. SSE wymaga proxy_buffering off w nginx

Błąd CORS

Objaw: Konsola przeglądarki pokazuje CORS blocked
Przyczyny: Origin nie na białej liście CRM_ALLOWED_ORIGINS
Rozwiązanie: Dodaj origin do zmiennej CRM_ALLOWED_ORIGINS i zrestartuj Master Bot

Wiadomość Jest Obcięta

Objaw: Odpowiedź w Telegram się urywa
Przyczyny: Limit Telegram 4096 znaków
Rozwiązanie: Bot automatycznie dzieli na części [1/3] [2/3] [3/3]. Jeśli nie — bug w logice podziału

Baza Danych

"Database not initialized"

Objaw: Bot pada z błędem "Database not initialized. Call initDb() first."
Przyczyny: initDb() nie zostało wywołane przed pierwszym zapytaniem, lub plik DB usunięty
Rozwiązanie: Zrestartuj Master Bot — automatycznie zainicjalizuje DB i wykona migracje

"Database locked"

Objaw: Losowe błędy 500 przy dużym obciążeniu
Przyczyny: SQLite jest zapisywane jednocześnie z kilku procesów
Rozwiązanie: Tryb WAL włączony domyślnie. Zrestartuj stale procesy

Szybka Referencja

Problem	Co Sprawdzić Najpierw	Szybkie Rozwiązanie
Bot nie odpowiada	`/health` lub `/ping`	Restart przez CRM
401 Unauthorized	Czas utworzenia tokenu	Zaloguj się ponownie
403 Forbidden	Własność projektu	Sprawdź owner_id
Status degraded	`consecutiveFailures`	Poczekaj na watchdog
Timeout 5m	Złożoność zadania	Podziel na mniejsze kroki
Błąd Bridge	`google_auth` w /health	`arc memory refresh`
CORS blocked	CRM_ALLOWED_ORIGINS	Dodaj origin
WebSocket disconnect	Czas życia JWT (24h)	Odśwież stronę

Przydatne Komendy Diagnostyczne

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

# Sprawdzenie sesji tmux
tmux list-sessions

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

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

# Sprawdzenie portów
ss -tlnp | grep '192[0-9][0-9]'

# Stan bazy danych
sqlite3 data/citadel.db "PRAGMA integrity_check;"

Egzekwowanie Dokumentacji (Phase 49.1+)

`git push` jest blokowany z "doc-coverage check failed"

Hook pre-push wymaga aktualizacji dokumentacji gdy zmieniany jest kod. STDERR pokaże które pliki należy zaktualizować.

Szybkie rozwiązania:

Auto-draft: arc wrapup --generate → wypełnij TODO → commit
Ręcznie: sprawdź mapowanie w CLAUDE.md (Documentation Law)
Awaryjne obejście: git push --no-verify (pozostawia ślad w git log)

Hook Nie Uruchamia Się na Nowym Klonie

bash scripts/setup-hooks.sh   # jednorazowo per klon
git config core.hooksPath     # sprawdź czy = ".githooks"

Integracja GitHub (Phase 49.3)

Webhook Zwraca 401

Content-Type: application/json w webhooku GitHub (nie form-urlencoded)
Secret musi pasować do outputu arc github link
Zgubiony secret → usuń webhook w GitHub UI + arc github unlink, utwórz nowy

Pasek Boczny GitHub Feed Pusty

ContextRail widoczny przy viewport ≥1280px
Hard refresh (Ctrl+Shift+R)
Sprawdzenie DB: sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Rate Limit "429 Rate limited"

Cap = 100 req/min/project. Zwiększ w shared/routes/github.ts:RATE_MAX.

Szczegóły: Konfiguracja Integracji GitHub.