Eve library

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

Guide

Revision 1

On this page
  • 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)