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
`/edit-capsules` (TUI slash)	Same snapshot in the chat transcript
`/capsules` (TUI)	Dialog to inspect, roll back, or dismiss 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 and failed_files. Use get_edit_capsule or the /capsules dialog to inspect; manual recovery may be required for paths listed in failed_files.