Hydra-OS/docs/superpowers/plans/2026-10-13-base-recovery.md

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.

Verification status

The command, tests, image wiring and independent source reviews are complete. The unchanged final laptop harness passed all 23 checks against the final ISO, including real SIGKILL/resume, restored disk-only boot, exact base/kernel/Portage/EFI hashes, current HOME and unchanged guest/foreign data. Physical laptop checks remain separate; exact kernel restoration does not establish a two-kernel upgrade. See the release record.