# HydraOS Graphics Session Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans. Steps use checkbox syntax for tracking.

**Goal:** Validate independent VM management and fullscreen switching before Gentoo ISO packaging.

**Architecture:** Python CLI owns validated profiles, disks and private QMP connections. A separate labwc session owns viewer windows, workspaces and host shortcuts. Gentoo packaging follows in its own plan.

**Tech Stack:** Python3.11+ standard library, QEMU/KVM, virt-viewer/SPICE, labwc>=0.20.0.

**Spec:** ../specs/2026-10-13-graphics-session-design.md

## Global Constraints

- Gentoo, first target ASUS FX517ZC, UEFI, Secure Boot disabled.
- Preserve current NixOS, Ubuntu, VM lab and existing disks.
- Source in Ubuntu-owned project; temporary development tools permitted.
- QEMU lifetime independent of compositor/viewer.
- Tests use explicitly separate config/state/runtime paths.
- Private Unix QMP/SPICE sockets; no public management listener.
- Guest Meta/Alt+Tab; host Ctrl+Alt+Shift+Left/Right/Escape and brightness.
- No clipboard/directory sharing or USB auto-redirection by default.
- No overwrite of existing disks or unattended physical disk installation.

## Review Focus

- Stale records/reused PID must never stop another process: Task1 identity tests.
- Concurrent starts must never attach one writable disk twice: Task1 lock tests.
- Profile names and paths must not become shell syntax: Tasks1/2 escaping tests.
- Held keys/buttons during switches must not stick: Task3 input test.
- Missing display/GPU/ISO and viewer crash preserve guests: Tasks1–3 failure tests.

## File Structure

`bin/hydra` is the source-checkout entry point. `hydra/profiles.py`, `qmp.py`,
`runtime.py`, `cli.py` implement validated profiles, protocol, lifecycle, parsing.
`hydra/session.py` owns session configuration/viewer launch. `session/` contains
launcher assets; `patches/` holds necessary upstream adaptations. `tests/` uses
unittest; `dev/` holds pinned tools and disposable integration probes.

### Task 1: Independent VM lifecycle

**Files:** Create `bin/hydra`, `hydra/{__init__,profiles,qmp,runtime,cli}.py`, `tests/test_{profiles,qmp,runtime}.py`.

**Interfaces:**
- CLI globals `--config PATH`, `--state PATH`, `--runtime PATH`; defaults from XDG.
- Commands `add NAME --iso PATH [--memory 4096] [--cpus 2] [--disk-size 40G]`, `list`, `start NAME`, `status [NAME]`, `shutdown NAME`, `stop NAME --force`.
- Names match `[a-z][a-z0-9-]{0,31}`; individual `NAME.toml` profiles.
- `Profile` fields: name, iso, memory, cpus, disk_size, graphics(auto|software), network(user|bridge), bridge. Defaults: graphics auto, network user, bridge hydrabr0. Distribution networking follows later.
- `load_profile(path: Path) -> Profile`, `build_qemu_argv(profile: Profile, paths: VMPaths) -> list[str]`, `QMPClient.command(name: str, arguments: dict | None = None) -> dict`.
- `VMPaths` provides disk, log, lock and private QMP/SPICE sockets. Session consumes stable name and socket paths only.

- [ ] Write validation/QMP fake-server tests: invalid names/resources, missing ISO, paths containing spaces, greeting/capabilities, asynchronous events, IDs, timeouts.
- [ ] Run `python3 -m unittest discover -s tests -v`; observe failure before implementation.
- [ ] Implement validation and bounded QMP; subprocess argv arrays, named environment tool overrides for tests.
- [ ] Add lifecycle tests: simultaneous start, existing-disk preservation, stale socket, failed boot, shutdown vs force, QMP VM identity.
- [ ] Implement locked safe disk creation, detached QEMU, virtio disk/network, SPICE no clipboard/file transfer, optional Intel GL. No display dependency in manager and no PID-only stop.
- [ ] Run complete suite, help, scratch QEMU lifecycle probe. Commit `feat: add independent VM manager`.

### Task 2: Minimal fullscreen session

**Files:** Create `hydra/session.py`, `session/hydra-session`, `tests/test_session.py`, `dev/tools.nix`; amend CLI; optional narrow virt-viewer patch.

**Interfaces:** Consumes Task1 Profile/VMPaths. Produces `hydra view NAME [--windowed]`, `hydra session [--nested]`, labwc config only in selected runtime. Viewer title is deterministic from validated name; each VM maps to one workspace. Recovery opens host terminal; session never shuts down a VM.

- [ ] Probe actual labwc version/overrideInhibition and remote-viewer kiosk USB behavior on disposable state; record versions.
- [ ] Resolve manual USB dialog with a small upstream viewer adaptation if necessary; never auto-redirect USB.
- [ ] Write tests for valid escaped XML, exact window/workspace/fullscreen rules, no default keyboard/mouse bindings, overrideInhibition on host keys, missing viewer/display errors.
- [ ] Run session tests and observe missing implementation failure.
- [ ] Implement session/viewer commands and pinned temporary tool environment; no host installation.
- [ ] Run full tests and labwc config parsing. Commit `feat: add fullscreen HydraOS session`.

### Task 3: Integration and recovery

**Files:** Create `dev/smoke.py`, `docs/verification.md`; update README with verified commands. Amend runtime/profile/CLI/session tests and dependency patches for integration defects and the installed-guest workflow below.

**Interfaces:** Consumes Tasks1/2, produces disposable-VM integration evidence.

- [ ] Run two disposable KVM instances/viewers, never existing lab disks; verify private QMP and independent lifecycle.
- [ ] Verify viewer/session exit preserves QEMU and reattach works; switching neither restarts nor reconnects guests.
- [ ] Check input only in disposable session, without injecting into current host or user's guests; add regression tests for discovered defects.
- [ ] Resolve Task 2's observed USB shortcut dispatch failure; demonstrate manual selector opening without automatic USB redirection on the private display. Check reserved switching/recovery actions with a standard keymap and keyboard inhibition.
- [ ] Complete installed-guest boot workflow: optional installation media, explicit attach/detach while stopped, disk boot without the original ISO, and status/stop usable even if previously configured ISO disappears. Preserve exclusive disk creation and verified QMP control.
- [ ] Add validated display dimensions/optional refresh and distribution defaults under `/etc/hydra/defaults.toml`. Defaults affect newly created profiles only; explicit CLI values win. Developer default remains user networking and stock-QEMU-compatible refresh; installed Hydra uses hydrabr0 and ASUS 1920x1080/144000 mHz preference.
- [ ] Port the existing tested `qemu-virtio-refresh-rate.patch` from the old lab as a tracked dependency patch; validate the generated EDID and requested mode. Distinguish advertised refresh from achieved frame rate and physical display verification.
- [ ] Record held-key, physical brightness and 144Hz checks needing dedicated TTY. Nested tests cannot prove them.
- [ ] Run full suite and independent review; fix material findings with reproducing tests.
- [ ] Commit evidence and push reviewed prototype branch to supplied repository.

## Next plan

Stage3/rootfs, signed official binpkgs where suitable, kernel/firmware, dracut live
boot, squashfs/UEFI ISO and guarded installer. Acceptance: ISO boot, install to
blank disposable disk, reboot without ISO, persistent changes and working VM
session. Real laptop installation requires a selected disk and final consent.