diff --git a/docs/superpowers/plans/2026-10-13-base-recovery.md b/docs/superpowers/plans/2026-10-13-base-recovery.md new file mode 100644 index 0000000..67fc69d --- /dev/null +++ b/docs/superpowers/plans/2026-10-13-base-recovery.md @@ -0,0 +1,53 @@ +# Offline Base Recovery 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:** Recover Gentoo root, package database, kernel and owned EFI files together +while preserving HOME and other systems, using the trusted live ISO. +**Architecture:** Offline Btrfs read-only checkpoints and a restartable restore +journal outside @root; matching EFI/HydraOS backups; explicit target identities. +**Tech Stack:** Python stdlib, Btrfs tools, existing live image and QEMU acceptance. +**Spec:** `docs/superpowers/specs/2026-10-13-base-recovery-design.md` + +## Global Constraints + +- No real host devices or existing VM disks may be modified during development. +- Only genuine live mode, selected unmounted single-device Btrfs/ESP, explicit UUID. +- @home, foreign EFI/BOOT, partition table and firmware state remain unchanged. +- Runtime update and full-base checkpoint/recovery remain distinct commands/scopes. +- Recovery requires no installed executables/network and retains previous roots. + +## Review Focus + +1. Duplicate/cloned UUIDs or changed PARTUUIDs fail before modifying either target. +2. A nested root subvolume or read-write snapshot invalidates the checkpoint contract. +3. Interrupted root rename/EFI copy resumes from the durable journal and actual UUIDs. +4. Corrupt/path-traversing EFI backups never overwrite foreign files. +5. The real VM proves coordinated kernel/package recovery and post-checkpoint HOME. + +## Task 1: Offline command and journal + +**Files:** `hydra/system_recovery.py`, `bin/hydra-system`, +`tests/test_system_recovery.py`, `docs/system-recovery.md`. +**Consumes:** installer storage.json schema and @root/@home/@snapshots layout. +**Produces:** checkpoint/list/restore CLI; root-owned completed metadata and durable +restore transaction; module has no import-time mutations and works from live ISO. + +- [ ] Write failing topology/ownership/path/format checks and checkpoint publication tests. +- [ ] Implement root/ESP resolution and private mount cleanup, read-only planning. +- [ ] Implement offline checkpoint snapshot and EFI backup with exact metadata/hashes. +- [ ] Implement restartable restore preserving failed roots and all non-owned data. +- [ ] Test process interruption/restart at journal transitions and malformed backups. +- [ ] Scoped tests, self-review, commit, independent task review. + +## Task 2: Bootable acceptance and integration + +**Files:** new `dev/system-recovery-smoke.py` or extension to preserve-partition +acceptance, associated harness tests, image wiring and release evidence. + +- [ ] Consume completed installer mode; seed and record fresh qcow2 only. +- [ ] Install, checkpoint offline, upgrade real fixture package and change HOME. +- [ ] Damage selected kernel and owned EFI, recover from live ISO and boot disk-only. +- [ ] Verify exact old base/kernel/Portage and unchanged current HOME/foreign data. +- [ ] Exercise interrupted restore, record hashes/states and honest limitations. +- [ ] Integrate with laptop ISO acceptance and final review before delivery. diff --git a/docs/superpowers/specs/2026-10-13-base-recovery-design.md b/docs/superpowers/specs/2026-10-13-base-recovery-design.md new file mode 100644 index 0000000..7959dca --- /dev/null +++ b/docs/superpowers/specs/2026-10-13-base-recovery-design.md @@ -0,0 +1,53 @@ +# Offline recovery of the Gentoo base + +This separately verified part of laptop preparation supplies real OS rollback, +not just runtime-file rollback. It is deliberately offline: create checkpoints +from the trusted live ISO while the installed root and ESP are unmounted, perform +ordinary Portage updates in the installed system, and use the ISO to recover if +needed. No online application-consistency or automatic failed-boot claim is made. + +The explicit Btrfs layout is @root, @home, @snapshots; /boot, kernel modules, +Portage package database and world remain in @root. There must be no nested +subvolumes within @root. VM disks and user data in @home survive OS recovery. +GRUB/fstab/initramfs select UUID plus subvol=@root, never fixed subvolume IDs. + +`/etc/hydra/storage.json` is the installation ownership marker with exact fields: +format=1, install_uuid, root_fs_uuid, root_partuuid, esp_uuid, esp_partuuid, +owned_efi_path='EFI/HydraOS', filesystem='btrfs', root_subvolume='@root'. The ESP +must be the recorded FAT partition; never operate on foreign EFI paths or NVRAM. + +CLI `hydra-system checkpoint --root-uuid UUID --esp-partuuid PARTUUID --name NAME`, +`hydra-system list --root-uuid UUID`, and +`hydra-system restore --root-uuid UUID --checkpoint ID`. Changes require --execute +and --confirm-root-uuid UUID. Default plans/list are read-only. Require a genuine +Hydra live marker, root execution for changes, exactly one matching root and ESP, +ordinary unmounted partitions without active swap/holders, single-device Btrfs, +matching partition/filesystem/install UUIDs and supported owned layout. + +Checkpoint mounts selected filesystems privately, snapshots @root read-only into +@snapshots/ID/root and saves only EFI/HydraOS with a hash/metadata manifest. +Preserve exact installed root and EFI state while offline. Durably publish the +completed checkpoint descriptor last. Incomplete checkpoints cannot be restored. +Snapshots remain on the same disk and are not external backups. + +Restore validates all metadata, recorded source/snapshot UUIDs, readonly snapshot, +layout marker and saved EFI bytes before mutation. Prepare a writable snapshot, +record a durable transaction outside @root, retain the previous root under a unique +failed-root name, rename the new root to @root, then restore only owned EFI files. +Keep checkpoints and failed roots. Never delete @home or alter GPT, fallback EFI, +foreign partitions/EFI directories or BootOrder. Directory fsync and filesystem +sync delimit journal transitions. Lock operations and reject unexplained state. + +Root/ESP replacement is not atomic across Btrfs and FAT. A power interruption can +leave the install temporarily unbootable; rerunning restore from the live ISO must +verify identities and resume the recorded transaction without guessing or deleting +either root. Recovery must not invoke installed programs, fetch files, or require +network access. Symlinks, malformed paths, unexpected files and tampered backup +metadata fail closed before writes. + +Actual acceptance uses a fresh UEFI VM, preserved foreign EFI/data sentinels, +Btrfs install, live checkpoint, a real local Portage package upgrade, changed HOME, +and damaged installed kernel/own EFI. After recovery boot without ISO and verify +old package database/world/kernel artifacts together, updated HOME retained, and +foreign bytes/GPT/BootOrder unchanged. Exercise restart after journal transition +failures. Do not claim a two-kernel-version upgrade unless separately exercised.