Recovery and checkpoints
Checkpoints
Section titled “Checkpoints”A checkpoint is a best-effort capture of file states with a manifest and visible exclusions. It is not an atomic filesystem snapshot, and secret redaction is imperfect. Automatic Git operations refuse partial or promisor repositories.
Automatic recovery requires a verified, non-uncertain majlis.checkpoint/v2 manifest. Version 1 manifests are display-only.
When a writer is lost
Section titled “When a writer is lost”A missing hook completion means the outcome is unknown. The affected resources are quarantined. Majlis never resets the abandoned checkout.
- A provisioned operator declares the loss with
recovery orphan, which also fences the incarnation. - The operator previews recovery. The preview binds the exact plan and destination, and returns a preview hash. Nothing is committed.
- After review, the operator commits with that exact
--preview-hash.
| Kind | What happens |
|---|---|
takeover |
An explicit heir continues the work in a fresh worktree. The abandoned checkout is preserved. |
requeue |
The task returns to open. It grants no lease and does not prove the old writer stopped. |
Accepting a recovery job means queued work, not completed recovery. majlis --operator recovery job <id> reads durable progress.
Reusing the original checkout needs affirmative evidence that the old writer stopped. An exact operator reconciliation (incarnation reconcile) can end a fenced lifetime; it never reactivates it.
The full command sequence is in Recovering lost work.
Retries are idempotent
Section titled “Retries are idempotent”Every mutation carries an idempotency key scoped to the binding, workspace and operation. After a timeout, retry with the same key and payload to discover the committed result. A new key is a new intent and can duplicate work. See Idempotency.