Eve library

Bellona Remote Host — macOS Menu-Bar Shell (180.C.26.01)

Other

Revision 1

On this page

Native AppKit menu-bar app for the controlled Mac. It renders the host-derived menu-bar model and forwards operator actions to the host's loopback, token-authenticated local-control surface — the shell never re-implements enable/disable, tone, or label rules, so the TypeScript contract (src/macos-host-support.ts → deriveMacOSMenuBarModel) stays the single source of truth.

Architecture#

  • Sources/BellonaRemoteHostShell/main.swift — entrypoint; one binary, two invocations: a normal login-session launch and --run-as-agent under launchd (the LaunchAgent plan's ProgramArguments run this same executable).
  • ShellController.swift — NSStatusItem + NSMenu rendered every 2 s from GET /v1/local-control/menu-bar-model; controls post to pause/resume/stop-session/unpair/diagnostics; unpair is guarded by a destructive confirmation alert; diagnostics reveals the written snapshot in Finder.
  • LocalControlClient.swift — loopback HTTP client; reads the owner-only token file the host mints next to its identity file, and self-heals by poking the (401) state endpoint when the token file does not exist yet.
  • HostProcessSupervisor.swift — spawns and supervises the Node remote-host child when BELLONA_SHELL_HOST_COMMAND is set: unexpected exits restart with a 5 s backoff; a graceful shell shutdown (Quit control or SIGTERM from launchctl kill TERM) forwards SIGTERM so the host cancels running commands, disconnects from the gateway, and flushes before exit. Without a command the shell runs attach-only against an externally managed host.

Build and bundle#

bash
cd apps/bellona/remote-host/macos
scripts/bundle-app.sh            # swift build -c release + assemble
open "dist/Bellona Remote Host.app"

The bundle sets LSUIElement=true (menu-bar only) and bundle id com.oshun.bellona.remote-host. Signing/notarization is the separate, gated 180.C.26.06 step; this script produces an unsigned bundle for development and hardware-evidence runs.

Configuration (environment)#

Variable Meaning Default
BELLONA_SHELL_HOST_PORT Host health/local-control port 4071
BELLONA_SHELL_TOKEN_PATH Local-control token file ~/.oshun/bellona/local-control.token
BELLONA_SHELL_HOST_COMMAND argv (JSON array or space-split) to spawn the host empty → attach-only
BELLONA_SHELL_HOST_CWD Working directory for the host command inherited
BELLONA_SHELL_CONTROL_ROOM_URL URL for the "Open Control Room" control unset → control explains how to configure

Live evidence run#

apps/bellona/remote-host/scripts/macos-menu-bar-shell-evidence.ts boots the REAL gateway and REAL host in one process with a gateway-issued development identity so the shell can be exercised against live host state:

bash
cd apps/bellona/remote-host
npx tsx scripts/macos-menu-bar-shell-evidence.ts /tmp/bellona-shell-evidence
# parse the printed {"ready":true,...} line for ports/paths, then:
BELLONA_SHELL_HOST_PORT=<hostPort> \
BELLONA_SHELL_TOKEN_PATH=<tokenPath> \
  "./macos/dist/Bellona Remote Host.app/Contents/MacOS/Bellona Remote Host"

The 2026-07-07 MAC-HOST-03 closure runs for 180.C.26.01 and 180.C.26.02 (including the full launchd lifecycle) are documented in docs/domains/bellona/extras/remote-control/evidence/180.C.26.01/ and .../180.C.26.02/.