Recovering lost work

Recovery is always preview, review, commit. A preview never commits, and a pending job is not a completed restore. The human operator must first be provisioned.

1. Declare the loss

majlis --operator recovery orphan "$TASK_REF" \
  --reason '<observed-loss>' --idempotency-key '<key>'

This orphans the task and fences the lost incarnation.

2. Gather the inputs

majlis --operator --json task show "$TASK_REF"

Keep data.revision as CURRENT_TASK_REVISION. For a takeover you also need the heir’s NEW_OWNER_ACTOR_ID and NEW_INCARNATION_ID from their registration (the incarnation must be active in this workspace), an absolute unused REQUESTED_DESTINATION_ROOT, a RECOVERY_REASON, and separate stable PREVIEW_KEY and COMMIT_KEY values.

3. Preview a fresh-worktree takeover

majlis --operator --json recovery preview "$TASK_REF" --kind takeover \
  --revision "$CURRENT_TASK_REVISION" --reason "$RECOVERY_REASON" \
  --new-owner "$NEW_OWNER_ACTOR_ID" --new-incarnation "$NEW_INCARNATION_ID" \
  --fresh-worktree --destination-root "$REQUESTED_DESTINATION_ROOT" \
  --idempotency-key "$PREVIEW_KEY"

Stop and review the returned task, revision, checkpoint, destination and warnings. Copy data.preview_hash and the exact data.destination_root.

4. Commit the reviewed plan

majlis --operator recovery takeover "$TASK_REF" \
  --revision "$CURRENT_TASK_REVISION" --reason "$RECOVERY_REASON" \
  --new-owner "$NEW_OWNER_ACTOR_ID" --new-incarnation "$NEW_INCARNATION_ID" \
  --fresh-worktree --destination-root "$REVIEWED_DESTINATION_ROOT" \
  --preview-hash "$REVIEWED_PREVIEW_HASH" --idempotency-key "$COMMIT_KEY"

Requeue instead

Preview with --kind requeue, the revision, the reason and its own preview key, and no owner, incarnation or destination flags. After review, run recovery requeue with the same revision and reason, the returned --preview-hash and a separate commit key. Requeue returns the task to open. It grants no lease and does not prove the old writer stopped.

Track the job

majlis --operator recovery job "$RECOVERY_ID"

Pending is not a completed restore or ownership transfer. Retry uncertain requests with the original key and payload. If the task or plan changed, inspect durable state and review a new preview. Never combine preview and commit automatically.

Fresh recovery needs a retained, verified, non-uncertain majlis.checkpoint/v2 manifest. Reusing the original checkout also needs the exact old writer confirmed ended and a matching checkout.