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

NotebookLM Bridge

Wyszukiwanie Semantyczne Nie Działa

• Objaw: arc kb search lub zakładka NotebookLM zwraca błąd
• Diagnostyka: Sprawdź /health — czy google_auth: true
• Przyczyny: Autoryzacja Google wygasła, serwis Bridge nie uruchomiony
• Rozwiązanie: Zrestartuj serwis Bridge. Odnów autoryzację Google

Stare Dane w Wyszukiwaniu

• Objaw: Wyszukiwanie zwraca przestarzałe informacje
• Przyczyny: Cache (TTL 5 minut) lub źródła nie zsynchronizowane
• Rozwiązanie: Uruchom arc memory refresh dla pełnej resynchronizacji

Kolejka Synchronizacji Przepełniona (429)

• Objaw: Sync zwraca HTTP 429
• Przyczyny: Ponad 200 elementów w kolejce
• Rozwiązanie: Poczekaj 2-3 minuty — kolejka jest przetwarzana z prędkością 1 element / 2 sekundy

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

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.