3.1 KiB
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
- Duplicate/cloned UUIDs or changed PARTUUIDs fail before modifying either target.
- A nested root subvolume or read-write snapshot invalidates the checkpoint contract.
- Interrupted root rename/EFI copy resumes from the durable journal and actual UUIDs.
- Corrupt/path-traversing EFI backups never overwrite foreign files.
- 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.