- 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#
- Lint + register —
plutil -lintOK;launchctl bootstrap gui/$(id -u) <plist>+launchctl enable+launchctl kickstart -kregistered the job in the per-user GUI domain (not root session zero).launchctl printshowedstate = running,pid = 77576,properties = runatload | inferred program, program = the bundled.appbinary. RunAtLoad fired on bootstrap (the same mechanism that starts the job at login when the plist loads). - 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 /healthon 127.0.0.1:4171 answeredstatus: 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. - Crash restart (KeepAlive Crashed=true) —
kill -9 77576; after the 10s ThrottleInterval launchd restarted the shell with a NEW pid78231(launchctl blame→semaphore). VERIFIED. - Child supervision —
kill -9of the Node host child (77591); the shell's supervisor loggedremote host child exited with status …andrestarting remote host child in 5s;/healthanswered again with new pid78424. 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). - 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 loggedhost.stopping reason: SIGTERM(cancel running commands → close gateway connection → stop adapters → flush); child exited 143; shell loggedterminated cleanlyand exited 0.launchctl printthen showedstate = not running,last exit code = 0,job state = exited— NOT restarted, perKeepAlive.SuccessfulExit=false. The child health port stopped answering. VERIFIED. - Clean uninstall —
launchctl bootout gui/$(id -u) <plist>,rm -f <plist>,rm -rf "Bellona Remote Host.app";launchctl printnow answersBad 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.stoppingpath) - 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)