# Hydra OS terminal experience implementation plan

> **For agentic workers:** Use superpowers:subagent-driven-development. Tasks
> are implemented in the shared feature worktree with disjoint owned files,
> then reviewed and integrated before publication.

**Goal:** Download and open VMs through a concise terminal workflow and ship
consistent Hydra OS branding with Fastfetch.

**Architecture:** Retain Runtime as the VM lifecycle authority. Add a safe ISO
download module and explicit launch orchestration. Replace recovery's JSON
prompt with a terminal menu and use the existing session-refresh boundary to
focus a selected workspace without changing QEMU lifetimes.

**Tech stack:** Python standard library, existing labwc/Foot/SPICE, Gentoo,
Fastfetch. No GUI toolkit or host NixOS changes.

**Spec:** `docs/superpowers/specs/2026-10-13-terminal-ux-design.md`

## Global constraints

- Visible product name is **Hydra OS**; preserve technical identifiers and data.
- No NixOS configuration changes, user-disk replacement or guest input injection.
- Opening a selected stopped VM is explicit; menu display never starts all VMs.
- Existing CLI output and runtime ownership guarantees remain compatible.
- Downloads publish only verified complete ISO files; SHA-256 is optional.
- New launch preflight reserves 768 MiB of available RAM for the Hydra host.

## Review focus

- Concurrent downloads or interruption must not publish partial ISO files (T1).
- Existing names/disks and unknown VM identities must not be replaced (T1).
- Selecting a second VM must focus it and preserve other QEMU processes (T2).
- Invalid profiles, missing ISO, absent network tools must leave a usable menu (T2).
- Branding must not invalidate existing IDs or rewrite historical evidence (T3).

## Task 1: Download and explicit launch commands

Owned: `hydra/media.py`, `hydra/launch.py`, `hydra/cli.py`,
`tests/test_media.py`, `tests/test_launch.py`, relevant new CLI tests.

Interfaces:
- `media.download_iso(url, *, sha256=None, cache=None, progress=None) -> Path`.
  `progress(received_bytes, total_bytes_or_none)` is optional.
- `launch.open_vm(runtime, name, *, windowed=False, no_view=False,
  manifest=None) -> int`. For a session manifest call
  `session.request_refresh(manifest, selected=name)` after successful launch;
  outside a session use existing `session.view`. No GUI check for `no_view`.
- CLI: `open NAME`, `run SOURCE --name NAME`, `download URL`; plain `hydra`
  and `hydra menu` call `menu.run_menu(runtime, manifest=...)` lazily.
- Manifest defaults from `HYDRA_SESSION_MANIFEST` when valid; launch errors
  remain actionable and never silently restart an unknown/foreign VM.

- [x] Write and observe failing tests using a local HTTP fixture (ISO, HTML,
  truncation, checksum, cancellation, cache reuse, collision).
- [x] Implement downloader and explicit open/run commands, preserve existing CLI.
- [x] Test no accidental overwrite/start, headless operation, RAM preflight and
  view-only reconnection. Run scoped tests and commit only owned files.

## Task 2: Terminal menu and focused session handoff

Owned: `hydra/menu.py`, `hydra/session.py`, `tests/test_menu.py`,
`tests/test_session.py`, relevant `dev/session-refresh-smoke.py` extensions.

Interfaces:
- `menu.run_menu(runtime, *, manifest=None) -> int`: clear readable menu,
  numbers/names/Enter, persistent last selection, old colon commands, controlled
  guided `run`/`download`, network and shell actions. Use Task 1's launch API.
- `session.request_refresh(manifest: Path, *, selected=None) -> int`: backwards
  compatible empty refresh requests, optional validated selected VM name.
- Session env carries `HYDRA_SESSION_MANIFEST`; next compositor starts on the
  requested configured VM. Recovery delegates to menu; automatic clients remain
  view-only. Errors stay in menu, and operations use fresh runtime profiles.

- [x] Write failing menu/refresh tests for stopped/running selection, unknown
  identity, names such as s/q, empty/invalid profiles and second-workspace focus.
- [x] Implement terminal flow, visible command previews and recovery fallback.
- [x] Run scoped tests plus an isolated session probe where feasible; commit
  owned files. Existing reserved chords and VM independence remain intact.

## Task 3: Hydra OS branding and Fastfetch

Owned: `image/packages`, `image/rootfs` (Fastfetch config/logo/motd only),
`hydra/image.py`, `image/grub.cfg`, `session` metadata, new branding tests.
Coordinate session/CLI visible names with their owners; do not edit their files.

- [x] Confirm Fastfetch's Gentoo atom, supported logo/config format and search path.
- [x] Add original terminal logo and restrained summary configuration; retain
  technical IDs while updating visible OS/boot/session labels.
- [x] Verify config with actual Fastfetch in a temporary/container environment,
  preview logo, and test resulting image metadata. Commit owned files.

## Task 4: Integration and delivery

Owner: controller. README/install docs, update bundle, isolated validation.

- [x] Review each task diff with concrete test reports; resolve findings.
- [x] Integrate task interfaces; document terminal usage and branded name.
- [x] Run complete suite and isolated smoke covering run/open/menu with new code.
- [x] Prepare a reversible guest update with exact file inventory and checksums;
  preserve old ISO and test disk. Assess cached image rebuild and test new output.
- [x] Review whole branch, commit/publish authorized repository changes and report
  exactly which artifacts and guest states have actually been updated.