Eve library

macOS Remote Host Local Contracts

Guide

Revision 1

On this page

Status: local contract coverage for 180.C.26.01, 180.C.26.02, 180.C.26.06, 180.C.26.09, and 180.C.26.14. Items 180.C.26.01 and 180.C.26.02 are now CLOSED with live hardware evidence from macOS rig MAC-HOST-03 (2026-07-07): the native SwiftPM AppKit menu-bar shell (apps/bellona/remote-host/macos) renders the host-derived deriveMacOSMenuBarModel output over the loopback token-guarded local-control surface (src/local-control.ts), and the LaunchAgent lifecycle plan below was executed verbatim under launchd (see evidence/180.C.26.01/ and evidence/180.C.26.02/).

The remaining macOS host checklist items (180.C.26.06, 180.C.26.09, 180.C.26.14) still require Apple Developer ID credentials, codesign, notarytool, stapler, signed-package install QA, and non-developer acceptance evidence. This note records the parts that are deterministic and covered by portable tests so the final macOS evidence can be judged against an explicit contract.

Covered Locally#

Implementation:

  • apps/bellona/remote-host/src/macos-host-support.ts
  • apps/bellona/remote-host/src/macos-host-support.test.ts

Export:

  • apps/bellona/remote-host/src/index.ts

The local contracts cover:

  • the menu-bar status model for ready, offline, attention, active-session, and paused-session states;
  • operator controls for open Control Room, pause, resume, stop, diagnostics, unpair, and quit, including disabled reasons for unsafe actions;
  • LaunchAgent lifecycle commands for plist linting, bootstrap, enable, kickstart, status, graceful TERM, crash restart, and clean uninstall;
  • Developer ID and notarization readiness checks driven by the existing macOS packaging plan, including Developer ID Application/Installer identity shape, notary profile, and Team ID validation so placeholder signing env cannot pass;
  • the install QA scenario matrix for clean install, upgrade, permission revocation, adapter repair, update rollback, crash-loop recovery, and uninstall;
  • the install QA evidence evaluator requiring each scenario to attach canonical UTC millisecond artifacts captured during or after a current scenario run, with identifiers that are unique across every scenario record after case-insensitive normalization and bind to the scenario/evidence kind in both the artifact ID and canonical evidence URI with non-empty artifact suffixes, plus a macOS host runner and an operator:macos-install-qa: identity;
  • the Stage 26 roll-up gate proving that 180.C.26.14 cannot close until the menu-bar shell, LaunchAgent lifecycle, signing/notarization, install QA, and non-developer acceptance run all have concrete macOS evidence records in the right order rather than placeholder booleans, generic install-QA summaries without complete per-scenario QA records, install-QA summaries captured before the scenario evidence they summarize, non-developer acceptance captured before prerequisite Stage 26 evidence, stale or non-canonical timestamp QA runs, QA artifacts, or stage evidence, stage artifacts that do not identify both their checklist item and exact evidence slot, generic install-QA operator identities, non-developer acceptance records without a non-developer operator identity, empty or placeholder runner/operator/artifact suffixes, or artifact identifiers duplicated within or across stage evidence records, including case-variant duplicates.

Still Required On macOS#

These contracts do not complete the open checklist items. Final closure still requires:

  • building and running the native AppKit/SwiftUI menu-bar app on a physical macOS host;
  • registering the real LaunchAgent with launchd and observing restart, graceful-stop, and uninstall behavior;
  • signing and notarizing the real app, helpers, LaunchAgent package, Blender add-on package, Unreal plugin package, and installer with Apple Developer ID credentials;
  • running the full install QA matrix on the hardware rig named in hardware-rig-inventory.md;
  • recording a non-developer install/pair/permission/update/diagnose/uninstall acceptance run.

Verification#

Run the focused local contract check:

bash
pnpm nx test @bellona/remote-host -- macos-host-support.test.ts --reporter=verbose

These tests are deliberately pure over inputs. A passing run proves the local contract shape, not live macOS behavior.