Hydra-OS/docs/superpowers/plans/2026-10-13-laptop-ready.md

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 and foreign EFI/fallback files across reboots; preserve firmware BootOrder around every installer/recovery/selection operation. Firmware may independently prune empty-media entries between boots.
• 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.
• Complete 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.

Verification status

Implementation and scoped reviews are complete through source ebeebc7fb1aed07a5f50bc62374365d614953dad. The complete source suite passed 431 tests in 26.048 seconds. Independent final review is complete. The final ISO passed the unchanged whole-disk harness (13 checks) and laptop/recovery harness (23 checks), with no skips. Exact artifact identities and public evidence passed review. Source and signed artifacts are published in the public repository. Actual public discovery, signature verification, staging apply/rollback and replay rejection passed. Physical checks remain operator work after live laptop boot. See the release record.