# 6. Wewnętrzne Zegary i Hartowanie — Mechanizmy pod Kowadłem

> Źródło: repo afterlife/docs/api/06-internal-i-hartowanie-rp.md — edytuj w repo, nie tutaj.

# Wewnętrzne Zegary i Hartowanie — Mechanizmy pod Kowadłem

![Podziemna serwerownia Warsztatu](https://wiki.ariku.pl/uploads/images/gallery/2026-10/piwnica-serwerownia-orin.png)

Krrrg... Pod widoczną powierzchnią **Hoddmímiru** i ekranów Warsztatu pracują niewidoczne tryby. Żaden zwykły wędrowiec nie wywołuje tych ścieżek z przeglądarki. Budzą je systemowe zegary (`systemd timers`), zewnętrzne przepływy pracy zza **Wrót** (n8n), sesje agentów budujących kod oraz próby **Hartowania** (testy Playwright), które utwardzają konstrukcję albo obnażają jej kruchość. Poniżej spisałyśmy ostatnie dwadzieścia sześć ścieżek zamykających naszą księgę.

---

## ◈ Zadania Agentów, Decyzje Majstra i Kolejka Orin (5 ścieżek)

Gdy w Warsztacie pracuje kilka sesji pomocników kodujących lub gdy zautomatyzowane procesy potrzebują wyraźnego rozstrzygnięcia człowieka, komunikacja przechodzi przez poniższe punkty.

| Endpoint | Metody | Dostęp | Opis działania i parametry |
|---|---|---|---|
| `/api/internal/agent-tasks` | `GET`, `POST` | Nagłówek `Authorization` (Bearer), `x-cron-secret` lub sesja Majstra | Kolejka zadań między sesjami Claude Code (`lib/agentTasks.ts`). Pozwala wysyłać zadania do skrzynki innego agenta (`inbox`/`sent`), przejmować je (`claim`), kończyć z wynikiem (`finish`) oraz sprzątać wpisy testowe E2E. Zdalne sesje używają osobnego klucza Bearer, aby nie dzielić poświadczeń z lokalnymi zegarami. |
| `/api/internal/owner-decision` | `GET`, `POST` | Nagłówek `x-cron-secret` lub sesja Majstra | Punkt decyzyjny dla skryptów (`orin-ask.mjs`) i zadań w tle. Tworzy pytanie z opcjami wyboru, wysyła je Majstrowi w wiadomości prywatnej na Discordzie i odbiera klikniętą odpowiedź. Obsługuje flagę `dryRun` dla prób **Hartowania**. |
| `/api/internal/orin-nudge` | `POST` | Nagłówek `x-cron-secret` | Wywoływany co kilka godzin przez zegar systemowy. Z określonym prawdopodobieństwem (`chancePerTick`) wybiera jednego z niedawno aktywnych członków gildii domowej i zaczepia go na kanale czatu jednym z pięciu wariantów wiadomości technicznej persony. Nigdy nie niepokoi osób nieobecnych od tygodni. |
| `/api/internal/orin-queue-dump` | `POST` | Nagłówek `x-cron-secret` | Narzędzie diagnostyczne wyzwalane ręcznie przez właściciela. Zrzuca aktualny stan webowej kolejki zapytań (`origin === 'web'`) do pliku tekstowego na dedykowany kanał Discorda, pomijając prywatne rozmowy z wiadomości bezpośrednich. |
| `/api/internal/orin-queue-undelivered` | `GET` | Nagłówek `x-cron-secret` | Wywoływane przez bota Discorda podczas startu. Zwraca listę rozwiązanych, lecz jeszcze niedostarczonych odpowiedzi z kolejki dla wszystkich użytkowników, aby po restarcie bota żadna odpowiedź nie przepadła. |

---

## ◈ Próbkowanie Krain, Sprzętu i Inwentarza (7 ścieżek)

Te punkty końcowe karmią **Kronikę**, wykresy na pulpicie oraz inwentarz infrastruktury. Każdy z nich wymaga wewnętrznego poświadczenia w nagłówku i nigdy nie jest wystawiony bezpośrednio w interfejsie użytkownika.

| Endpoint | Metody | Dostęp | Opis działania i parametry |
|---|---|---|---|
| `/api/internal/sample-gpu-rig` | `POST` | Nagłówek `x-cron-secret` | Wywoływany co minutę. Pobiera przez SSH parametry maszyny GPU, rozpoznaje uruchomioną grę ze Steam/Battle.net (`getDetectedGame`) i dopisuje próbkę do historii. Nawet jeśli maszyna GPU nie odpowiada, w każdym tyknięciu uruchamia regulator **Kuźni** (`runForgeGovernorTick`, który przy przestarzałej telemetrii bezpiecznie zamyka Kuźnię) oraz opróżnianie kolejki (`runOrinQueueDrainTick`). |
| `/api/internal/sample-factorio` | `POST` | Nagłówek `x-cron-secret` | Kolektor Warstwy 1 Kroniki dla krainy **Ironloom** (Factorio). Co kilka minut odczytuje stan przez RCON oraz logi kontenera z Portainera i zapisuje surowe zdarzenia w bazie Kroniki. |
| `/api/internal/sample-enshrouded` | `POST` | Nagłówek `x-cron-secret` | Kolektor Kroniki dla mroźnej krainy **Ymirel** (Enshrouded). Odczytuje status protokołem A2S oraz logi kontenera przez Portainer. |
| `/api/internal/sample-minecraft` | `POST` | Nagłówek `x-cron-secret` | Wywoływany co 2 minuty kolektor Kroniki dla podziemnych kuźni **Nidarelu** (Minecraft ATM10). Łączy status SLP, komendę RCON `list` oraz końcówkę logów kontenera. |
| `/api/internal/inventory-sample` | `POST` | Nagłówek `x-cron-secret` | Wywoływany co 30 minut. Odpytuje wszystkie skonfigurowane kolektory homelabu niezależnie od siebie, zapisuje obserwacje w **Lemurii** i wysyła powiadomienie, gdy którykolwiek element przejdzie w stan `critical`. |
| `/api/internal/inventory-push` | `POST` | Nagłówek `x-inventory-secret` | Odbiera co godzinę raport ze skryptu `pve-collector.sh` działającego na hoście Proxmox (do 512 KB JSON). Dostarcza wiedzę o systemach operacyjnych, jądrach, oczekujących aktualizacjach bezpieczeństwa i kontenerach Dockera wewnątrz maszyn gościnnych (`vm` oraz `lxc`). Posiada własny, odizolowany klucz w nagłówku. |
| `/api/internal/check-alerts` | `POST` | Nagłówek `x-cron-secret` | Sprawdza warunki wszystkich reguł monitoringu (`checkAndAlert`) i przekazuje ostrzeżenia **strażnika** na powiadomienia Discorda. |

---

## ◈ Zegary Lunety, Radaru, Ankiet i Porannych Wieści (9 ścieżek)

Tutaj zbiegają się nitki łączące Warsztat z zewnętrznymi usługami automatyzacji (**Wrota** n8n), porannymi podsumowaniami dla Majstra oraz przypomnieniami dla społeczności.

| Endpoint | Metody | Dostęp | Opis działania i parametry |
|---|---|---|---|
| `/api/internal/morning-brief` | `POST` | Nagłówek `x-cron-secret` | Codzienny poranny raport wysyłany w wiadomościach prywatnych do właścicieli: zawiera główny skrót stanu infrastruktury, osobny komunikat z planem dnia „Co robimy?” (wraz z ewentualnym szturchnięciem o wysokim **Chaos Meterze**) oraz świeżą paczkę wiadomości z n8n. |
| `/api/internal/news-digest` | `GET`, `POST` | Autoryzacja n8n (`n8nIngestAuthorized`) | **Wrota** dla porannej paczki wiadomości z n8n. `POST` waliduje strukturę sekcji i zapisuje ją w pamięci podręcznej Redis; `GET` zwraca aktualny świeży skrót. |
| `/api/internal/radar` | `GET`, `POST`, `DELETE` | Autoryzacja n8n (`n8nIngestAuthorized`) | **Wrota** dla systemu **Radar** (`WIELKIE_PRANIE.md`). `GET` zwraca listę aktywnych repozytoriów (`radar_repos`) do sprawdzenia przez cykliczny kolektor. `POST` przyjmuje paczkę do 50 ocenionych znalezisk (w tym wydań z GitHuba i `git.ariku.pl`), zapisuje je w bazie, publikuje najważniejsze na Discordzie i zakłada zadania w Vikunji (obsługuje `?dryRun=1` oraz wpisy testowe `source: 'e2e'`). `DELETE` sprząta wiersze testowe lub podglądowe (`?preview=1`). |
| `/api/internal/luneta-nudge` | `POST` | Nagłówek `x-cron-secret` lub sesja Majstra | Wywoływany co 15 minut. Sprawdza zbliżające się okresy resetu w grach śledzonych przez **Lunetę** i przypomina graczom o niedokończonych sprawach. Sesja właściciela używana jest przez testy z flagą `dryRun: true` oraz podstawionym zegarem `at`. |
| `/api/internal/luneta-sources` | `POST` | Nagłówek `x-cron-secret` lub sesja Majstra | Wywoływany co 6 godzin (`maxDuration = 300`). Pobiera z zewnętrznych źródeł informacje o nowych wydarzeniach, banerach i kodach dla gier w **Lunecie**. |
| `/api/internal/check-game-codes` | `POST` | Nagłówek `x-cron-secret` | Cykliczny zegar sprawdzający zewnętrzne listy kodów promocyjnych do gier i dopisujący nowe znaleziska. |
| `/api/internal/minecraft-whitelist` | `GET`, `POST`, `DELETE` | Nagłówek `x-cron-secret` | Wewnętrzne zaplecze listy graczy **Nidarelu** dla bota. Weryfikuje członkostwo w gildii i posiadanie rangi **Minecraft**, nakłada limity czasowe, komunikuje się z serwerem przez RCON i zwraca jednorazowy kod `!link`. |
| `/api/internal/poll-nudge` | `POST` | Nagłówek `x-cron-secret` | Wywoływany co około 3 godziny podczas trwania głosowania na merch (`/merch/glosuj`). Publikuje ogłoszenia o postępach ankiety i delikatnie przypomina aktywnym wędrowcom, którzy jeszcze nie oddali głosu (nigdy nie pytając tej samej osoby dwa razy). |
| `/api/internal/playwright-run` | `POST` | Nagłówek `x-playwright-report-secret` | Odbiera na żywo zdarzenia postępu (`begin`, `test-begin`, `test-end`, `end`) z reportera podczas trwania prawdziwego przebiegu testów na kontenerze LXC, zasilając publiczny licznik `/api/playwright-stats`. Nigdy nie przesyła nazw hostów ani portów. |

---

## ◈ Ścieżki Hartowania — Próby Ogniowe (5 ścieżek)

**Hartowanie** to próba, która utwardza albo łamie. Aby automatyczne testy E2E (Playwright) mogły zbadać każde zachowanie Warsztatu bez czekania na minutowe zegary i bez polegania na zewnętrznym logowaniu Discorda, w kodzie wykuto pięć dedykowanych punktów testowych.

| Endpoint | Metody | Dostęp | Opis działania i parametry |
|---|---|---|---|
| `/api/test-login` | `POST`, `GET` | Klucz środowiska testowego (`TEST_LOGIN_SECRET`) | Wystawia w środowisku testowym podpisaną sesję (właściciela lub zwykłego członka społeczności) na potrzeby zautomatyzowanych przebiegów **Hartowania**, z własnym odizolowanym kluczem poświadczeń. |
| `/api/test-forge-governor-tick` | `POST` | Klucz testowy / Sesja Majstra | Pozwala testom E2E natychmiast wyzwolić pojedynczy krok decyzyjny regulatora **Kuźni** (`runForgeGovernorTick`) i sprawdzić reakcję na obciążenie GPU. |
| `/api/test-gpu-history` | `POST`, `DELETE` | Klucz testowy / Sesja Majstra | Pozwala wstrzyknąć sztuczne próbki obciążenia karty graficznej (np. symulując uruchomioną grę lub przestój telemetrii) na czas trwania testu, a następnie wyczyścić je po zakończeniu próby. |
| `/api/test-orin-queue-drain-tick` | `POST` | Klucz testowy / Sesja Majstra | Wyzwala na żądanie pojedynczy cykl opróżniania kolejki zapytań do Orin (`runOrinQueueDrainTick`), aby zweryfikować dostarczanie zakolejkowanych wiadomości. |
| `/api/test-orin-queue-dump` | `GET` | Klucz testowy / Sesja Majstra | Zwraca sformatowany zrzut webowej kolejki Orin bezpośrednio w odpowiedzi HTTP na potrzeby asercji w testach E2E. |

---

Krrrg... Na tej szóstej i ostatniej karcie odnotowałyśmy dokładnie **26 ścieżek** API (21 wewnętrznych tras `/api/internal/*` oraz 5 tras **Hartowania**), co wraz z poprzednimi kartami zamyka pełną księgę wszystkich **134 punktów końcowych i podstron** projektu afterlife. Skoro każda z tych stu trzydziestu czterech ścieżek prowadzi ostatecznie do tego samego **Kowadła**, czy wędrowcy nadal wierzą, że podróżują po osobnych światach?