# ADR-0004: Cross-Platform Remote Host Scope

- **Status**: Accepted
- **Date**: 2026-04-22
- **Authors**: Bellona Remote Control Working Group, Codex
- **Reviewers**: Bellona, Psyche, Yemaya, Oshun Platform, Oshun Security

## Context and Problem Statement

Phase 180 is titled around a MacBook Remote Host and its target layout names
`libs/bellona/mac-host-runtime` for macOS permissions, process launching, window
focus, screen capture, signing, and update helpers. The compatibility matrix
also makes macOS 14 on Apple Silicon the remote-host MVP baseline.

The broader product vision is not macOS-only. Blender and Unreal production
studios frequently use Windows workstations, Linux render nodes, and
mixed-platform farms. The Phase 180 gap analysis therefore added explicit
Windows host support (`180.C.36`), Linux host support (`180.C.37`), and a
cross-platform permission abstraction task (`180.C.26.16`).

This ADR decides whether Phase 180 remains macOS-only, expands immediately to
macOS plus Windows and Linux, or takes a phased approach. The decision controls
whether `180.C.36` and `180.C.37` are in scope and whether host runtime code
should stay macOS-specific or split into generic interfaces plus
platform-specific providers.

## Decision Drivers

- Deliver the Phase 180 MVP safely against the original two-MacBook use case
  without diluting early security, pairing, policy, audit, Control Room, and
  Blender/browser work.
- Avoid overclaiming support for Windows desktop control, Linux Wayland/X11
  capture, service packaging, update channels, UAC/PolicyKit, Defender,
  AppArmor/SELinux, and cross-platform codec behavior before test rigs exist.
- Keep protocol, gateway, audit, MCP, adapter, and timeline contracts
  platform-neutral so future hosts do not require a second control plane.
- Preserve macOS-specific implementation quality for TCC, Keychain, LaunchAgent,
  ScreenCaptureKit, Accessibility, code signing, notarization, and operator
  onboarding.
- Acknowledge that Windows and Linux hosts are product requirements for
  production DCC coverage, not speculative nice-to-haves.

## Considered Options

### Option 1: macOS Only for All of Phase 180

Phase 180 would explicitly support only macOS hosts. Windows and Linux would be
deferred to a later phase.

Pros:

- Lowest short-term complexity.
- Aligns with the original two-MacBook scenario and existing compatibility
  matrix.
- Keeps host packaging, permissions, and hardware evidence focused.

Cons:

- Understates real studio workstation and render-node requirements.
- Makes the added `180.C.36` and `180.C.37` stages misleading.
- Encourages macOS assumptions to leak into protocol, gateway, audit, MCP, and
  adapter contracts.

### Option 2: macOS, Windows, and Linux Immediately

Every host-runtime feature would be designed and implemented for macOS, Windows,
and Linux before the MVP is considered complete.

Pros:

- Strongest platform ambition.
- Forces generic interfaces early.
- Avoids later refactoring of host abstractions.

Cons:

- Too large for the current MVP safety sequence.
- Requires hardware rigs, packaging pipelines, signing/update plans, and
  permission models that are not yet inventoried.
- Delays the foundational gateway, protocol, audit, adapter, and Control Room
  path before any production feedback exists.
- Risks implementing lowest-common-denominator desktop fallback instead of deep
  DCC adapters.

### Option 3: Phased Cross-Platform Scope

Ship the MVP and alpha gates on macOS first. Keep Windows and Linux explicitly
in scope for Phase 180 as later expansion stages, but block them behind the
macOS MVP, cross-platform host-runtime interface, hardware rig inventory, and
platform-specific packaging/security evidence.

Pros:

- Preserves the original MacBook Remote Host delivery path.
- Prevents protocol and gateway code from becoming macOS-only.
- Makes Windows and Linux real Phase 180 work without making them MVP blockers.
- Lets Windows start with DCC workstation/render-node needs and Linux start with
  render-node/headless needs before full desktop fallback parity.

Cons:

- Requires strict discipline to keep early interfaces platform-neutral.
- Adds future migration work from `mac-host-runtime` implementation details to
  generic `host-runtime` contracts.
- Requires later hardware evidence across three operating systems.

## Decision Outcome

Bellona adopts **Option 3: phased cross-platform scope**.

The Phase 180 MVP and alpha gates are macOS-first. The controlled host baseline
is the existing compatibility-matrix target: macOS 14 Sonoma on Apple Silicon,
with the Remote Host connecting outbound to the Bellona Remote Gateway and all
Blender, Unreal, browser, and desktop ports remaining localhost-only.

Windows and Linux hosts remain in scope for Phase 180, but they are later
expansion stages rather than MVP blockers:

- `180.C.36` is in scope for Windows host support after macOS host, policy,
  audit, Control Room, adapter, packaging, and cross-platform abstraction
  foundations exist.
- `180.C.37` is in scope for Linux host support after the same foundations, with
  render-node/headless operation as the initial Linux emphasis.

The host-runtime split is:

- `apps/bellona/remote-host` remains the platform-neutral host application and
  protocol participant.
- `libs/bellona/mac-host-runtime` remains the first concrete provider for
  macOS-specific permissions, secure credential storage, capture, input, process
  launching, app discovery, diagnostics, packaging, signing, and update helpers.
- `libs/bellona/host-runtime` is introduced later by `180.C.26.16` as the
  cross-platform interface package for permission state, capture capability,
  input capability, window/app discovery, process control, credential storage,
  artifact/diagnostic hooks, codec/stream capabilities, and install/update
  state.
- Future `libs/bellona/windows-host-runtime` and
  `libs/bellona/linux-host-runtime` providers may implement the generic
  interfaces when `180.C.36` and `180.C.37` begin. They must not bypass the
  gateway, protocol, policy, approval, or audit path.

## Normative Rules

- **MVP host scope**: MVP and alpha acceptance remain macOS-first unless a later
  ADR explicitly revises the release gate.
- **Platform-neutral contracts**: `libs/bellona/remote-protocol`, gateway
  storage, audit records, timeline events, MCP tools, adapter capability
  records, and Control Room state must model host OS and runtime capability
  explicitly rather than assuming macOS.
- **macOS provider quality**: `mac-host-runtime` may use macOS-native APIs and
  packaging concepts directly. It should not pretend Windows or Linux semantics
  are available.
- **Generic interface timing**: do not introduce a broad `host-runtime`
  abstraction until at least one concrete macOS provider path exists and
  `180.C.26.16` is reached. The abstraction must be extracted from real host
  needs, not speculative platform guesses.
- **No premature parity claims**: Windows and Linux support cannot be checked
  until platform-specific package install, permissions, capture/input,
  credential storage, diagnostics, update, security, and hardware evidence are
  documented and verified.
- **Desktop fallback is platform-specific**: desktop screenshot, input, window
  focus, clipboard, and permission behavior must remain capability-reported per
  OS. Linux render-node support does not imply Linux desktop control. Windows
  DCC adapter support does not imply arbitrary Windows desktop automation.
- **Deep adapter first remains global**: Blender, Unreal, browser, and other DCC
  adapters remain preferred over desktop fallback on every OS.
- **No direct engine exposure**: Windows and Linux host providers inherit the
  localhost-adapter rule. Blender, Unreal, Chrome/CDP, desktop, and fallback
  ports must not be exposed directly to LAN or internet.

## Platform Scope by Gate

| Gate / Stage Group                    | macOS Host                                    | Windows Host                                                          | Linux Host                                                            |
| ------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- |
| MVP foundation through `180.C.16`     | In scope and required.                        | Out of MVP gate; protocol must remain platform-neutral.               | Out of MVP gate; protocol must remain platform-neutral.               |
| Final verification through `180.C.29` | Required for the two-MacBook acceptance path. | Not required for final Mac MVP unless a later release ADR changes it. | Not required for final Mac MVP unless a later release ADR changes it. |
| Fleet expansion `180.C.30`            | In scope.                                     | Candidate after Windows host stage.                                   | Candidate after Linux host stage.                                     |
| Windows stage `180.C.36`              | Existing provider remains supported.          | In scope and required for that stage.                                 | Not required for Windows stage.                                       |
| Linux stage `180.C.37`                | Existing provider remains supported.          | Existing provider remains supported once completed.                   | In scope and required for that stage.                                 |

## Architecture Implications

- Remote protocol schemas should include `hostOs`, `hostRuntimeId`,
  `hostRuntimeVersion`, `permissionProvider`, `captureProvider`,
  `inputProvider`, and per-capability degraded-state fields before
  cross-platform providers are advertised.
- Gateway and Control Room must display capabilities and missing permissions
  from host reports rather than deriving behavior from OS names alone.
- Tests for protocol, gateway, host, and mock harness should avoid macOS-only
  fixture names except where explicitly testing macOS behavior.
- Windows support should prioritize signed MSI/service install, DCC process
  discovery, Chrome/Edge isolated profile control, DXGI capture, Defender/UAC
  policy surfaces, diagnostics, and update rollback.
- Linux support should prioritize signed packages, systemd user units,
  headless/render-node roles, Blender/Unreal commandlet operation, PipeWire
  audio where needed, and explicit Wayland/X11 limitations for desktop fallback.
- The hardware rig inventory task (`180.C.02.15`) must list separate macOS,
  Windows, and Linux fixtures, including virtualized cases that are acceptable
  only for non-capture/non-input verification.

## Acceptance Criteria

- This ADR exists under `docs/domains/bellona/extras/remote-control/adr/`.
- The decision explicitly selects phased cross-platform host scope.
- The ADR states that macOS is required for the MVP/alpha host path.
- The ADR states that `180.C.36` and `180.C.37` remain in scope for later Phase
  180 expansion, not MVP blockers.
- The ADR defines the split between `apps/bellona/remote-host`,
  `libs/bellona/mac-host-runtime`, future `libs/bellona/host-runtime`, and
  future Windows/Linux provider packages.
- The tracker row and Phase 180 checklist item for `180.C.02.14` are updated.
- Markdown formatting verification passes for this ADR, the tracker, and the
  phase checklist.

## Consequences

Positive consequences:

- The Phase 180 MVP remains deliverable against the original controlled-MacBook
  scenario.
- Core contracts stay platform-neutral enough for later Windows and Linux hosts.
- Windows and Linux are explicit product commitments rather than hidden
  assumptions or indefinite future work.
- Hardware evidence expectations become clear before platform work starts.

Negative consequences:

- Early macOS implementation must avoid leaking platform assumptions into shared
  protocol and gateway records.
- Cross-platform support arrives later than the first macOS MVP.
- `180.C.26.16`, `180.C.29.16`, `180.C.36`, and `180.C.37` become necessary
  follow-through work rather than optional cleanup.

## Related Decisions

- `docs/domains/bellona/extras/remote-control/adr/ADR-0001-standalone-remote-gateway-and-host.md`
- `docs/domains/bellona/extras/remote-control/adr/ADR-0002-remote-control-threat-model.md`
- `docs/domains/bellona/extras/remote-control/adr/ADR-0003-gateway-trust-and-e2e-encryption-model.md`
- `docs/domains/bellona/extras/remote-control/compatibility-matrix.md`
- Future `180.C.02.15` hardware rig inventory matrix.
- Future `180.C.02.16` MVP release artifact ADR.
- Future `180.C.26.16` cross-platform permission abstraction.
- Future `180.C.36` Windows Host Support.
- Future `180.C.37` Linux Host Support.

## References

- `TODOS/phase-180.md`
- `TODOS/phase-180-gaps.md`
- `docs/domains/bellona/extras/remote-control/implementation-tracker.md`
- `docs/domains/bellona/extras/remote-control/external-implementation-research-2026-04-21.md`
- Apple ScreenCaptureKit screen capture docs:
  <https://developer.apple.com/documentation/screencapturekit/capturing_screen_content_in_macos>
- Microsoft Windows Service Applications:
  <https://learn.microsoft.com/en-us/windows/win32/services/services>
- Microsoft Desktop Duplication API:
  <https://learn.microsoft.com/windows/win32/direct3ddxgi/desktop-dup-api>
- systemd user service manager docs:
  <https://www.freedesktop.org/software/systemd/man/latest/user%40.service.html>
- PipeWire documentation: <https://docs.pipewire.org/>
