From 2408d56d14d11db89c3b2db95cb212657ca92fbc Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 13 Oct 2026 03:58:07 +0300 Subject: [PATCH] docs: define Gentoo HydraOS target and implementation plan --- .gitignore | 15 ++ README.md | 26 ++++ docs/hardware/asus-fx517zc.md | 22 +++ .../plans/2026-10-13-graphics-session.md | 91 ++++++++++++ .../2026-10-13-graphics-session-design.md | 130 ++++++++++++++++++ 5 files changed, 284 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 docs/hardware/asus-fx517zc.md create mode 100644 docs/superpowers/plans/2026-10-13-graphics-session.md create mode 100644 docs/superpowers/specs/2026-10-13-graphics-session-design.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..81aebd1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,15 @@ +.worktrees/ +.superpowers/ +__pycache__/ +*.py[cod] +.pytest_cache/ +.venv/ +build/ +dist/ +state/ +cache/ +*.qcow2 +*.iso +*.img +*.log +*.sock diff --git a/README.md b/README.md new file mode 100644 index 0000000..647765f --- /dev/null +++ b/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. diff --git a/docs/hardware/asus-fx517zc.md b/docs/hardware/asus-fx517zc.md new file mode 100644 index 0000000..0c546b8 --- /dev/null +++ b/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. diff --git a/docs/superpowers/plans/2026-10-13-graphics-session.md b/docs/superpowers/plans/2026-10-13-graphics-session.md new file mode 100644 index 0000000..d28b4d2 --- /dev/null +++ b/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. diff --git a/docs/superpowers/specs/2026-10-13-graphics-session-design.md b/docs/superpowers/specs/2026-10-13-graphics-session-design.md new file mode 100644 index 0000000..bad5b96 --- /dev/null +++ b/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 является реализационной деталью, не требованием пользователя.