Edit capsules

Edit capsules group multi-file mutations into one lifecycle: backup -> apply -> validate -> commit or rollback. The feature is opt-in via options.edit_capsules = true (default false).

When to enable

Use capsules when agents or operators need a durable rollback unit across several files (for example a coordinated multiedit batch). For single-file primitives without transactional grouping, use File tools instead.

Operator surfaces

Surface	Purpose
`bmo config show-edit-capsules`	Enabled flag plus in-process `edit_capsule.*` ring snapshot
`bmo edit-capsules recover <capsule-id>`	Dry-run recovery packet by default; `--apply` retries retryable partial rollback steps locally
`/edit-capsules` (TUI slash)	Same snapshot in the chat transcript
`/capsules` (TUI)	Dialog to inspect capsules, recovery classification, rollback, or dismiss
`/undo` (TUI)	Recovery hub that advertises recovery-needed capsules before routing into `/capsules`
`list_recent_edit_capsule_events`	Agent tool, JSON export of the ring

Agent tools

Descriptor-backed tools (when capsules are enabled): create_edit_capsule, list_edit_capsules, get_edit_capsule, update_edit_capsule, delete_edit_capsule, capsule_rollback, capsule_dismiss.

Rollback and dismiss are not exposed on the HTTP API. See Edit capsules (HTTP) for CRUD routes and the intentional POST start-only gap vs create_edit_capsule.

Structured logs

Lifecycle transitions emit paired records:

edit_capsule.fired - one per tool invocation entry
edit_capsule.action - bounded action enum (start, apply, rollback, validate_pass, …)

Filter examples:

edit_capsule.fired
edit_capsule.action
edit_capsule.action action=rollback

Partial rollback

When backup restore fails, the capsule row keeps rollback_state.partial=true, failed_files, and a structured rollback_state.recovery contract.

retryable means BMO can still retry the remaining rollback steps locally.
manual_only means at least one remaining step can no longer be completed safely by BMO.
resolved means a previous partial rollback has already been repaired.

Use bmo edit-capsules recover <capsule-id> to inspect the packet. The command defaults to dry-run; add --apply only when the packet is retryable. /capsules, /edit-capsules, /undo, get_edit_capsule, and the HTTP capsule detail route all surface the same recovery truth.