---
title: "Gdy coś nie działa w Monolynx: objawy, przyczyny i naprawa"
description: "Tabele objaw, przyczyna, naprawa dla pracy z agentami w Monolynx: połączenie, konfiguracja, kontrola wstępna sprint-run, sesje w tle, kolejka merge requestów i zamknięcie sprintu."
url: "https://monolynx.com/blog/gdy-cos-nie-dziala-w-monolynx"
lang: "pl"
author: "Zespół Monolynx"
published: "2026-10-08T08:39:49.986527+00:00"
modified: "2026-10-09T18:11:30.910442+00:00"
last_verified: "2026-10-08"
tags: ["diagnostyka", "sprint", "claude-code", "agenci-ai", "plugin"]
translations: []
reading_time_minutes: 11
word_count: 2183
---

> [!TLDR]
> - Większość problemów ma jedną z czterech przyczyn: brak połączenia, brak konfiguracji projektu, brak zgody albo decyzja, która należy do człowieka.
> - Zacznij od `/monolynx:next` i `/monolynx:setup`. Pierwsza komenda mówi, co zrobić teraz, druga pokazuje braki w konfiguracji.
> - Pętle nigdy nie psują się po cichu. Każdy tick kończy się linią statusu, a każde zatrzymanie linią `STOP` z powodem.
> - Zatrzymanie nie jest awarią. Sesja, która staje i pyta, zachowuje całą pracę i czeka na Twoją decyzję.
> - Kod 137 w CI i masowe błędy testów przy równoległych sesjach to problemy środowiska, a nie kodu. Agent ich nie "naprawia".

## Od czego zacząć diagnozę?

Diagnozę zaczynasz od ustalenia warstwy, w której leży problem. Poniższa kolejność prowadzi od rzeczy najtańszych do sprawdzenia do najdroższych.


**Kroki**

1. **Zapytaj router** Komenda `/monolynx:next` czyta stan repozytorium, ticketu, sprintu, sesji i merge requestów, a potem poleca od jednej do trzech komend z uzasadnieniem. Niczego nie zmienia.
2. **Sprawdź konfigurację** Komenda `/monolynx:setup` pokazuje stan siedmiu punktów: slug, strona `toolchain`, LLM Wiki, graf, mutacje, flagi i CLI.
3. **Przeczytaj ostatnią linię** Pętla dyspozytora kończy tick linią `SPRINT-RUN:`, kolejka linią `MR-QUEUE:`. Zatrzymanie ma własną linię `STOP` z powodem.
4. **Zajrzyj do sesji** Komenda `claude logs <id>` pokazuje, na czym stanęła sesja ticketu w tle.
5. **Dopiero potem poprawiaj** Znana przyczyna wskazuje jedną konkretną naprawę z tabel poniżej.



**W której warstwie leży problem**

Jeśli agent w ogóle nie widzi Monolynx, problem leży w połączeniu. Jeśli widzi, ale komendy odmawiają startu, brakuje konfiguracji projektu albo zgód. Jeśli pętle działają, a sprint stoi, sesja czeka na człowieka albo ticket jest zablokowany. Jeśli merge request nie wchodzi, przyczyna jest w CI, konflikcie albo braku zatwierdzenia.

```mermaid
flowchart TD
  A{"Agent widzi narzędzia Monolynx?"} -- nie --> P["Połączenie: MCP albo CLI"]
  A -- tak --> B{"Komendy startują?"}
  B -- nie --> K["Konfiguracja: slug, toolchain, flagi"]
  B -- tak --> C{"Sprint posuwa się?"}
  C -- nie --> S["Sesje: waiting, blokery, sloty"]
  C -- tak --> D{"Merge requesty wchodzą?"}
  D -- nie --> M["Kolejka: CI, konflikt, zatwierdzenie"]
  D -- tak --> OK["Wszystko działa"]
```



**Statystyki**

- **4** - warstwy, w których szukasz przyczyny
- **2** - komendy diagnostyczne tylko do odczytu: `next` i `setup`
- **2** - rundy poprawek CI, po których kolejka oddaje merge request człowiekowi


## Połączenie: agent nie widzi Monolynx

Problemy tej warstwy widać od razu: agent nie zna narzędzi albo dostaje odmowę przy pierwszej operacji.


**Porównanie**

| Objaw | Przyczyna | Naprawa |
| --- | --- | --- |
| Agent nie ma narzędzi Monolynx | serwer MCP dodany tylko dla innego katalogu | dodaj serwer dla całego użytkownika: `claude mcp add --transport http --scope user monolynx https://monolynx.com/mcp` |
| Błąd autoryzacji przy pierwszej operacji | logowanie OAuth niedokończone albo wygasłe | w Claude Code otwórz `/mcp` i zaloguj się ponownie |
| Lista projektów jest pusta | konto nie jest członkiem żadnego projektu | poproś właściciela projektu o dodanie do zespołu |
| `Brak uprawnienia <moduł>:<akcja>` | rola nie pozwala na tę operację | poproś o rolę z tym uprawnieniem; ponawianie nic nie da |
| `Brak uprawnienia blog:write` | publikacja na blogu to osobne uprawnienie konta | nadaje je administrator instancji |
| Linia `TRANSPORT-HINT:` na starcie komendy | CLI nie jest zainstalowane, zalogowane albo aktualne | to podpowiedź, nie błąd; praca idzie dalej przez MCP |


> [!NOTE]
> Odmowa uprawnienia przychodzi zawsze przed jakimkolwiek zapisem. Operacja odrzucona z komunikatem "Brak uprawnienia" niczego nie zmieniła, więc nie ma czego sprzątać.

Pełną konfigurację połączenia opisuje wpis [Jak połączyć agenta AI z Monolynx](https://monolynx.com/blog/polaczenie-z-monolynx-mcp-claude-code-chatgpt), a kanał CLI wpis [CLI monolynx dla deweloperów i agentów](https://monolynx.com/blog/monolynx-cli-dla-deweloperow-i-agentow).

## Konfiguracja: komenda odmawia startu

W tej warstwie komendy działają, ale zatrzymują się na początku, bo brakuje im wejścia.


**Porównanie**

| Objaw | Przyczyna | Naprawa |
| --- | --- | --- |
| Komenda pyta o slug projektu | brak `MONOLYNX_PROJECT_SLUG` w środowisku klienta | wpisz slug do pola `env` w śledzonym `.claude/settings.json` |
| Slug jest w pliku `.env`, a komenda dalej pyta | plik `.env` nie przekazuje zmiennych do Claude Code | przenieś slug do `.claude/settings.json` |
| `work` pyta przed lintem i testami, czy kontynuować bez nich, a sesja w tle kończy turę | brak strony wiki `Toolchain` | uruchom `/monolynx:project-toolchain` |
| `work` w osobnym worktree odsyła do `project-toolchain` | strona `Toolchain` nie ma sekcji `## Worktree` | uruchom `/monolynx:project-toolchain` ponownie |
| Komendy wiki kończą się informacją o wyłączonej metodzie | LLM Wiki nie jest włączona w projekcie | uruchom `/monolynx:wiki-init` |
| Agent wypisuje komendy testów zamiast je uruchomić | `MONOLYNX_AUTOTEST` nie jest ustawiona na `true` | uruchom testy sam albo ustaw flagę |


> [!WARNING]
> Flaga ustawiona w `.claude/settings.local.json` działa w Twojej sesji, ale nie w sesji ticketu, która pracuje w osobnym worktree. Flagi dla sprintu z sesjami w tle trzymaj w śledzonym `.claude/settings.json` albo w środowisku procesu, który uruchamia pętlę.

## Dlaczego sprint-run nie startuje sesji?

Dyspozytor zaczyna każdy tick od kontroli wstępnej. Kontrola zbiera wszystkie problemy naraz, wypisuje je jako linie `ERROR:` i `WARN:`, a na końcu podaje wynik.


**Przykład kontroli wstępnej z dwoma błędami**

```console
WARN: MONOLYNX_AUTOMR nie jest ustawiona na true
ERROR: MONOLYNX_AUTOPUSH nie jest ustawiona na true w środowisku procesu
ERROR: MONOLYNX_BASE_BRANCH i MONOLYNX_MR_TARGET wskazują różne branche
PREFLIGHT: failed problems=2
```


Brzmienie linii w przykładzie jest poglądowe. Prawdziwy wynik zawsze kończy się linią `PREFLIGHT: ok` albo `PREFLIGHT: failed problems=<n>`.


**Porównanie**

| Objaw | Przyczyna | Naprawa |
| --- | --- | --- |
| Błąd o flagach `AUTOTEST`, `AUTOCOMMIT` albo `AUTOPUSH` | flagi nie ma w środowisku procesu ticku | ustaw wszystkie trzy na `true` w śledzonym `.claude/settings.json` |
| Błąd o dwóch różnych branchach | `MONOLYNX_BASE_BRANCH` i `MONOLYNX_MR_TARGET` wskazują różne branche | zostaw jedną zmienną, zwykle `MONOLYNX_MR_TARGET` |
| Błąd o pliku settings | plik `.claude/settings.json` ma błąd składni JSON | popraw plik; błąd podaje linię i kolumnę |
| Błąd o trybie uprawnień | ustawiono tryb omijający wszystkie zgody | usuń to ustawienie albo ustaw `MONOLYNX_SPRINT_PERMISSION_MODE=auto` |
| Kontrola przechodzi, a sesje nie startują | wszystkie sloty zajęte albo osiągnięty limit sesji `waiting` | odpowiedz czekającym sesjom |
| Ticket nie dostaje sesji mimo wolnych slotów | ticket ma niezamknięty bloker, etykietę `needs-local` albo status inny niż Do zrobienia | zamknij bloker, zdejmij etykietę albo zmień status |
| `SPRINT-RUN STOP` o nieaktualnym checkoucie | główny checkout jest za zdalnym branchem bazowym | dociągnij branch w głównym checkoucie i poczekaj na następny tick |



**Ticket z etykietą needs-local**

Etykieta `needs-local` oznacza ticket, który wymaga lokalnego środowiska albo decyzji człowieka, na przykład zmiany w konfiguracji CI. Dyspozytor nigdy nie startuje go w tle. Taki ticket prowadzisz sam, w zwykłej sesji, komendą `/monolynx:work`. Sprint, w którym zostały tylko takie tickety, nie zakończy się sam: linia statusu pokazuje `remaining` większe od zera, a nic nie pracuje.


## Sesja ticketu stoi albo skończyła się bez wyniku

Problemy tej warstwy widać w polu `waiting` linii statusu i w werdykcie `needs_human`.


**Porównanie**

| Objaw | Przyczyna | Naprawa |
| --- | --- | --- |
| Werdykt `waiting` z pytaniem | sesja trafiła na decyzję spoza kontraktu ticketu | wejdź komendą `claude attach <id>` i odpowiedz |
| Werdykt `waiting`, powód "brak postępu" | log sesji nie zmienił się przez dwa ticki | sprawdź `claude logs <id>`; sesja mogła czekać na długie testy albo CI |
| `SPRINT-RUN STOP: kolizja testów` | równoległe sesje współdzielą stan testów, na przykład jedną bazę | uruchom testy ponownie, gdy inne sesje skończą; docelowo dodaj izolację testów do strony `Toolchain` |
| `SPRINT-RUN STOP: fast-forward ... odrzucony` | branch ticketu rozjechał się z branchem bazowym | rozwiąż rozjazd ręcznie w worktree sesji |
| `SPRINT-RUN STOP: pełny przebieg ci bez MR` | projekt puszcza pełne testy w CI, a brakuje zgody na push albo merge request | ustaw `MONOLYNX_AUTOCOMMIT`, `MONOLYNX_AUTOPUSH` i `MONOLYNX_AUTOMR` na `true` |
| Werdykt `needs_human` | sesja skończyła się bez wyniku, także po jednym automatycznym wznowieniu | przeczytaj komentarz w tickecie i log sesji, popraw ticket albo dokończ ręcznie |
| Sesja pyta o każdą komendę | sesja wystartowała w trybie uprawnień, który wymaga potwierdzeń | zostaw domyślny tryb `auto` w `MONOLYNX_SPRINT_PERMISSION_MODE` |


> [!IMPORTANT]
> Masowe błędy przygotowania testów przy zielonych testach zmienionego obszaru to kolizja środowiska, nie regresja. Agent nie poprawia wtedy kodu i nie zużywa limitu poprawek. Uruchamia testy ponownie raz, a potem oddaje decyzję człowiekowi.

Jak wejść do sesji i odpowiedzieć, opisuje wpis [Sesje w tle: jak obserwować pętle sprintu i odpowiadać agentom](https://monolynx.com/blog/sesje-w-tle-monolynx).

## Merge request nie wchodzi

Kolejka `mr-queue` sprawdza merge request w stałej kolejności: konflikt, CI, zatwierdzenie, merge. Zatrzymuje się na pierwszej przeszkodzie i mówi, czego potrzebuje, w linii raportu zaczynającej się od "Potrzebne:".


**Porównanie**

| Werdykt albo objaw | Przyczyna | Naprawa |
| --- | --- | --- |
| Kolejka kończy tick prośbą o logowanie | `glab` albo `gh` nie jest zalogowane | uruchom `glab auth login` albo `gh auth login` |
| `wait` | pipeline merge requesta jeszcze trwa | nic; następny tick sprawdzi ponownie |
| `conflict` | branch docelowy zmienił się od otwarcia merge requesta | nic; kolejka sama merguje branch docelowy do brancha merge requesta |
| `ci_failed` | czerwony pipeline merge requesta | nic przez dwie rundy; kolejka poprawia sama |
| Kolejka stoi po dwóch rundach poprawek | poprawka CI nie udała się dwa razy | popraw branch ręcznie i wypchnij zmianę |
| `needs_approval` | merge request nie ma zatwierdzenia | przejrzyj i zatwierdź; tego nie zrobi żadna flaga |
| `needs_human` po anulowanym pipeline | ktoś ręcznie anulował pipeline | uruchom pipeline ponownie; kolejka nie ponawia cudzej decyzji |
| Kolejka stoi po merge do domyślnego brancha | CI domyślnego brancha jest czerwone | popraw branch osobnym merge requestem; kolejka ruszy po zielonym CI |



**Kod 137 w zadaniu CI**

`exit status 137` bez żadnego czerwonego testu oznacza, że kontener z testami został zabity, najczęściej przez brak pamięci na runnerze albo przez inne zadanie na tej samej maszynie. To nie jest błąd kodu. Kolejka ponawia takie zadanie i nie liczy tego jako rundy poprawek. Gdy 137 wraca regularnie, sprawdź pamięć runnera i to, czy równoległe zadania nie używają tych samych nazw kontenerów.


> [!TIP]
> Merge request innego autora kolejka poprawia dopiero po Twojej zgodzie. Jeśli tick staje z pytaniem o push do cudzego brancha, to nie błąd, tylko granica, której kolejka sama nie przekracza.

## Zamknięcie sprintu i wiki

Ostatnia grupa to problemy przy `sprint-end` i komendach wiki.


**Porównanie**

| Objaw | Przyczyna | Naprawa |
| --- | --- | --- |
| `sprint-end` mówi, że nie ma aktywnego sprintu | sprint nie został wystartowany albo już jest zamknięty | podaj nazwę sprintu jako argument |
| Logi sprintu nie zostały usunięte | INGEST do wiki się nie powiódł, więc logi zostają jako jedyne źródło wiedzy | popraw przyczynę i uruchom `sprint-end` ponownie |
| Po zamknięciu tickety wróciły do backlogu | nie miały statusu Gotowe w chwili zamknięcia | przypisz je do następnego sprintu |
| `wiki-sync-merge` kończy się bez zapisu | checkout nie stoi na branchu integracyjnym | przejdź na ten branch i uruchom ponownie |
| Agent nie może usunąć strony albo ticketu | rola `member` nie ma prawa usuwania | poproś o rolę z prawem usuwania |


## Najczęstsze pytania


**FAQ**

### Czy mogę bezpiecznie uruchomić pętlę ponownie po błędzie?
Tak. Tick jest idempotentny: czyta stan od zera i nie dubluje sesji ani komentarzy. Ponowne uruchomienie po naprawie konfiguracji jest zawsze bezpieczne.

### Sesja czeka od wczoraj. Czy coś przepadło?
Nie. Sesja `waiting` i jej worktree zostają nietknięte, dopóki sam ich nie usuniesz. Wejdź do niej, odpowiedz, a praca ruszy od miejsca zatrzymania.

### Skąd wiem, że to problem środowiska, a nie kodu?
Dwa znaki: testy zmienionego obszaru są zielone, a błędy pojawiają się masowo na etapie przygotowania testów albo zadanie CI kończy się kodem 137 bez czerwonego testu.

### Co, jeśli mojego objawu nie ma w tabelach?
Zacznij od `/monolynx:next`. Jeśli to nie pomoże, przeczytaj log sesji komendą `claude logs <id>` i ostatnią linię statusu. Powód zatrzymania jest tam zawsze zapisany wprost.

### Czy agent może sam ominąć blokadę, żeby iść dalej?
Nie powinien i reguły pluginu tego pilnują. Zamiast obchodzić odmowę inną komendą, sesja kończy turę linią `STOP` z powodem. Obejście blokady to decyzja człowieka.


## Słownik i następny krok


**Słownik**

- **Kontrola wstępna** - sprawdzenie środowiska na początku ticku, zanim wystartuje jakakolwiek sesja; w komunikatach nazywana preflight
- **Linia STOP** - jedna linia z powodem, którą sesja albo kolejka kończy turę, gdy potrzebuje decyzji człowieka
- **Werdykt** - stan ticketu albo merge requesta policzony przez skrypt, a nie odgadnięty z opisu
- **Runda poprawek** - jedna próba naprawy czerwonego CI przez kolejkę; limit to dwie
- **Kolizja testów** - błędy testów spowodowane współdzieleniem środowiska przez równoległe sesje
- **Idempotentny** - bezpieczny do powtórzenia: drugie uruchomienie nie zmienia wyniku pierwszego


Cały obieg, w którym te problemy mogą się pojawić, opisuje przewodnik [Sprint z Monolynx krok po kroku](https://monolynx.com/blog/sprint-z-monolynx-krok-po-kroku), a pierwszą konfigurację wpis [Pierwszy projekt w Monolynx](https://monolynx.com/blog/pierwszy-projekt-w-monolynx).


**Wezwanie do działania**

Chcesz widzieć błędy aplikacji i dostępność usług w tym samym miejscu co sprint?

[Zobacz moduł Monitoring w Monolynx](https://monolynx.com/features/monitoring)