# Desktop Compensating Actions

Implementation task: `180.C.13.11`

Desktop fallback input has no trustworthy native undo stack. A click, focus
change, drag, or key event can reach any foreground application, open modal
state, submit a form, or trigger operating-system UI that Bellona cannot roll
back generically. Bellona therefore treats desktop fallback mutations as
rollback-declared actions with explicit compensating-action metadata.

## Protocol Catalog

The source of truth lives in `libs/bellona/remote-protocol/src/desktop.ts`:

- `RemoteDesktopCompensatingAction`
- `RemoteDesktopCompensatingActionKind`
- `RemoteDesktopCompensatingActionVerification`
- `RemoteDesktopMutatingCommandName`
- `REMOTE_DESKTOP_COMPENSATING_ACTIONS`
- `REMOTE_DESKTOP_COMPENSATING_ACTION_METADATA_KEY`

Command envelope metadata stays primitive-only for compatibility with
`RemoteCommandEnvelope`. Mutating desktop commands therefore carry a
`compensating_action_id` plus primitive summary fields, and clients resolve the
full descriptor from the protocol catalog.

## Current Mutating Commands

| Command                  | Rollback strategy         | Compensating action id                                      | Reversal recipe                                                                                                                                                              | Verification              |
| ------------------------ | ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `desktop.window.focus`   | `manual_remediation_only` | `compensating-action:desktop-window-focus-explicit-refocus` | Refocus the operator-reviewed window with `desktop.window.focus`, or manually restore focus if macOS/app focus rules block deterministic refocus.                            | `focused_window_restored` |
| `desktop.click`          | `manual_remediation_only` | `compensating-action:desktop-click-explicit-remediation`    | Review before/after evidence. Use click-back only for operator-confirmed idempotent targets; otherwise perform an app-specific remediation and record it.                    | `operator_attestation`    |
| `desktop.type`           | `manual_remediation_only` | `compensating-action:desktop-type-key-undo-or-remediation`  | Use an app-specific undo shortcut only after operator review, or explicitly remediate by selecting/deleting the typed text or applying the target app's documented reversal. | `operator_attestation`    |
| `desktop.emergency_stop` | `manual_remediation_only` | `compensating-action:desktop-emergency-stop-session-review` | Review interrupted command ids and current session state before allowing further desktop input. Already-dispatched native input is not undone by the emergency stop itself.  | `session_state_reviewed`  |

`desktop.screenshot` and `desktop.window.list` remain read-only desktop
commands. They do not require rollback metadata.

## Future Mutating Command Requirements

Future mutating desktop commands must add a catalog entry before becoming
routable. The descriptor must include:

- stable action id
- mutating desktop command name
- rollback strategy, either `compensating_action` or `manual_remediation_only`
- action kind
- operator-readable label and limitations
- suggested Bellona command when a truthful automated compensating command
  exists
- verification method and verification description

Expected future action kinds are:

- `click_back` for operator-confirmed idempotent toggles
- `drag_back` for reversible drags where the source and destination are known
- `key_undo` for commands with an app-specific undo shortcut such as
  `Cmd+Z`/`Ctrl+Z`
- `explicit_remediation` when the target application owns the reversal path
- `session_state_review` when the only safe step is reviewing and attesting
  current state before continuing

If a desktop command cannot name a truthful reversal path, it must use
`manual_remediation_only` and state the operator action required. It must not
claim `compensating_action` just because a best-effort keypress or repeat click
might work in some applications.

## Dispatch Boundary

`180.C.13.11` introduces the desktop catalog, populates current desktop mutation
metadata, and rejects safe-mutation desktop envelopes whose command name has no
protocol-owned compensating action or whose metadata carries the wrong action id
or rollback strategy.

Agents should treat the catalog as binding metadata: every mutating desktop
fallback command must carry the catalog id and primitive summary fields so
audit, timeline, and rollback planning can name the available remediation path.
