# macOS Remote Host Local Contracts

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.
