recovery: destination reset and machine replacement paths

[mbertschler]

Problem (friction log F20 + F28 — recovery day)

Both recovery scenarios the walk exercised dead-ended:

• F20 — a wrecked destination has no supported reset. After the bucket-addressing bug era, the packed-layout guard refused every further sync — and following its own advice (fresh root) still refused, because the guard keys on run history by destination name. The only escape was a new destination name: a cross-machine, by-hand config migration (hub sync_to lists, edge offload_requires) plus total loss of evidence continuity, with sqlite surgery as the only alternative.
• F28 — a dead edge machine has no supported restore. The laptop syncs only to the nas (a node), and restore refuses nodes. The machinery exists (a reverse peer push is exactly what nas→htpc does daily), but there's no verb and no runbook; re-pairing a replacement machine is the full bootstrap gauntlet again. "Laptop died" is the most likely disaster in the household; today the answer is "copy files back by hand".

Decision (Martin, 2026-07-24 — option 6d)

Recovery paths are their own issue, separate from the day-1 bootstrap helpers (#162).

Scope

• Destination reset: an explicit operator verb ("forget this destination's recorded state") that clears remote_objects/remote_packs/vectors/freshness for a destination audit-preservingly (runs history stays; the reset itself is recorded as a run). Plus: the layout guard should recognise "configured root is empty on the remote ⇒ fresh start" instead of refusing on name-keyed history alone.
• Machine replacement / restore-from-node: a supported path to rebuild an edge machine from its hub — plausibly a reverse peer push driven from the hub, or a documented restore --from <node> implementation. Includes the re-pairing story (leans on cli: day-1 bootstrap helpers — config check, agent cert, node pairing #162's pairing helper) and a "your machine died" runbook in the docs.
• Cross-reference the existing manual DR that does work and stays: mirror restore, ride-along index snapshot recovery (walked successfully — see friction log checkpoint 8), and packed-layout DR (restore: support the packed (and content-addressed) layouts #142 tracks squirrel-native packed restore).

See design/friction-log.md F20/F28 and the checkpoint 8 section.

[mbertschler]

Landed by #176, which merged into the claude/issue-162-bootstrap-helpers branch and reached main with #171 — the stacked base is why the Closes #163 keyword never auto-closed this.

Verified on main (09c2760): squirrel destination reset (cmd/squirrel/destination_reset.go, audit-preserving — clears derived state only, records itself as a run), the empty-root fresh-start recognition in the packed and content-addressed layout guards, and docs/src/content/docs/guides/recovery.md with the machine-replacement runbook plus cross-references to the manual DR paths that already work.

Note on the second scope item: machine replacement landed as the reverse-peer-push runbook rather than a restore --from <node> verb — one of the two options the issue itself allowed. restore's node dead-end error now signposts the runbook.

Closing as completed.

---

Generated by Claude Code