Hydra-OS/docs/superpowers/plans/2026-10-13-terminal-ux.md

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.

• Write and observe failing tests using a local HTTP fixture (ISO, HTML, truncation, checksum, cancellation, cache reuse, collision).

• Implement downloader and explicit open/run commands, preserve existing CLI.

• 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.

• Write failing menu/refresh tests for stopped/running selection, unknown identity, names such as s/q, empty/invalid profiles and second-workspace focus.

• Implement terminal flow, visible command previews and recovery fallback.

• 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.

• Confirm Fastfetch's Gentoo atom, supported logo/config format and search path.
• Add original terminal logo and restrained summary configuration; retain technical IDs while updating visible OS/boot/session labels.
• 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.

• Review each task diff with concrete test reports; resolve findings.
• Integrate task interfaces; document terminal usage and branded name.
• Run complete suite and isolated smoke covering run/open/menu with new code.
• 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.
• Review whole branch, commit/publish authorized repository changes and report exactly which artifacts and guest states have actually been updated.