stem-launcher/doc/session.md

Sesja karty z wiersza poleceń

stemctl session łączy pięć selektorów w jeden kontrakt:

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

./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

# 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:

./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.

./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:

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.