lantern

Overview ¶

Auto-stale-reset (#118): bridge-off boot recovery from long outages.

#51 gave RPC-mode Lantern the "restart after a week and it just catches up" property via the polling Sync's StaleResetThreshold path. In bridge-off mode (--no-fallback-rpc) that path is a no-op: there's no RPC head-source to report a live head that the polling Sync could compare against. So a bridge-off node that was stopped past the parentWalkCap (default 2880 epochs / ~24h) boots wedged — the persisted anchor + header store are old, and every parent-walk from the fresh gossip head exceeds the cap.

This file is the parallel code for bridge-off: on daemon boot, if the persisted bootstrap-anchor.json is older than --anchor-max-age (default 12h), re-run the same multi-source quorum probe `lantern repair` uses and overwrite the anchor with a fresh finality. The subsequent boot steps then treat this as a normal fresh-anchor start; the ChainExchange seed (main.go:1326) re-seats the header store from the fresh anchor tipset, and #117's parentWalkCap covers whatever gap remains between the fresh anchor and the live head.

Chain state only. Keys, JWT, tokens are never touched (same allow-list discipline as `lantern reset --chain-state`, enforced by never touching anything outside `bootstrap-anchor.json`). Quorum probe failure is fail-warn (not fail-fatal): we continue boot with the stale anchor and let the existing boot paths do their best. A probe blip should not take the daemon down.

The helper is factored out of cmdDaemon so it can be unit-tested with a fake probe + fake writer (no live network needed).

`lantern reset` — issue #51.

The official, key-safe recovery path for a node that has been stopped for a long time and boots stuck on a stale head. It clears ONLY rebuildable chain state (the persistent header store and the on-disk bootstrap anchor) and then the next `lantern daemon` re-syncs from the live head.

It is deliberately impossible for this command to delete secrets. The only thing it removes is an explicit allow-list of chain-state paths; it never recurses over the whole data dir, and it refuses to run if asked (via the escape hatch flag) to touch anything in the secrets allow-list.

This exists because the previous "recovery" was hand-rolled `rm -rf ~/.lantern/...` which sits next to keystore/ and jwt-secret in the same directory — one slip wipes irreplaceable keys (observed 2026-06-18). No README, --help, or UI hint should ever again tell a user to rm under ~/.lantern directly.