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:
RemoteDesktopCompensatingActionRemoteDesktopCompensatingActionKindRemoteDesktopCompensatingActionVerificationRemoteDesktopMutatingCommandNameREMOTE_DESKTOP_COMPENSATING_ACTIONSREMOTE_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_actionormanual_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_backfor operator-confirmed idempotent togglesdrag_backfor reversible drags where the source and destination are knownkey_undofor commands with an app-specific undo shortcut such asCmd+Z/Ctrl+Zexplicit_remediationwhen the target application owns the reversal pathsession_state_reviewwhen 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.