# 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 kontener od pane zewnętrznego tmuxa. Procesy wewnątrz żyją 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ę.

`attach` i `detach` operują na połączeniu pane z kontenerem. Neovim i
Termdebug są zawartością jego sesji. `detach` 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.