Plan and verify repository recovery

Use crab recover when a release manifest identifies expected content that is missing or damaged. Recovery is evidence-driven: plan from known inventories and candidate byte sources, inspect the saved plan, materialize verified files to an isolated directory, and change the remote only with explicit repair flags.

Create a plan without changing the remote

Start from a release manifest and add only sources available to the incident:

crab fsck --jsonl > fsck.jsonl
crab recover plan \
  --manifest release.json \
  --source /mnt/verified-backup \
  --fsck-jsonl fsck.jsonl \
  --output recovery-plan.json

Planning reads the supplied manifest, missing-object evidence, and candidate sources. It records expected identities and possible recovery actions. It does not trust a filename as proof of content and does not write recovered objects to the configured remote.

Other evidence sources include a workflow cache, replica export, import or workflow journal, pointer tree, and explicit shard, xorb, pack, or file-index inventories. Include only evidence whose origin and collection time can be explained in the incident record.

Inspect and apply the plan

crab recover show --plan recovery-plan.json
crab recover apply \
  --plan recovery-plan.json \
  --restore-to ./recovered-files

The default apply path materializes verified recovered files under the selected directory. Remote actions require explicit flags such as --restore-shards, --restore-xorbs, --restore-packs, --rebuild-file-index, or --repair-remote. Review each action, destination, and refspec before granting write credentials.

Inspect historical repository roots

Historical recovery is a separate command group:

crab recover history list
crab recover history verify --help
crab recover history restore --help

List is read-only. Verify one immutable historical root and its complete dependency closure before previewing restoration. Retention and restoration commands expose their own preview or apply boundary; inspect subcommand help for the installed release.

Distinguish interrupted pushes

Push and upload commands can also resume or clean operation-specific staging state. Diagnose those failures first with crab logs last, crab staging verify, and crab fsck. Do not create a repository recovery plan merely to clear local staging after a failed push.

Verify the recovered result

Run crab fsck again, hydrate representative files from an empty client cache, and compare their application-level format or checksum with the release evidence. Keep the plan, apply output, and post-recovery checks together as the incident record.

For exact plan and mutation flags, see the crab recover reference.