# `stemctl` — sterowanie sesją zajęć

`stemctl session` łączy wybór materiału, kontenera, stanu UML i zewnętrznego
pane tmuxa. Szczegółowy opis wyboru checkpointów znajduje się w
[`session.md`](session.md); ten dokument definiuje znaczenie poleceń cyklu
życia.

## Model połączenia

```text
pane tmuxa na hoście
        │
        │ attach / detach
        ▼
wybrany kontener
        └── wewnętrzny tmux → Neovim + Termdebug/GDB + symulator lub RP2350
```

## Katalog i organizacje Gitea

`workspace-info/workspace.json` jest źródłem prawdy. Organizacja `edu` pełni
rolę control plane, a stabilne serie mają osobne organizacje o nazwie
`edu-<series-id>`. Karta jest repozytorium wewnątrz organizacji swojej serii.

```bash
stemctl workspace audit
stemctl series list
stemctl series cards list freertos-c
stemctl series cards show freertos-c FC02
```

`workspace audit` jest lokalny i deterministyczny: sprawdza kontrakt katalogu,
nie modyfikuje Gitea. Dzięki temu brak sieci nie uniemożliwia przeprowadzenia
zajęć z wcześniej zsynchronizowanego workspace.

Obiektem operacji `attach` i `detach` jest **połączenie pane z kontenerem**.
Neovim i Termdebug są zawartością sesji kontenera, a nie osobnym obiektem
podpinanym przez launcher.

- `attach` podpina wybrany, działający kontener do wskazanego pane i pokazuje
  jego istniejącą sesję Neovim/Termdebug;
- `detach` zastępuje widok kontenera zwykłą powłoką hosta w tym pane;
- `detach` nie zatrzymuje kontenera, wewnętrznego tmuxa, Neovima, GDB,
  symulatora ani połączenia z RP2350;
- ponowne `attach` wraca do tej samej działającej sesji;
- `stop` i `rm`, a nie `detach`, zmieniają cykl życia kontenera.

## Polecenia sesji

| Polecenie | Znaczenie |
| --- | --- |
| `session choices` | Wyświetla numerowane serie, karty, Taski i etapy UML. |
| `session status` | Sprawdza kontener, MCP, tożsamość karty i bieżący etap. |
| `session start` | Uruchamia kontener i jego środowisko pracy. |
| `session reset` | Usuwa i odtwarza kontener, następnie opcjonalnie odtwarza checkpoint. |
| `session refresh` | Zachowuje kontener i odnawia jego podpięcie oraz wybór MCP. |
| `session attach` | Podpina istniejący kontener do pane tmuxa na hoście. |
| `session detach` | Odpina kontener od pane bez zatrzymywania czegokolwiek wewnątrz. |
| `session stage` | Ustawia wybrany etap UML; alias: `session checkpoint`. |

## Wybór celu

Serię, kartę, Task i elementy UML można wskazywać stabilnym ID albo numerem
pokazanym przez `choices`:

```bash
stemctl session choices --series inf --card 7 --task 4

stemctl session reset hazard3-sim \
  --series inf --card 7 --task 4 \
  --step 12 --pane current:0
```

Najważniejsze selektory:

- środowisko: `profile`, `--target`, `--instance`;
- materiał: `--series`, `--card`, `--task`;
- UML: `--stage`, `--block`, `--phase`, `--step`, `--snapshot`, `--first`;
- widok: `--pane`, `--focus`, `--offline`, `--control`;
- wykonanie: `--card-url`, `--timeout`, `--force-pane`, `--dry-run`.

`--pane current:0` oznacza pane `0` tego okna tmuxa, w którym uruchomiono
Codexa. Można także podać `%ID` albo `sesja:okno.pane`. Launcher chroni pane
wykonujące bieżącą komendę i pane oznaczone jako należące do innej sesji
Codexa.

## Przykłady attach i detach

```bash
# Podepnij działający kontener Task04 do pane 0 bieżącego okna.
stemctl session attach hazard3-sim \
  --series inf --card 7 --task 4 --pane current:0

# Wróć w pane 0 do powłoki hosta. Kontener i debugowanie nadal działają.
stemctl session detach hazard3-sim \
  --series inf --card 7 --task 4 --pane current:0
```

## Status materiału

`session choices` pokazuje jedną z trzech wartości:

- `opracowane` — kompletny materiał wraz z receptą checkpointu;
- `robocze` — źródło lub metadane istnieją, ale nie są kompletne;
- `brak` — materiał nie jest jeszcze dostępny w workspace.