104 lines
6.1 KiB
Markdown
104 lines
6.1 KiB
Markdown
# 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.
|