# 180.C.26.02 — LaunchAgent lifecycle: live launchd run on macOS

- **Date:** 2026-07-07 (run window 18:53–18:56 UTC)
- **Rig:** `MAC-HOST-03` — physical MacBook Air, Apple Silicon (arm64), macOS
  26.5.2 (build 25F84)
- **Operator:** `operator:macos-install-qa:elikem-macbook-air-2026-07-07`
- **Checklist item:** `180.C.26.02` — Implement LaunchAgent registration,
  restart after crash, graceful shutdown, and clean uninstall.

The run follows `createMacOSLaunchAgentLifecyclePlan()` exactly: label
`com.oshun.bellona.remote-host`, plist in `~/Library/LaunchAgents/`,
`ProgramArguments` = the bundled `Bellona Remote Host.app` binary with
`--run-as-agent`, `RunAtLoad=true`,
`KeepAlive={SuccessfulExit:false, Crashed:true}`, `ProcessType=Interactive`,
`ThrottleInterval=10`, `StandardOutPath`/`StandardErrorPath` set.

## Structured stage evidence record

```json
{
  "launchAgentLifecycleRunOnMac": {
    "passed": true,
    "capturedAt": "2026-07-07T18:56:00.000Z",
    "macOSRunnerId": "MAC-HOST-03",
    "operatorId": "operator:macos-install-qa:elikem-macbook-air-2026-07-07",
    "evidenceArtifactIds": [
      "artifact:180.C.26.02:launch-agent-lifecycle-run:2026-07-07-mac-host-03-bootstrap-print-running",
      "artifact:180.C.26.02:launch-agent-lifecycle-run:2026-07-07-mac-host-03-keepalive-crash-restart",
      "artifact:180.C.26.02:launch-agent-lifecycle-run:2026-07-07-mac-host-03-child-supervision-restart",
      "artifact:180.C.26.02:launch-agent-lifecycle-run:2026-07-07-mac-host-03-sigterm-graceful-no-restart",
      "artifact:180.C.26.02:launch-agent-lifecycle-run:2026-07-07-mac-host-03-bootout-clean-uninstall"
    ]
  }
}
```

## Lifecycle steps executed and observed

1. **Lint + register** — `plutil -lint` OK;
   `launchctl bootstrap gui/$(id -u) <plist>` + `launchctl enable` +
   `launchctl kickstart -k` registered the job in the per-user GUI domain (not
   root session zero). `launchctl print` showed `state = running`,
   `pid = 77576`, `properties = runatload | inferred program`, program = the
   bundled `.app` binary. RunAtLoad fired on bootstrap (the same mechanism that
   starts the job at login when the plist loads).
2. **Real host under launchd** — the shell logged
   `running as LaunchAgent (gui domain)` and spawned the REAL Node remote-host
   child (`tsx src/main.ts`); `GET /health` on 127.0.0.1:4171 answered
   `status: healthy | platform: darwin`. On real darwin the host defaulted to
   the macOS Keychain identity store and failed loud on the missing item
   (`identity-keychain-item-missing`,
   `macos-keychain:com.oshun.bellona.remote-host.identity:default`) — the honest
   not-paired state, no fabricated identity.
3. **Crash restart (KeepAlive Crashed=true)** — `kill -9 77576`; after the 10s
   ThrottleInterval launchd restarted the shell with a NEW pid `78231`
   (`launchctl blame` → `semaphore`). VERIFIED.
4. **Child supervision** — `kill -9` of the Node host child (`77591`); the
   shell's supervisor logged `remote host child exited with status …` and
   `restarting remote host child in 5s`; `/health` answered again with new pid
   `78424`. VERIFIED (this also covered a real restart-crash-restart sequence
   when the first replacement hit the still-bound port and exited 1; supervision
   retried and recovered).
5. **Graceful stop (SIGTERM), no restart on clean exit** —
   `launchctl kill TERM gui/$(id -u)/com.oshun.bellona.remote-host`: the shell
   forwarded SIGTERM to the child; the host logged
   `host.stopping reason: SIGTERM` (cancel running commands → close gateway
   connection → stop adapters → flush); child exited 143; shell logged
   `terminated cleanly` and exited 0. `launchctl print` then showed
   `state = not running`, `last exit code = 0`, `job state = exited` — NOT
   restarted, per `KeepAlive.SuccessfulExit=false`. The child health port
   stopped answering. VERIFIED.
6. **Clean uninstall** — `launchctl bootout gui/$(id -u) <plist>`,
   `rm -f <plist>`, `rm -rf "Bellona Remote Host.app"`; `launchctl print` now
   answers `Bad request.` (service gone) and no bellona LaunchAgents remain in
   `~/Library/LaunchAgents/`. Keychain identity was never created (host was
   unpaired), matching the "preserve Keychain identity only when the operator
   has not unpaired" assertion. VERIFIED.

## Raw evidence artifacts (captured during the run)

`01-plutil-lint.txt`, `02-bootstrap.txt`, `03-print-running.txt`,
`04-crash-restart.txt`, `05-child-supervision.txt`, `06-graceful-term.txt`,
`07-uninstall.txt`, plus the launchd `agent.out.log` shell/host transcript. The
transcript excerpts above are copied verbatim into this document; the raw files
were captured under the session working directory during the run.

## QA assertions from the plan — status

- LaunchAgent registers in the per-user GUI domain, not root session zero — ✅
- RunAtLoad starts the host after load/login — ✅ (fired on bootstrap)
- KeepAlive restarts after crash but not after clean operator quit — ✅
- SIGTERM triggers graceful session stop, diagnostic flush, gateway disconnect —
  ✅ (`host.stopping` path)
- Clean uninstall removes plist and app bundle, preserving Keychain identity
  only when not unpaired — ✅ (no identity existed; removal path implemented and
  covered by `MacOSKeychainRemoteHostIdentityStore.removeIdentity`)
