docs: define Gentoo HydraOS target and implementation plan

.gitignore

@@ -0,0 +1,15 @@
+.worktrees/
+.superpowers/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+build/
+dist/
+state/
+cache/
+*.qcow2
+*.iso
+*.img
+*.log
+*.sock

README.md

@@ -0,0 +1,26 @@
+# HydraOS
+
+Gentoo-based host for concurrent virtual desktops. Its default session shows one
+VM fullscreen and switches between guests with keyboard shortcuts. Other host
+desktops may use the same independent VM manager and viewers.
+
+## Status
+
+Under active development, not yet an installation-ready distribution. The target
+is an installable UEFI ISO, first validated on ASUS TUF Dash F15 FX517ZC. Existing
+NixOS and VM disks are not installation or test targets.
+
+1. Independent QEMU/KVM lifecycle with private QMP control.
+2. Minimal labwc session and fullscreen SPICE viewers.
+3. Gentoo rootfs, live ISO, explicit disk installer.
+4. Disposable-disk installation/reboot tests, then physical live-boot checks.
+
+Shared clipboard and directories are opt-in. VM processes survive viewer and
+compositor exits. GPU passthrough and graphics performance require hardware tests;
+a refresh-rate setting does not prove delivered FPS.
+
+- [Session design](docs/superpowers/specs/2026-10-13-graphics-session-design.md)
+- [Implementation plan](docs/superpowers/plans/2026-10-13-graphics-session.md)
+- [Hardware target](docs/hardware/asus-fx517zc.md)
+
+Build outputs, VM disks, runtime state and credentials stay outside Git.

docs/hardware/asus-fx517zc.md

@@ -0,0 +1,22 @@
+# ASUS TUF Dash F15 FX517ZC
+
+Read-only inventory 2026-10-13; no serial numbers or machine identifiers.
+
+| Component | Hardware | Driver / requirement |
+| --- | --- | --- |
+| CPU | i7-12650H, 10 cores / 16 threads | KVM Intel, VT-x |
+| RAM | 32 GB nominal | Four build jobs initially; avoid disrupting existing VMs |
+| Display | Intel Alder Lake-P UHD 8086:46a3 | i915, internal eDP, intel_backlight |
+| Discrete GPU | RTX 3050 Mobile 10de:25a2 | Initial shell uses Intel; test NVIDIA separately |
+| Wi-Fi | Intel CNVi 8086:51f0 | iwlwifi/iwlmvm, linux-firmware |
+| Ethernet | Intel I219-LM 8086:1a1e | e1000e |
+| Audio | Intel PCH-P 8086:51c8 | snd_hda_intel, SOF firmware |
+| NVMe | Intel 8086:f1aa behind VMD 8086:467f | vmd and nvme in initramfs |
+| USB | Intel 8086:461e, 8086:51ed | xhci_pci |
+| Thunderbolt | Intel 8086:463e | thunderbolt |
+| Laptop controls | ASUS | asus_wmi, asus_nb_wmi |
+
+UEFI boot, Secure Boot currently disabled. Include vmd, nvme, xhci_pci,
+thunderbolt, usb_storage, sd_mod in boot coverage. Target physical refresh144Hz;
+actual guest frame delivery must be measured. About290GiB build storage free at
+inventory. Initial RAM headroom about10GiB with existing sessions running.

docs/superpowers/plans/2026-10-13-graphics-session.md

@@ -0,0 +1,91 @@
+# 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.
+
+**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.
+- [ ] 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.

docs/superpowers/specs/2026-10-13-graphics-session-design.md

@@ -0,0 +1,130 @@
+# HydraOS: минимальная графическая сессия хоста
+
+Решение первого этапа, 13 октября 2026 года. Пользователь подтвердил Gentoo,
+устанавливаемый ISO, ASUS TUF Dash F15 FX517ZC и автономную разработку.
+
+## Назначение
+
+HydraOS должна стать устанавливаемым Linux-дистрибутивом для одновременной
+работы нескольких виртуальных машин. Пользователь видит рабочий стол выбранной
+VM на весь экран и переключает машины горячими клавишами. Хост обеспечивает
+оборудование, сеть и управление VM; его графический интерфейс обычно незаметен.
+
+Подтверждённые требования: минимальная оболочка хоста по умолчанию, отсутствие
+впечатления вложенных окон, переключение клавишами, совместимость управления
+VM с другими окружениями хоста. Гостевые окружения выбираются независимо.
+Gentoo выбрана основой будущего дистрибутива. Первый этап проверяет
+графическую сессию до изготовления установочного ISO.
+
+## Решение первого этапа
+
+Предлагается labwc как композитор стандартной сессии и отдельный SPICE-просмотрщик
+для каждой VM. Панель, меню рабочего стола, оформление окон и обычные сочетания
+оконного менеджера в этой сессии не нужны. На физическом экране всегда находится
+один полноэкранный просмотрщик. Его обычный интерфейс должен быть скрыт; выбор
+USB и восстановление доступа к хосту остаются доступны по явному действию.
+
+Первый прототип рассчитан на один физический экран. Режим без рамок включает
+отсутствие всплывающей панели просмотрщика при подведении указателя к краю.
+До основной реализации отдельно проверяются два условия: сохранение
+зарезервированных клавиш хоста при захвате ввода SPICE и возможность явно
+открыть управление USB при скрытом интерфейсе просмотрщика. Если выбранный
+режим remote-viewer этого не допускает, способ управления пересматривается;
+доступность этих функций пока не считается подтверждённой.
+
+Несколько VM и их просмотрщики продолжают работать при переключении. Меняется
+видимый просмотрщик, а не питание или состояние гостя. Переключение не должно
+требовать повторной загрузки ОС или подключения к SPICE.
+
+Существующий прототип `/home/workspaces/niri-vm-lab` служит источником проверенных
+решений для виртуального оборудования и сети. Его работающие VM и диски не
+используются как тестовые объекты новой графической сессии.
+
+## Границы компонентов и совместимость
+
+- Управление VM: параметры QEMU, отдельные диски, запуск, состояние, штатное
+  выключение, приватные сокеты QMP и SPICE. Этот компонент не вызывает labwc
+  или Niri и не требует работающей графической сессии.
+- Запуск просмотрщика: подключение к выбранной VM. В обычном окружении хоста
+  просмотрщик может работать окном; графический backend определяется средой.
+- Сессия HydraOS: настройка labwc, полноэкранный показ, фокус, горячие клавиши
+  переключения и восстановление после закрытия просмотрщика.
+- Упаковка дистрибутива: ядро, драйверы, пакеты, запуск сессии, установка и
+  обновления. Это следующий самостоятельный этап после проверки оболочки.
+
+В KDE, GNOME и других окружениях хоста должны оставаться доступны общие команды
+управления и оконные просмотрщики. Специальная политика захвата клавиатуры и
+переключения полноэкранных VM гарантируется только после проверки конкретной
+сессии. Установка другой оболочки не должна менять формат профилей или дисков.
+Одновременная работа нескольких полноценных сессий хоста и передача физического
+экрана между ними в первый этап не входят.
+
+## Ввод и поведение при сбоях
+
+В стандартной сессии Meta, Alt+Tab и переключение раскладки передаются гостю.
+Для хоста резервируются Ctrl+Alt+Shift+Left/Right для смены VM и отдельное
+аварийное сочетание Ctrl+Alt+Shift+Escape для освобождения ввода и доступа к
+локальному управлению. Клавиши яркости управляют физическим экраном хоста.
+Общий буфер обмена и общие папки не включаются автоматически.
+
+Завершение или сбой просмотрщика либо композитора не выключает VM. Повторный
+запуск сессии подключается к работающим машинам. Ошибка подключения показывается
+коротким сообщением с возможностью повторить подключение или открыть аварийный
+терминал; она не приводит к автоматическому сбросу VM.
+
+Управляющие команды не передаются через гостевую клавиатуру. Горячие клавиши
+хоста должны срабатывать и при захваченном вводе просмотрщика. Отключение всех
+привязок labwc через ToggleKeybinds не подходит без проверки аварийного выхода
+и переключения VM.
+
+## Проверка перед упаковкой в ISO
+
+Используются отдельные временные VM и диски. Сначала проверяется вложенная
+тестовая сессия, затем самостоятельная сессия на TTY: первая не доказывает
+корректность захвата клавиш или работу физического экрана.
+
+Критерии приёмки:
+
+1. Два гостя переключаются клавишами без рамок, панели и интерфейса просмотрщика.
+2. Фоновая задача в скрытой VM продолжает работу; QEMU не перезапускается.
+3. Meta, Alt+Tab, раскладка и указатель работают в госте, а переключение VM,
+   яркость и аварийный выход остаются доступны хосту.
+   Проверяется также смена VM при удерживаемых модификаторах и кнопке мыши:
+   в покинутом госте не остаются зажатыми клавиши, а в новом не возникают
+   случайные действия из-за переданных отпусканий или состояния ввода.
+4. После закрытия просмотрщика или сессии VM остаются доступны по сети;
+   повторное подключение восстанавливает изображение.
+5. В обычной сессии хоста работает оконный просмотрщик и общее управление VM.
+6. Измеряются задержка переключения и обновление скрытых поверхностей. Замена
+   композитора не считается доказательством исправления ограничений VirGL/SPICE
+   или достижения 144 FPS. Если существующие просмотрщики не обеспечивают
+   требуемое поведение, выбор способа вывода пересматривается до сборки ISO.
+
+На этом этапе не создаются собственный композитор, графическая панель управления,
+установщик или механизм обновления дистрибутива. Сначала проверяется пригодность
+минимальной сессии для ежедневного использования.
+
+## Основания выбора
+
+- [labwc](https://labwc.github.io/) и его
+  [действия](https://labwc.github.io/labwc-actions.5.html): готовые механизмы окон,
+  полноэкранного режима, рабочих пространств и клавиатурного управления.
+- [Cage](https://github.com/cage-kiosk/cage): вариант для одного собственного
+  приложения HydraOS; самостоятельное управление несколькими просмотрщиками
+  потребует дополнительной реализации.
+- [Weston kiosk-shell](https://wayland.pages.freedesktop.org/weston/toc/kiosk-shell.html):
+  полноэкранные приложения и распределение по экранам; переключение VM придётся
+  дополнительно проектировать.
+- [Smithay](https://github.com/Smithay/smithay): основа собственного композитора
+  на Rust, с существенно большим объёмом ответственности за графику и ввод.
+
+## Уточнения реализации
+
+- Python 3.11+ и стандартная библиотека для переносимого CLI `hydra`.
+- labwc >= 0.20.0: обязательные host bindings используют overrideInhibition.
+- Профили TOML, состояние и приватные Unix-сокеты QMP/SPICE разделены.
+- Meta/Alt+Tab и default mouse bindings хоста не подключаются.
+- Полный проект ведётся автономно; локальные патчи зависимостей разрешены.
+- Сборка Gentoo идёт в отдельном builder; физические диски не являются целями тестов.
+- Для первой версии выбран Gentoo systemd stage3: logind, cgroups и независимые
+  службы VM; выбор init является реализационной деталью, не требованием пользователя.