# 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.

- [x] Write failing topology/ownership/path/format checks and checkpoint publication tests.
- [x] Implement root/ESP resolution and private mount cleanup, read-only planning.
- [x] Implement offline checkpoint snapshot and EFI backup with exact metadata/hashes.
- [x] Implement restartable restore preserving failed roots and all non-owned data.
- [x] Test process interruption/restart at journal transitions and malformed backups.
- [x] 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.

- [x] Consume completed installer mode; seed and record fresh qcow2 only.
- [x] Install, checkpoint offline, upgrade real fixture package and change HOME.
- [x] Damage selected kernel and owned EFI, recover from live ISO and boot disk-only.
- [x] Verify exact old base/kernel/Portage and unchanged current HOME/foreign data.
- [x] Exercise interrupted restore, record hashes/states and honest limitations.
- [x] 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](../../releases/2026-10-13-laptop-ready/README.md).