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

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/`.
