feat: orchestrate lesson sessions from stemctl

doc/session.md

@@ -0,0 +1,113 @@
+# Sesja karty z wiersza poleceń
+
+`stemctl session` łączy pięć selektorów w jeden kontrakt:
+
+```text
+seria → karta → Task → blok/faza/krok/snapshot UML → instancja kontenera
+```
+
+Każdy selektor przyjmuje stabilne ID. Seria, karta, Task, blok, faza, krok i
+snapshot przyjmują także numery pokazywane przez `choices`. Numer karty jest
+jednobazową pozycją w manifeście serii, więc nie zależy od tego, czy repo karty
+zostało już pobrane. W przypadku kroków najpierw sprawdzany jest globalny numer
+strzałki z diagramu, a przy jawnie wybranej fazie także lokalny numer kroku.
+
+## Lista wyboru
+
+```bash
+./stemctl session choices --series inf --card 7 --task 4
+./stemctl session choices --series inf --card pointers --json
+```
+
+Tabele zawierają kolumnę `status`:
+
+- `opracowane` — materiał UML ma komplet recept replay/checkpoint;
+- `robocze` — istnieje źródło albo częściowe metadane;
+- `brak` — karta lub materiał nie znajduje się jeszcze w workspace.
+
+## Sterowanie środowiskiem
+
+```bash
+# Utwórz debugger Task04 w pane 0 okna, z którego uruchomiono Codexa.
+./stemctl session start hazard3-sim --series inf --card 7 --task 4
+
+# Usuń i odtwórz kontener, po czym zatrzymaj maszynę na strzałce 12.
+./stemctl session reset hazard3-sim \
+  --series inf --card 7 --task 4 --step 12
+
+# Zachowaj kontener i ponownie podepnij istniejący debugger.
+./stemctl session refresh hazard3-sim --series inf --card 7 --task 4
+
+# Podepnij/odepnij tylko klienta w zewnętrznym tmuxie. Serwer debuggera żyje dalej.
+./stemctl session attach hazard3-sim --series inf --card 7 --task 4
+./stemctl session detach hazard3-sim --series inf --card 7 --task 4
+```
+
+Domyślny cel `--pane current:0` oznacza pane `0` tego samego okna tmuxa, w
+którym działa wywołujący Codex. Można podać jawne `%ID`, `sesja:okno.pane` albo
+`--pane none`. Launcher odmawia zastąpienia pane, z którego sam został
+uruchomiony, aby nie zakończyć Codexa. Pane Codexa jest dodatkowo oznaczone
+PID-em pane w opcjach tmuxa; jawne `%ID` podane z innego terminala również
+zostanie odrzucone. Świadome obejście tej drugiej ochrony wymaga
+`--force-pane`; nie da się nim zastąpić pane wykonującego bieżącą komendę.
+
+`detach` odłącza wyłącznie zewnętrznego klienta tmuxa. Nie zatrzymuje
+kontenera, symulatora, GDB, Neovima ani wewnętrznej sesji tmuxa.
+
+## Wybór stanu UML
+
+Równoważne przykłady:
+
+```bash
+./stemctl session stage hazard3-sim --series inf --card 7 --task 4 --step 12
+./stemctl session checkpoint hazard3-sim --series inf --card pointers --task 4 \
+  --snapshot task04.alloc5.commit
+./stemctl session stage hazard3-sim --series inf --card 7 --task 4 --stage alloc-5/7
+./stemctl session stage hazard3-sim --series inf --card 7 --task 4 \
+  --stage task04/allocator-flow/alloc-5/alloc5-commit
+./stemctl session stage hazard3-sim --series inf --card 7 --task 4 \
+  --phase 2 --step 3
+./stemctl session stage hazard3-sim --series inf --card 7 --task 4 --first
+```
+
+W ostatnim przykładzie `3` oznacza trzeci krok wewnątrz drugiej fazy, jeżeli
+w tej fazie nie istnieje globalna strzałka numer 3.
+
+Tryb online najpierw sprawdza pełną tożsamość karty (`id`, UUID, wersję i hash
+źródłowego JSON-a), receptę checkpointu, profil, target oraz bind mount
+`/workspace`. Następnie wybiera sockety MCP i przekazuje kontrolerowi
+oczekiwane `instance/container_id/profile/target`. Replay zostaje odrzucony,
+jeżeli globalny wybór MCP zmieni się przed aktywacją albo podczas niej. Dopiero
+po udanym zatrzymaniu GDB publikowane są pozycja strony i `SYNC ON`.
+
+`--offline` zmienia wyłącznie stan strony i wyłącza SYNC/sterowanie Neovimem.
+`--control` dodatkowo uzbraja sterowanie klawiaturą Neovima; samo SYNC nie robi
+tego automatycznie. `stage/checkpoint` wymaga jawnego selektora; pierwszy etap
+wybiera się świadomie przez `--first`.
+
+```bash
+./stemctl session stage hazard3-sim --series inf --card 7 --task 4 \
+  --step 12 --offline
+./stemctl session status hazard3-sim --series inf --card 7 --task 4
+./stemctl session status hazard3-sim --series inf --card 7 --task 4 \
+  --json --strict
+```
+
+Adres serwera karty można zmienić przez `--card-url` albo `STEM_CARD_URL`.
+Limit oczekiwania na Neovima/GDB/MCP ustawia `--timeout`.
+
+## Przyszłe strategie i adnotacje
+
+Kluczem rozszerzeń pozostaje pełna pozycja
+`task/block/phase/step/snapshot`. Pod tym kluczem będzie można później
+przechowywać wiele strategii debugowania i adnotacji bez zmiany obecnego CLI.
+Planowany kontrakt rozdziela treść od widoczności:
+
+```text
+strategy: id, label, commands, expected_observations
+annotation: id, strategy_id, target, geometry, style, text, visible
+```
+
+`target` może wskazywać diagram, bufor/wiersz Neovima, rejestr, ramkę stosu
+albo zakres pamięci. Operacje `show/hide/toggle` mają zmieniać widoczność bez
+usuwania adnotacji; `add/remove` będą osobnymi, audytowalnymi operacjami.