From 71fb8eacbd64a22f25aa707c7f5117b73e9f592b Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 13 Oct 2026 21:26:18 +0300 Subject: [PATCH] Plan preserved installation and verified Hydra updates --- .../plans/2026-10-13-laptop-ready.md | 103 ++++++++++++++++++ .../specs/2026-10-13-laptop-ready-design.md | 96 ++++++++++++++++ 2 files changed, 199 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-13-laptop-ready.md create mode 100644 docs/superpowers/specs/2026-10-13-laptop-ready-design.md diff --git a/docs/superpowers/plans/2026-10-13-laptop-ready.md b/docs/superpowers/plans/2026-10-13-laptop-ready.md new file mode 100644 index 0000000..ebe52a4 --- /dev/null +++ b/docs/superpowers/plans/2026-10-13-laptop-ready.md @@ -0,0 +1,103 @@ +# Hydra OS Laptop Preparation Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Deliver a tested ISO supporting preserved-partition installation, signed +runtime updates/recovery, and live laptop diagnostics without modifying the host. + +**Architecture:** Extend the validated installer with an explicit partition mode; +use a separately installed trusted updater for signed passive release payloads; +retain independent guest VM state. Validate each subsystem then exercise them in +new disposable UEFI/KVM VMs before integrating and delivering release artifacts. + +**Tech Stack:** Python stdlib, Gentoo, OpenSSL Ed25519, Btrfs tools, GRUB/efibootmgr, +QEMU/KVM, existing dedicated rootless Podman builder. + +**Spec:** `docs/superpowers/specs/2026-10-13-laptop-ready-design.md` + +## Global Constraints + +- No physical block, firmware, host-service, original-container or existing-VM writes. +- Install tests exclusively use fresh private qcow2 disks; no target selected for laptop. +- Preserve partition boundaries, foreign EFI/fallback files and firmware BootOrder. +- Runtime payloads never contain HOME, VM data/config, credentials or networking. +- Check release signature using a separately installed key before trusting contents. +- Keep physical functional claims separate from read-only diagnostics and VM results. +- Existing whole-disk and runtime behavior must retain their regression coverage. + +## Review Focus + +1. Partition aliases, topology changes and mounted siblings: reject actual targets + in use and identity changes, preserve eligible unrelated siblings (Task 1). +2. Existing EFI loaders, lack of ESP space and partial installation: fail before + destructive root formatting when possible and preserve foreign bytes (Task 1). +3. A signed but malformed/replayed archive or unsafe redirect: no mutation (Task 2). +4. Power loss during apply/rollback and a broken CLI: standalone fresh-process + recovery restores exact originals and retains monotonic replay state (Task 2). +5. Missing hardware/tools, privacy and a release that passed only mocks: bounded + honest diagnostics and real disposable-disk acceptance evidence (Tasks 3, 4, 5). + +## Task 1: Preserve-partition installer + +**Files:** `hydra/installer.py`, optional focused `hydra/install_storage.py`, +`tests/test_installer.py`, `image/packages`, `image/dracut.conf`, `docs/install.md`. +**Interfaces:** extend Request compatibly with root_partition, esp_partition, +confirm_format, root_fs and register_boot_entry. Existing `install` stays the entry. + +- [ ] Add failing tests for mode parsing, identity/bounds/protection, mounted siblings, + Btrfs member enumeration, ESP collision/space, only-root formatting and EFI policy. +- [ ] Implement shared validated target plan and distinct storage/boot branches. +- [ ] Add ext4 and Btrfs layouts plus explicit dependencies; test failure cleanup. +- [ ] Run installer suite, self-review, commit only task-owned files. +- [ ] Independent task review and scoped fixes. + +## Task 2: Signed update and recovery + +**Files:** new `hydra/update*.py` as needed, stable `bin/hydra-update*`, `hydra/cli.py`, +`dev/release.py`, `tests/test_update*.py`, `tests/test_cli.py`, image install wiring, +`docs/updates.md`. Coordinate shared image files with Task 1; do not race edits. +**Interfaces:** the CLI actions from the spec; stable recover entrypoint runnable +without importing hydra runtime; passive artifact manifest with version/sequence. + +- [ ] Add failing tests for real crypto, transport bounds, manifest/payload validation, + no-write failures, replay rules, locking and destination/backup path ownership. +- [ ] Implement passive package builder, trusted verification and transactional apply. +- [ ] Implement explicit rollback and independent crash recovery with durable journal. +- [ ] Prove SIGKILL recovery in a fresh process, unchanged guest data and blocked + corrupt backups; verify status/check work unprivileged. +- [ ] Document release creation, local key ownership, bootstrap and runtime scope. +- [ ] Run scoped suites, commit, independent review and scoped fixes. + +## Task 3: Read-only laptop doctor + +**Files:** `hydra/doctor.py`, `tests/test_doctor.py`, `docs/hardware/asus-fx517zc.md`. +**Interfaces:** `doctor_report()` returns serializable bounded observations; +`doctor_main(argv)` serves text/JSON. CLI wiring coordinated after Task 2. + +- [ ] Test fake proc/sys/tools with absent devices, timeouts and redaction. +- [ ] Implement independent read-only probes and manual functional checks. +- [ ] Run unit suite and safe host smoke, commit, independent review. + +## Task 4: Integration and disposable acceptance harnesses + +**Files:** `dev/iso-smoke.py`, `tests/test_iso_smoke.py`, new `dev/update-smoke.py` +or helper as needed, CLI wiring and docs; do not edit these while other tasks do. + +- [ ] Preserve whole-disk mode; add existing-partitions acceptance using seeded fresh + disk only, no existing-disk argument. Capture partition/EFI/BootOrder identities. +- [ ] Add signed update/tamper/apply/rollback/crash-recover installed-guest checks. +- [ ] Confirm brand asset and doctor availability, compile standalone guest scripts. +- [ ] Run full source suite once integrations settle; independent review. + +## Task 5: Build, run acceptance and deliver + +**Files:** source release records under `docs/releases`; build artifacts remain ignored. + +- [ ] Prepare isolated build checkout and preserve old ISO/firmware hashes. +- [ ] Build needed packages/rootfs/ISO, retaining explicit signature trust material. +- [ ] Run whole-disk and preserve-partitions real UEFI acceptance plus updater recovery. +- [ ] Run focused fixes only for observed failures, rerun affected acceptance. +- [ ] Verify exact release files, checksums, source revisions and absence of secrets. +- [ ] Final independent branch review, integrate and publish authorized source/artifacts + using available authenticated transport; report any unavailable publishing action. +- [ ] Report physical checks still requiring live laptop boot, not unsupported success. diff --git a/docs/superpowers/specs/2026-10-13-laptop-ready-design.md b/docs/superpowers/specs/2026-10-13-laptop-ready-design.md new file mode 100644 index 0000000..7ebded6 --- /dev/null +++ b/docs/superpowers/specs/2026-10-13-laptop-ready-design.md @@ -0,0 +1,96 @@ +# Hydra OS laptop preparation + +The user authorized autonomous implementation of the agreed scope: preserve all +existing laptop partitions; install Hydra into an explicitly selected partition; +obtain updates from the now-public `Emil_Shanaty/Hydra-OS` Gitea repository; verify +signatures and recover after failed updates; prepare hardware diagnostics; rebuild +and test an ISO including the generated Fastfetch branding. Technical choices are +delegated. Actual laptop partitioning/installation and physical hardware checks +remain operator steps; no physical target is selected or authorized. + +## Invariants + +- Never modify the physical host's block devices, firmware, services, NixOS + configuration, networking, existing containers, or existing VM disks. +- All installation/recovery execution tests use freshly created private qcow2s. +- Keep whole-disk installation compatible, but add a distinct existing-partitions + mode. No automatic partition selection, shrinking, or repartitioning. +- Preserve foreign EFI files, the removable fallback loader, and BootOrder. +- VM disks, profiles, HOME, credentials and network configuration are not runtime + update payloads. Release trust is installed independently of untrusted discovery. +- Prefer the standard library and already installed OpenSSL; no hosted dependency. +- Hardware detection is evidence about presence, not proof of working devices. +- A runtime rollback must never be described as rollback of Gentoo or its kernel. + +## Existing-partitions installation + +Keep `--disk` and `--confirm-erase` for fresh whole-disk installations. Add +`--root-partition`, `--esp-partition`, `--confirm-format`, `--root-fs ext4|btrfs` +and opt-in `--register-boot-entry`. A request chooses exactly one mode. Existing +mode formats only the selected root after full identity revalidation, requires an +unmounted existing FAT ESP, and never runs disk-label/partition/ESP-format commands. + +Require stable canonical paths, block identities, parent/partition identities and +bounds; reject mounted/active/protected targets, overlaps, aliases, ambiguous +metadata and devices with holders. Unrelated mounted sibling partitions must not +cause false rejection. Btrfs mounts must resolve all backing members conservatively. +Require enough capacity for the installed payload and boot files before erasure. + +Write only EFI/HydraOS, refusing an existing collision. Use GRUB --no-nvram without +--removable, disable os-prober, and leave foreign EFI entries and fallback intact. +Explicit registration may create a new entry without modifying BootOrder. Default +output explains manual firmware selection. ESP preflight is read-only and happens +before root formatting; record and verify unchanged foreign file hashes. + +Ext4 remains compatible. Optional Btrfs uses @root, @home, @snapshots. The kernel, +/boot and Portage database remain within @root; guest disks under HOME remain in +@home. This layout permits a separately verified system recovery path; it alone +is not a rollback implementation. + +## Signed runtime updates + +Use a bounded passive ZIP payload, exact-byte Ed25519-signed JSON manifest and +detached signature. Manifest records product, scope, format, channel, architecture, +monotonic sequence, release version, source commit, archive name/size/hash and the +allowlisted installed paths/modes/hashes. OpenSSL verifies using an installed public +key. Private release material stays outside Git, the build context and Nix store. + +Gitea discovery is unauthenticated HTTPS on the fixed project origin; it is not a +trust authority. Reject cross-origin/downgrade redirects, malformed URLs, duplicate +JSON/archive entries, traversal/symlinks/special files, excess sizes, tampering and +unsupported formats. Verify the manifest before trusting the archive. Empty releases +are a normal result. No fallback to executing unsigned downloaded Python archives. + +CLI: `hydra update check`, `status`, `apply` and `rollback TRANSACTION`, plus a +standalone `hydra-update-recover` available when the runtime itself is damaged. +The trusted engine and recovery bootstrap are outside the runtime update allowlist. +Prefer a protected installed engine imported without arbitrary sys.path entries. +For local tests/support permit an explicit trusted local artifact directory and a +staging-root API; production target checks must still require a Hydra installation. + +Serialize mutations with a lock. Before the first destination change, validate all +paths and save original bytes, modes, owners, symlinks and hashes into a durable +private backup; persist a journal and fsync files/directories. Recover prepared or +interrupted transactions from independently validated records. Latest-only explicit +rollback refuses unexpected modifications. Preserve highest accepted sequence when +rolling back current state; block new changes while recovery is pending. Failure +must retain the journal and all backups. Include real fresh-process crash tests. + +## Diagnostics and delivery + +`hydra doctor` collects a bounded read-only report useful on the live ASUS laptop: +UEFI/Secure Boot, KVM, CPU/RAM, storage visibility, kernel/driver bindings, graphics, +input devices, network/audio tools and required services. Redact serials, MACs, +SSID, IP addresses, usernames and machine IDs by default. Print actionable checks +without implying physical Wi-Fi/audio/brightness/suspend/144Hz delivery were tested. + +Rebuild using the isolated existing builder store. Preserve the previous ISO and +firmware. Run whole-disk acceptance plus a distinct preserve-partitions acceptance: +seed foreign EFI/fallback/sibling sentinel files, install into only the target, +compare GPT/BootOrder/sentinels, and boot without ISO. Exercise signed update, +tamper refusal, rollback and recovery with guest data unchanged. Store reports +against exact source/ISO hashes. Publish only intended code/artifacts; private +builder exports, signing keys, VM data and test secrets are never release assets. + +Whole-base Portage recovery is a separate design/verification unit. Until its own +bootable test passes, documentation must retain that limitation explicitly.