Repository navigation
feature: verified Linux install and systemd service lifecycle #945
Description
Feature Description
Same goal as the macOS install issue, on the systemd path, which shares none of launchd's code.
Proposed Solution
- Fresh install via
curl | sh, amd64 and arm64 - Upgrade over an older install: service restarted, config preserved
- Uninstall leaves no unit file;
~/.cortex(config, CA) is explicitly preserved,
not wiped - Uninstall reverts agent settings automatically — today it does not:
agentop configure <agent> disableis a separate, manual step (relates to feature: agent integration contract — reusable detection, settings patching, and revert #939) - Re-running install is idempotent
- Service survives reboot and a crash
-
abctl service status | start | stop | restartaccurate in every state -
stoptolerates the proxy's ~15s drain - Works under user systemd, and states what happens where systemd is absent
Additional Context
Part of the Cortex v0.9.0 release. Gates exit criterion 1 (install works cold). Automated by
the Linux release smoke test.
Activity
fix: Address round-2 review findings on the fake-harness PR
Alan-Cha commentedon Sep 23, 2026
Status update from the #1076/#1079/#1080 (+follow-up #1107) review cycle, full analysis in
authbridge/docs/superpowers/specs/2026-09-16-linux-systemd-lifecycle-design.md:Closed:
Re-running install is idempotent—lingerEnabled()'s parsing had zero test coverage; now fully tested including the exact invocation shape (Test: Add a fakeSystemctl/fakeLoginctl harness for the Linux service path #1080, Fix: Follow-up review findings from #1076/#1080 #1107).stoptolerates the proxy's ~15s drain~~ —renderUnitFor("linux", ...)now setsTimeoutStopSec=20explicitly (Fix: Set an explicit TimeoutStopSec on the Linux service unit #1079).Partial, not checking off yet:
unloadService's systemctl/loginctl invocation shape is now fully tested (Test: Add a fakeSystemctl/fakeLoginctl harness for the Linux service path #1080), but nothing drivesserviceUninstallitself end-to-end (unit file removal, stamp file,~/.cortex). Still open.Restart=on-failuregenuinely restarts onkill -9, stays stopped on deliberate stop). The reboot half is out of automated-CI scope (runners don't reboot) and tracked separately in test: verify the installed Cortex service survives reboot on macOS and Linux #964.abctl service status \| start \| stop \| restartaccurate in every state — thegoosrefactor and afakeSystemctl/fakeLoginctlunit-test harness now exist (Test: Add a fakeSystemctl/fakeLoginctl harness for the Linux service path #1080), matching what macOS already had. Still missing macOS's other half: a real-systemd integration test that drivesloadService/controlService/supervisorRunningthemselves (not just rawsystemctl) against a live session, analogous toTestWaitBootedOut_RealLaunchd.Untouched:
curl \| shon a real Linux box, and upgrade-over-existing against a real running unit — both need actual CI infrastructure, likely belongs with test: release smoke test on Linux CI runners #957 (Linux release smoke test) rather than this issue.launchdUsable()'s clean preflight — explicitly left as an open decision in the design doc, not yet resolved either way.Alan-Cha commentedon Sep 23, 2026
#1108 addresses the last untouched bullet — "Works under user systemd, and states what happens where systemd is absent" — by adding
systemdUsable()(the Linux equivalent oflaunchdUsable()) and wiring it intoserviceInstall's existing preflight. Not checking the box until it merges.feat: Add a Linux preflight for abctl service install
Alan-Cha commentedon Sep 29, 2026
#1108 merged — checking off "Works under user systemd, and states what happens where systemd is absent."
Unrelated but worth flagging here:
mainhas since undergone a large reorg (afb49e9f, "Flatten authbridge/ into the repo root") —authbridge/cmd/abctl/...is now justcmd/abctl/...,authbridge/authlib/is nowcore/, etc. Our code landed before that and moved automatically with it, but the design doc's own path references (authbridge/cmd/abctl/cmd_service_platform.goetc.) still sayauthbridge/...and are now stale in prefix. Not fixing preemptively — flagging so whoever picks up the remaining bullets knows to use the new paths, and can fix the doc's prefixes as part of that work rather than as a separate no-op PR.Remaining, for reference:
serviceUninstallend-to-end: unit file, stamp file,~/.cortexactually removed) and bullet 6's remainder (a real-systemd integration test that drivesloadService/controlService/supervisorRunningthemselves, not just rawsystemctl— the actual analog ofTestWaitBootedOut_RealLaunchd) are the two pieces of actual#945-scoped work still open.Alan-Cha commentedon Oct 7, 2026
Checked off the upgrade box — now covered end-to-end by the Linux release smoke test (#957, landed in #1288):
assert_running_binary_is_current+assert_running_version_isconfirm the systemd unit is actually running the newly-installed binary post-upgrade (not a stale process, the exact #1203-class regression this is guarding against), and a config marker confirms the config survives untouched.Alan-Cha commentedon Oct 8, 2026
Split and corrected the uninstall bullet: the original wording bundled 'no unit file, no ~/.cortex, no modified agent settings' as one guarantee. In practice:
serviceUninstallexplicitly tells the user to separately runagentop configure claude-code disable/agentop configure opencode disable— left that half unchecked and split out as its own line, since it's a real gap (or a deliberate scoping decision someone should confirm), not a wording issue. Possibly belongs with feature: agent integration contract — reusable detection, settings patching, and revert #939's settings-revert work.Alan-Cha commentedon Oct 15, 2026
#1405 adds the arm64 half of "Fresh install via
curl | sh, amd64 and arm64" — matrix-izes the Linux release smoke test (#957) to also run on GitHub'subuntu-24.04-armrunner, exercising the exact same fresh-install/upgrade/uninstall pathinstall.sh's ownuname -mdetection andrelease-binaries.yaml'slinux/arm64tarballs already support. Not checking the box until it merges.