Repository navigation
fix(service): report and remove the user-scope gateway unit on Linux - #13964
Conversation
|
Intent, for the review lanes and the maintainers: on Linux, |
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS The ownership resolver that gates Watch
SuggestionsThe fixed 2 s [DESIGN-REVIEWED] 6067a76 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify on a real systemd host that uninstall's mask-unlink fires only at the installer's exact path and that a sudo shell reads the user scope unreachable. What this change shipsInventory (10 items) — 10 justifiedIntent: make
[FIRST-PRINCIPLES-REVIEWED] 6067a76 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
8dc5a7e to
b34d750
Compare
|
self-added: yes
|
|
self-added: yes
|
|
b34d750 to
f0c1687
Compare
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
f0c1687 to
21d1fbc
Compare
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
88b3d04 to
ae04ae9
Compare
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
`kirocrew service status`, `is_active`, `stop`, `restart` and `service uninstall` queried the system systemd manager only, so a gateway running as the per-user unit the installer's own SELinux remedy stands up was reported as `inactive (dead)` and could not be stopped or removed. Every scope-reading verb now accounts for both scopes and names the one it reports on: `status` prints `system scope: …` / `user scope: …` with `not installed`, `not reachable from this shell (…)`, or the unit's `ActiveState (SubState)` plus the `systemctl status` block for each scope that has a unit. Two predicates: `is_active` (reach — any state but inactive/failed, so a crash loop in `activating (auto-restart)` is one `stop`/`restart` can address) and `is_up` (health — `active`, what `is-active` exits 0 for), which the `service status` exit code follows. `restart` returns a per-scope report and confirms the unit stays up after the manager's `restart`: the unit is `Type=simple`, whose start job succeeds at the fork, so `systemctl restart` exits 0 for a gateway that dies at once; a non-zero exit is classified by the unit's state afterwards (a refusal leaves it unchanged, a failed job leaves it `failed`), and `kirocrew restart` prints each failed scope with the remedy for its kind — that scope's own restart command, its journal, or `service status` — and never falls through to the foreground spawn after an attempted restart. `uninstall` tears each scope down in the order stop → disable → verify inactive → unlink → daemon-reload, refuses an alias or a running unit under any load state but `loaded`, and returns a per-scope `UninstallReport` the controller prints; a step the manager refuses leaves the file in place and exits 1. Load state comes from `systemctl show -p LoadState …` so a scope with no unit is never shown as inactive. A root shell whose `SUDO_USER` names a human is decided in-process and never spawns `systemctl --user`; any other unreachable user bus is systemd's own non-zero exit, reported verbatim. Every `systemctl --user` spawn uses the resolver the pod runtime already used for the account's bus environment, now shared in `service.common`. `kirocrew logs` reads the user journal when the per-user unit is the running or only one, and takes the sudo rung for the system journal only on journalctl's access hint or a failed probe. `installed_unit_path()` reads the per-user unit too, so doctor's service checks see it. The install scope is unchanged (system). The remedy text and the docs describe the two-scope contract. Fixes #13915
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
Description gains the |
Problem / Motivation
Goal: On Linux,
kirocrew service status,is_active()anduninstall()see a gateway that runs as a systemd user unit, instead of asking only the system manager and reporting itinactive (dead).On Linux,
kirocrew service statusreports a running gateway asinactive (dead)when that gateway is a systemd user unit.status(),is_active()anduninstall()insrc/kiro_crew/service/linux.pyask only the system manager, neversystemctl --user. The per-user unit is not an exotic layout: the installer's own SELinux refusal renders one (render_unit(user_scope=True)), tells the operator tosystemctl --user enable --nowit, and then admits thatservice status|uninstall"only looks at the system unit, so it will not see this one".Why it matters
The command an operator runs to check the gateway returns the opposite of the truth, and during a user-unit crash loop it hides the failure it exists to surface.
kirocrew stopandkirocrew restartgate on the sameis_active(), so they cannot reach the unit either;kirocrew logsopens the journal only when the system unit file exists, so the crash loop's203/EXEClines in the user journal are never shown; andservice uninstallleaves the unit running while printing "stopped and removed". Backend/CLI only, no UI change.Not a goal
service installstill writes the system unit, and preferring user units at install time stays with feat(service): prefer systemd user units #10813.RestartSec: the window is a fixed 2 s (_RESTART_SETTLE_SECS), and that follow-up shape is not taken here because no death later than the window has been observed.kirocrew stop/restarttake the foreground-gateway path, tracked as #14190 (deferred-finding, due 2026-10-09).What changed (motivation → approach → change)
src/kiro_crew/service/linux.py_systemctl(..., user=True)runssystemctl --user(never under sudo) with the environment fromsystemctl_user_env()._unit_state()reads one scope withsystemctl show -p Id -p LoadState -p ActiveState -p SubState -p FragmentPath -p Result, parsed asKey=valuelines.status()printssystem scope: …thenuser scope: …—not installed,not reachable from this shell (<reason>), orActiveState (SubState)(, an alias of <Id>when the name resolves elsewhere) — and thesystemctl statusblock for each scope that has a unit. One guard is shared by every verb that acts on the name and it fails closed (_UnitState.ours): the canonicalIdshowanswers must be exactlykirocrew.service— an operator'sAlias=kirocrew.serviceon their own unit, or an answer with noId, is refused whole byuninstall, never selected bystop()/restart(), and not counted byis_active()/is_up()/ the logs predicates, while the headline still names it (active (running), an alias of shared.service). Two predicates, named:is_active()is REACH — true when either scope RUNS our unit, anyActiveStatebutinactive/failed, so a unit crash-looping throughactivating (auto-restart)counts, andstop()/restart()act on each scope that does, selected by the samesystemctl show(is-activeanswers non-zero foractivating, which would letkirocrew stopissue nothing at a flapping unit);is_up()is HEALTH —activeorreloadingin either scope, whatis-activeexits 0 for — and theservice statusexit code follows it.restart()returns a per-scopeRestartReport:systemctl restartin each running scope, then_confirm_up()re-reads the unit for_RESTART_SETTLE_SECS(2 s, a read every 0.25 s) because the unit isType=simpleand its start job succeeds the moment the process is forked — a unit seen inactivating (auto-restart),failed,inactiveordeactivatinginside the window is a FAILED restart carrying that state and itsResult(exit-code,start-limit-hit, …),activating (start)is waited for until the deadline, and onlyactiveat the deadline is ok; a non-zerosystemctl restartis a REFUSAL carrying the manager's first diagnostic line and the restart command for THAT scope (sudo systemctl restart kirocrew/systemctl --user restart kirocrew), every running scope is attempted; a stopped unit in the other scope is never started.user_unit_path()answerscontroller.installed_unit_path()for the user scope: theFragmentPathof a LOADED unit whose canonicalIdis ours and whose file exists, elseNone— fail-closed, so a blank or malformedshowanswer, an unparseable unit (bad-setting/error), a mask and an alias hand doctor nothing.uninstall()runs both scopes through one_teardown_scope(), and every verb in it rests on ONE decision, `_owned_unit(fragment, user=…) -> OwnedUnitsrc/kiro_crew/service/common.pysession_runtime_dir()andsystemctl_user_env(): the one resolver for the environment asystemctl --userspawn runs with —os.environplusXDG_RUNTIME_DIR(from the runtime dir,/run/user/<uid>when unset) and, only when the bus socket exists there,DBUS_SESSION_BUS_ADDRESS; an explicitly set value always wins. Moved here frompod/runtime.pyso the service verbs and the pod runtime share it.ScopeRestart/RestartReport: one scope's restart outcome (scope,ok,reason,kind∈ refused / not-up / unconfirmed,hint) and the per-scope reportrestart()andcontroller.restart_service()return —attempted,ok(at least one scope restarted and every one up),restarted,failures; truthy exactly whenok, soif restart_service():reads as the bool it replaces.system_restart_command_hint()/user_restart_command_hint():sudo systemctl restart kirocrew/systemctl --user restart kirocrew, each spelled once and unconditional — the report andmanual_restart_hint()use them, so a report built by a process on another platform (the Windows test shard) reads the same.restart_command_hint()— what the update path, the Slack restart-failure hint and the install-time credential warning print — picks by scope on systemd with two stats and no spawn: the system unit file present → the system command; only the per-user unit file at the remedy's location → the user command; neither (a foreground gateway) → the service-awarekirocrew restart.src/kiro_crew/pod/runtime.py_session_runtime_diris the shared helper;_systemctl_env()issystemctl_user_env()plus the pod-onlyLC_ALL=Cpin. Same mapping as before, one owner.src/kiro_crew/service/controller.pyinstalled_unit_path()reads both Linux scopes: the system unit file first (a stat), else the per-user unit the calling account's manager has loaded (linux.user_unit_path()), soinstalled_service_has_managed_marker()and doctor's headless-credential check — its two consumers — see a user-scope gateway as the installed service it is; the marker check reads throughlinux.unit_file_carries_managed_marker(), the same readinguninstalldecides ownership by.service_status()exits 0 onlinux.is_up()(health), notis_active()(reach).restart_service()returns theRestartReport(linux.restart()'s on Linux; on macOS onelaunchdoutcome, a refusal carrying the bootout/bootstrap pair).manual_restart_hint()keeps its signature and answers the unconditionalsystem_restart_command_hint()on systemd — never the circularkirocrew restart; the user-scope command reaches the operator through the report's per-scopehint, not through a parameter here.uninstall_service()prints one line per scope from the report; nothing installed anywhere printsNo kirocrew service was removed.with both scope lines and exits 0; a scope inunfinishedgetssrc/kiro_crew/cli_server.pykirocrew restart: when the service manager was asked and the report is not ok, the command exits 1 with one line per scope acted on and the remedy for a failed scope's kind —Run the restart yourself: <that scope's restart command>for a refusal,Read why it exits: <that scope's journalctl>for a unit that is not up,Check its state: kirocrew service statuswhen the manager stopped answering — and NEVER falls through to the foreground spawn after an attempted restart (report.attemptedis checked before the liveis_service_active(), which now only covers a restart that attempted nothing): a unit that landedfailedis still an installed, enabled definition, and a foreground gateway beside it would be an unmanaged competitor. The verdict is per scope, never one line: with a unit running in BOTH scopes (a stale crash-looping system unit beside the working per-user one)restart()restarts one and not the other, and the headline reads⚠️ Restarted kirocrew service in the user scope; the restart did not take in the system scope:withuser scope: restarted.and the system scope's reason and remedy under it — never "the gateway was NOT restarted", which is false for the gateway the operator uses; the exit code is still 1 because a scope needs a hand, the shapeservice uninstallgives a teardown finished in one scope. The audit row readsoutcome=partial restarted=user reason=service_restart_not_upfor that case andoutcome=denied reason=service_restart_denied/_not_up/_unconfirmedwhen nothing restarted.kirocrew logstails the user journal (journalctl --user -u kirocrew.service) when the account's own manager has the unit (svc_linux.user_unit_installed()) and it is the only unit or the running one (svc_linux.user_unit_active(), asked only when a system unit file also exists); no sudo rung, an empty probe falls through to the system journal or the log file. The user probe runs with--quiet(a journal with no matching entries prints-- No entries --on stdout with exit 0, which is not a row; quiet suppresses it, and on systemd 219 the-- Logs begin at …header too). The system-journal arm is the repository base's, byte for byte: an unprivilegedjournalctl -u kirocrew.service -n 1 --no-pagerprobe, exec unprivileged when it printed anything, thesudo journalctlrung (a TTY prompt, or thestdin is not a TTYrefusal) only when it printed nothing. Nothing in this arm reads journalctl's stderr or classifies its notices: the earlier rounds' hint-keyed rung was dropped on the First Principles lane's second arm, because its premise (the exact notice/hint text of an external tool across systemd releases) is one no test here can confirm, and because — as the Opus lane showed — the access hint is printed for EACCES on the system journal files while the unit's own rows from the ACL-readableuser-<uid>.journalare still printed, so keying on the hint pushed the very user it addresses to a sudo prompt for logs they could read. Rows are rows.src/kiro_crew/slack/gateway.pyrestart_command_hint()throughasyncio.to_threadinstead of calling it on the event loop. The hint stats the two unit-file locations and the per-user one is under the account's home, which can be a network mount: a stat against a disconnected mount blocks for as long as the mount does, and on the loop thread that would freeze chat and the liveness heartbeat together with nothing in-band to clear it (the watchdog's kill is the only exit). The hint's docstring now says it is a synchronous call for a thread that may block.test/test_service.py,test/test_cli_server_more_coverage.py,test/test_cli.py,test/test_cli_restart_marker_fallback.py,test/test_slack_gateway.py_fake_systemctl: asubprocess.runstand-in that answers per scope and verb (now withResult, and arestart_lands_instate or sequence a restarted scope answers afterwards), so no test touches the host's systemd; a fake clock walksrestart()'s settle window without sleeping.TestLinuxServiceScopes,TestLogsCmdUserScope,TestInstalledUnitPath,TestManagedServiceMarkerDetection; the stop/restart/status/uninstall/logs cases that assumed one scope are re-pointed at the fake, and the CLI tests that stood in for "no service to restart" withFalsenow hand_restartan emptyRestartReport.docs/system-specs/modules/cli.md,docs/guides/install.mdservice status/uninstall/logs/restartrows, the Restart Command and Logs Command sections, the two-scope bullet (the two predicates and the confirmed restart), the doctor gate and the SELinux section describe the two-scope contract, the health exit code, the checked teardown and the shared user-bus environment; the Restart Command section also states the per-scope headline of a restart that took in one scope only and that the gateway's update-failure handler resolvesrestart_command_hint()in a worker thread; the guide's "will not see a user unit" note is replaced and points at the open install-scope tracker.The symptom is a question asked of the wrong manager. systemd keeps two independent unit namespaces per host — the system manager and one manager per logged-in account — and
systemctlwithout--usernever consults the second. Worse,is-activecannot tell "no unit in this scope" from "a unit that is stopped": both answerinactive, which is how a scope with nothing in it was printed as a dead service.So every scope-reading verb asks both managers and names the one it reports on, and the load state comes from
show, whoseLoadState=not-foundis the one honest signal for an empty scope. A user scope the process cannot see is reported asnot reachable from this shell, never as inactive, anduninstalldeletes nothing there: the sudo case is decided fromgeteuid()andSUDO_USERbefore any spawn (under sudo,systemctl --userwould answer for root's manager, not the human's), and every other failure is systemd's own non-zero exit carried verbatim — nothing classifies stderr text. The install scope is unchanged:service installstill writes the system unit, and preferring user units at install time stays with #10813.Two consequences follow from reading the user scope at all. A teardown must not delete a unit file on the strength of a
stopit never checked — a refused stop leaves the unit loaded and possibly running, and unlinking its file would leave a gateway with no unit to find it by while the report readremoved— sostopanddisableare checked in both scopes and a refusal is reported, not acted past. And asystemctl --userspawned from the gateway's own shell inherits no login-session variables, which is the "Failed to connect to bus" the pod runtime already cures by backfilling them; the service verbs spawn with the same resolver, sounreachableis a fact about the host, not the shell.activatingis "running" for one question and not for another, so the module asks two.stopandrestartmust reach a unit the manager is still trying to run — a crash loop lives inactivating (auto-restart)— sois_active()counts it. Theservice statusexit code answers "is the gateway up", and the crash loop is the failure that command exists to expose, so it followsis_up():active, whatis-activeexits 0 for. The same distinction decides a restart: the unit isType=simple, whose start job completes at the fork, sosystemctl restartexits 0 for a gateway that dies at once.restart()re-reads the unit for two seconds and reports per scope — up, not up (state andResult), or unconfirmed when the manager stops answering — and classifies a non-zero exit by the unit's state afterwards, since that exit covers both a job the manager refused (unit unchanged) and one it ran that failed (unitfailed). Each kind gets its own remedy, and an attempted restart never falls through to the foreground spawn: afailedunit is still an installed, enabled definition.Backwards compatibility
Compatible:
status()still returns a string. The controller'sservice statusexit code keeps the meaning the base gave it — 0 iffsystemctl is-activewould exit 0 (active/reloading) — now over both scopes (linux.is_up()): a running user-scope gateway exits 0 where the base exited 1; a unit crash-looping throughactivating (auto-restart)exits 1 as it did on the base, with the headline naming that state.is_active()is true for anyActiveStatebutinactive/failed, sokirocrew stop/restartreach a flapping unit where the base issued nothing.uninstall()returns anUninstallReportinstead ofNone; its only caller iscontroller.uninstall_service(), updated here.linux.restart()andcontroller.restart_service()return aRestartReportinstead of a bool — truthy exactly when the restart took, soif restart_service():keeps its meaning; the one caller (cli_server._restart) reads itsattempted/failures.kirocrew restarton a systemd unit now exits 1 with the unit's real state where the base printed✅ Restarted kirocrew service.after asystemctl restartthat exited 0 into a crash loop, waits up to 2 s to confirm a restart, and no longer printsThis process lacks the privileges…/sudo systemctl restart kirocrewfor a user-scope unit or for a unit that exits on start — the line names the scope, what happened, and the remedy for it; after an attempted restart it never takes the foreground-spawn path the base took when the unit read inactive afterwards. With a unit running in both scopes and only one restarting, the headline names the scope that restarted and the one that did not (⚠️ Restarted kirocrew service in the user scope; the restart did not take in the system scope:) instead of the previous rounds' unconditionalthe gateway was NOT restarted, and the audit row's outcome ispartial(withrestarted=<scopes>) rather thandenied; the exit code stays 1.manual_restart_hint()keeps its signature and, on systemd, its answer (sudo systemctl restart kirocrew), now unconditional on the unit file's presence.restart_command_hint()— printed by the update path, the Slack restart-failure hint and the install-time credential warning — changes on systemd hosts without a system unit file: only a per-user unit file at the remedy's location →systemctl --user restart kirocrew(the base printedsudo systemctl restart kirocrew, which answersUnit kirocrew.service not foundthere); neither file, or both →kirocrew restart(the base printed the system command); a host with the system unit file alone is unchanged. The gateway's auto-update failure handler awaits the hint in a worker thread (asyncio.to_thread) where the base called it inline; the message it pushes is the same.installed_unit_path()on Linux returns the per-user unit's file when the system unit is absent, sokirocrew doctor's Managed Service row and its credential check now fire for a user-scope gateway (read from the sameEnvironment=lines the remedy bakes) where they read "no service installed";installed_unit_path()spawns onesystemctl --user showin that case, none when the system file exists.stop()/restart()keep, for a system unit, their exactsudo systemctlargv; they issue nothing for a scope whose unit is stopped, where the base issued a system-scope command regardless.uninstallrefuses what the base tore down blindly: a loaded unit whosestopordisablethe manager refuses, or that is still running afterstopreturned 0, keeps its file (exit 1); an alias, and a unit running under a runtime mask, an unparseable edit or a removed file, are left whole (exit 1); a system unit file on a host whose manager is present but unreachable from the shell is kept (exit 1) — a host not booted with systemd still removes it as the base did, as does a not-running unit the manager does not have loaded.service uninstallon a host withoutsudoprints both scope lines and exits 1 instead of the base's single❌error, and removes the user unit on the way. Round 10:UninstallReportgainsremovedandremoved_anyreads it, not a line prefix (the fileless-stopped system unit headlines✅ … stopped and removed.); a system-scope refusal with no file atUNIT_PATHand nothing running exits 0 where rounds 3-9 exited 1 (unfinished only when a running unit or the module's own file is left behind); a linked unit keeps its source file where rounds 1-9 followedFragmentPathto it. Round 12:uninstallacts only on units it owns — the installer's file, or one carrying theKIROCREW_SERVICE_MANAGED=1marker line. A vendor unit loaded under our name with no file of ours (rounds 9-11 stopped anddaemon-reloaded it, headlinestopped and removed) and an operator's own unit linked under our name (rounds 10-11 removed its link) now readleft untouchedwith nothing stopped and exit 0; a linked COPY of our unit (the marker) still loses only its link. An inactive mask at the installer's own path is a mask of OUR name (systemctl maskwrites its/dev/nullsymlink at exactly that path) and is unlinked as on the base —removed (the mask …; kirocrew.service is unmasked), exit 0 (the round-12 head alone left it in place). A mask anywhere else (--runtime, under/run) isleft in place (load state masked, …). A unit file of ours at the per-user path that the manager does not have loaded is now removed like the system scope's. TheUnitPathquery and the search-directory scan of rounds 10-11 are gone.kirocrew logs's system-journal arm is the base's, byte for byte (unprivileged probe → exec when it printed anything → thesudo journalctlrung only when it printed nothing); the user-journal rung above it is new and reaches a per-user unit's journal where the base offered only the system journal or the log file.pod/runtime.py's_systemctl_env()returns the same mapping as before.Tests
test/test_service.py::TestLinuxServiceScopes(subprocess.runmocked per scope and verb): system unit absent + user unit active →system scope: not installed,user scope: active (running), noinactive (dead),is_active()True, no sudo; both absent → bothnot installed; user bus unreachable (Failed to connect to bus: No medium found) →user scope: not reachable from this shellwith the diagnostic, system line intact; system active → itssystemctl statusblock kept plus the user line; the reporter's layout (system loaded but stopped, user running) →system scope: inactive (dead)besideuser scope: active (running); root withSUDO_USER→ user scope unreachable and no--userspawn; every--userspawn carries the backfilled bus pointers (systemctl_user_env()) while the system-scope spawn keeps the inherited environment, andpod.runtime._systemctl_env()is the shared mapping plusLC_ALL=C;stop()/restart()reach a user-only unit through--userwithout sudo; both scopes active and the restart refused → both restarts still issued, result False;uninstall()with only the user unit →--user stop/disable/daemon-reload, the fragment file unlinked, no sudo; a refused user-scopestop(RefuseManualStopwording) → the unit file still exists, nodisable, nodaemon-reload,os.unlinknever reached,left in place (\systemctl --user stop kirocrew.service` failed: …; the unit file was not removed),unfinished == {"user"}, controller exit 1 with ⚠️ on the user line only; a refused user-scopedisableafter a successful stop → file kept,unfinished == {"user"}; a refused system-scopestop→ norm, nodisable,left in place (`sudo systemctl stop kirocrew.service` failed: …), the user scope still queried and reported, ⚠️ on the system line and not on the user line, exit 1; a system-scoperm -fthat exits non-zero →stopped and disabled, but its unit file … could not be removed (…)with thesudo systemctl daemon-reloadremedy, nodaemon-reloadissued,unfinished == {"system"}; a stale system unit file with nosudoon the host (shutil.which→ None,sys.platformpinned to linux) → nosudospawn at all,, the user unit stopped, disabled and its file removed, exit 1; a system unit file on a host whose manager cannot be reached and that is not booted with systemd (everysystemctlanswersSystem has not been booted with systemd as init system (PID 1)…,/run/systemd/systemabsent) → nostop/disable,rm -fissued,removed (…), user scopenot reachablewith that diagnostic, nothing unfinished; the same unreachable manager on a host where/run/systemd/systemexists (Failed to connect to bus: Permission denied) → norm,left in place (the system manager is not reachable from this shell: …),unfinished == {"system"}; a system unit file the manager answersLoadState=not-foundfor (astopwould exit 5, not loaded) → nostop/disable,rm -f+daemon-reload,removed (…); a RUNNING unit whose load state ismasked, in either scope → nostop,disable,rmoros.unlink,left in place (an active unit whose load state is masked: unmask and stop it first, …), ⚠️ on that line, exit 1; a user unitnot-foundyetactive→ refusedstop it first, notnot installed; an alias in the SYSTEM scope → no verb,left in place (kirocrew.service is an alias of shared.service; manage that unit); astopthat returns 0 while the unit stays active → no unlink, nodaemon-reload,left in place (still active (running) after `systemctl --user stop kirocrew.service` returned 0; …); the user-scope verb order is exactlyshow, stop, disable, show, daemon-reload; a unit inactivating (auto-restart)→is_active()True,user_unit_active()True,stop()issuessystemctl --user stop, nois-activespawned,status()showsuser scope: activating (auto-restart); a stopped system unit beside the running user unit →restart()restarts the user scope only; a fragment not namedkirocrew.service→ left in place; an alias is named in the status headline; neither installed → bothnot installed`, controller exit 0 with the plain statement; both installed → both removed and both named; an unremovable user unit file after a system-scope teardown → both scope lines printed, the AppArmor profile still removed, exit 1; the remedy no longer says "will not see".4926e50b3c) and only the tests kept,test/test_service.pyis red as a whole and every new logs / CLI case fails for its own reason; each later round's new tests were run against the previous head's sources and fail for theirs (round 9, on011b9fa475: the four fileless system-scope cases all readnot installedwith nostopissued, anduser_unit_path()took a blankLoadState/Idanswer as a unit; round 10: in its own bullet below). Earlier heads' red-first evidence lives in each round's disposition comments on the thread.TestLinuxServiceScopes:test_a_persistent_mask_of_our_name_is_removed_in_the_system_scope(both loader readings ofFragmentPath, the mask entry and/dev/null) →sudo rm -f <mask>+daemon-reload, nostop/disable,removed (the mask …; kirocrew.service is unmasked),removed == {system};…_in_the_user_scope→ the entry really unlinked,systemctl --user daemon-reload, no sudo;test_a_link_at_our_path_that_does_not_resolve_to_dev_null_is_not_a_maskpins the boundary (a link at our path to an operator's unmarked file,bad-setting/not-found, or left dangling →left in place (load state …), no verb); the old masked-user-unit case is narrowed to a mask NOT at our path. Red-first on47e51b3527: the three positive cases fail withleft in place (load state masked, unit file …)— the Opus reading, verbatim.TestLinuxServiceScopes(the fake reports the module'sUNIT_PATHas the system fragment anduser_unit_file_pathis pinned undertmp_path; a test's own unit files carry the marker, an operator's or vendor's do not): a vendorkirocrew.service(a/usr/libstand-in) loaded and RUNNING with nothing atUNIT_PATH→left untouched (not installed by Kiro Crew: …),sudo systemctl stopNOT issued, no verb at all,removed == unfinished == {}, controller exit 0 withNo kirocrew service was removed.(test_a_vendor_unit_with_no_unit_file_of_ours_is_left_untouched_not_stopped); an operator's unitsystemctl --user linked under our name, reported by its resolved target → left untouched, link and source intact, no verb; the same source WITH the marker, reported as the link → ours-by-link: link removed, source kept; a link at the installer's path to an unmarked lower-priority file (the systemd 252 shape) → left untouched, nothing stopped; the same file marked → ours-by-link (link gone, file kept), and withdisablerefused →left in place (… disable … failed …)after the stop, both intact; a marked file elsewhere is ours by the marker, the installer's path is ours marker or not, another name never is, an unreadable or undecodable file makes no claim (unit_file_carries_managed_marker); the remedy's own file beside a same-named shadowed file → unlinked, the other untouched; a definition under another name → left untouched, no verb. Structural (test_every_teardown_arm_rests_on_the_one_ownership_decision): the module's AST shows_stop_and_disable,_sudo_run("rm", …)andos.unlinkreachable only from functions whose first parameter is anOwnedUnit(the installer's temp-file cleanups aside), and with_owned_unitpatched toNone,uninstall()issues no verb in either scope across running / stopped / one-scope layouts. Red-first onae04ae9172: the vendor unit was stopped (['sudo', 'systemctl', 'stop', 'kirocrew.service']in the calls), the operator's linked source lost its link, no resolver existed for the structural test to find.TestLinuxServiceScopes: a link entryos.unlinkcannot remove (a marked source) →stopped and disabled, but the link … could not be removed (…); remove the link by hand — not the file it points at, unfinished, source kept; the user-scope verb order isshow, stop, disable, show, daemon-reload;removed_anyis theremovedset, not a prefix; a system-scope inactive alias with no file atUNIT_PATHfinishes the scope (exit 0) while the same alias running, or with the file present, stays unfinished.uninstall()asks the system manager (unprivilegedshow) before answeringnot installed; a LOADED, running unit of ours whose file is gone getsstop+daemon-reload, nodisable, norm,stopped (… already gone …); the same unit leftnot-foundby adaemon-reloadis refused whole; a runtime mask with no file isleft in place (load state masked, …); an unreachable manager readsnot reachableonly where/run/systemd/systemexists;user_unit_path()answers only forloaded+Id=kirocrew.service.restart_command_hint()'s call-time import carries the# circular importnote.test_slack_gateway.py::…::test_failure_path_resolves_the_restart_hint_off_the_event_loop— the hint double blocks on athreading.Eventonly a loop task sets, so a hint run on the loop thread cannot deliver the pushed line (deterministic);test_cli.py::…::test_a_unit_in_both_scopes_is_reported_per_scope_never_as_not_restarted—⚠️ Restarted kirocrew service in the user scope; the restart did not take in the system scope:,NOT restartedabsent, auditoutcome=partial;TestControllerDispatch::…mixed_report…—restarted/failurespartition the outcomes.Id=shared.service) →is_active()/is_up()False,stop()andrestart()issue nothing, headlineactive (running), an alias of shared.service; an answer with NOId→ not acted on,left in place (the manager did not report kirocrew.service's canonical Id, …), unfinished; a manager that vanishes afterstop→left in place (the user manager stopped answering after …), no unlink; the report hint does not depend on the host running the module (UNSUPPORTED/LAUNCHDpinned — the Windows and macOS shards' shape);TestRestartCommandHint: system file only →sudo systemctl restart kirocrew, user file only →systemctl --user restart kirocrew, both / neither / launchd / unsupported →kirocrew restart;manual_restart_hint()on systemd is the system command even with no unit file.TestLogsCmdSystemdis the base's contract again: rows → unprivileged exec; an EMPTY probe → thesudo journalctlrung on a TTY (the base pin restored verbatim) and thestdin is not a TTYrefusal without one; rows WITH the access hint → still the exec.TestLinuxServiceScopes/TestControllerDispatch/TestInstalledUnitPath/TestManagedServiceMarkerDetection(fake clock, no wall time): a user-only unit whosesystemctl --user restartexits 0 and then readsactivating (auto-restart)withResult=exit-code→okFalse, kind not-up, the reason names the state andlast result: exit-code, the hint isjournalctl --user -u kirocrew.service -n 50 --no-pager,is_active()still True andis_up()False; a firstactivereading followed byauto-restartinside the window → failure (the window is walked, one reading is not confirmation);activating (start)twice thenactive→ ok; stillactivating (start)at the deadline →still activating (start) … 2s after the restart, the whole window walked;activeat every poll → ok with the window walked;failedwithResult=start-limit-hit→ not-up withsudo journalctl -u kirocrew.service -n 50 --no-pager; the bus going away mid-window → kind unconfirmed, hintkirocrew service status, no "exits" claim; a non-zerosystemctl restartwith the unit stillactiveafterwards → refused,sudo systemctl restart kirocrew; a non-zero exit (Job for kirocrew.service failed …) with the unitfailed (start-limit-hit)afterwards → not-up, the journal, never "refused"; both scopes running and both refused → two refusals withsudo systemctl restart kirocrewandsystemctl --user restart kirocrewrespectively;is_active()/is_up()overactive,reloading,activating (auto-restart),activating (start),deactivating,failed,inactive(reach true for the first five, up only for the first two);is_up()reads either scope;service_status()exits 1 for a crash-looping user unit whileis_active()is True and the headline readsuser scope: activating (auto-restart);installed_unit_path(): a system file answers with no spawn; absent → onesystemctl --user show, no sudo; a loaded (even stopped) user unit → itsFragmentPath;not-found, a mask (/dev/null), an alias, an unreachable user scope, and a fragment the operator deleted →None;installed_service_has_managed_marker()readsFalsethenTrueoff the user unit's file.test/test_cli.py::TestRestart: a refused system-scope report → exit 1,Run the restart yourself: sudo systemctl restart kirocrew, auditservice_restart_denied; a user unit not up →Read why it exits: journalctl --user -u kirocrew.service …, nosudo, auditservice_restart_not_up; an attempted restart whose unit readsfailed→ exit 1,is_service_activenever called, nothing spawned; an unconfirmed report →Check its state: kirocrew service status.TestLinuxControlPaths/TestLinuxUnitRendering/TestLinuxPrivilegeResolution/TestControllerDispatch/TestAppArmorNeverFailsTheInstall: the cases that mocked a single scope or aNoneuninstall return drive the same fake (system unit active) or a realUninstallReport, asserting the samesudo systemctl stop|restartargv; the restart cases assert the report (ok,failures,attempted) where they asserted a bool.test/test_cli_server_more_coverage.py::TestLogsCmdUserScope: no system unit +user_unit_installed()True + a user-journal probe with rows → exec ofjournalctl --user --no-pager -u kirocrew.service -n 42 -fafter exactly onejournalctl --user --quiet … -n 1probe, audited first; an empty user-journal probe → the plain log file, no sudo; a journalctl fake that answers-- No entries --unless asked with--quiet→ the log file is tailed, never the empty journal; both units present and the user unit active → the user journal; both present and the user unit inactive → the system journal as before.test_missing_unit_falls_through_to_the_plain_log_fileadmits the onesystemctl --user showquery (answering not-found) and still forbids any journal probe.-n0on this head:test/test_service.py(406 passed, 3 skipped),test/test_cli.py(403 passed, 2 skipped),test/test_slack_gateway.py(337),test/test_cli_server_more_coverage.py(123),test/test_cli_restart_marker_fallback.py(10),test/test_cli_doctor.py(259),test/test_gateway_restart_uses_respawn_executable.py+test/test_internal_python_isolation.py+test/test_update_check_install_aware.py+test/test_governance_updates.py+test/test_spawn_audit.py(the files that read_auto_apply_update's body),test/test_pod.py+test/test_pod_health_wait.py+test/test_pod_launchd.py(578 passed, 1 skipped — the moved helper changes nothing for pods,TestSessionBusincluded). Black ratchet,black --checkon the non-baselined files, isort, flake8, mypy on the changed files,check_subprocess_encoding.py,check_comment_history.pyanddocs-lint.shpass.test/e2e/scenarios/test_service_install_dry_run.pyneeds the pod fixture and was not run here; it drivesrender_unit, which this diff does not touch. Rebased onto main4d683462c2after fix(ci): stop platformdirs' pytest11 plugin killing Windows pytest lanes #14268 merged (a pure replay, like the earlier rebase onto7b2da39c53after fix(settings): regenerate the settings registry for the moved double-click route #14138); the Windows reds from ci(windows): platformdirs 4.12.0 declares a pytest11 entry point at platformdirs.pytest_plugin that will not import, so every Windows pytest lane dies before collection #14249 clear. TheBackend Tests (Windows) (5)reds of88b3d04bd8(aUnitPathfilter droppingC:\…) cannot recur: the query is gone. TheBackend Tests (Windows) (1)red istest/test_history_index_worker.py::test_a_contended_write_waits_instead_of_failing, #13215 (the test assertselapsed >= holdliterally), not this change. TheBackend Tests (Windows) (7)red on47e51b3527istest/test_runtime_cleanup_windows.py::test_windows_owner_shutdown_reclaims_children_after_root_exit(assert ['5564'] == []), #12359, the listed flake — not this change; rerun once, passed. Earlier heads'macOS (2)cancellation (a 32-minute stall, no failing test) andAwait Fast Gatered (ci: CodeBuild runner queue stalls head-of-line-block main (jobs wait hours for a runner; concurrency group holds every later push) #12800) were the runners', not gates.kirocrew stop/restarttake the foreground-gateway path (CLI refusal when an alias holds the service name #14190) — less harm than the base, which stopped the alias target. Rounds 7-13 had no local lane (execution cap); those heads rest on the mechanical gates, the red-first tests and transcripts 3-4.Manual verification
Real systemd (
systemd 252 (252.23-12.amzn2023), an Amazon Linux 2023 dev desktop), this head'ssrc/kiro_crew/service/linux.py. Transcripts 1-2 use read-only verbs only —show,list-units,is-active,status, and the module'sstatus()/is_active()/is_up()/_unit_state(). Transcript 3 records the mutating verbs — the module's ownrestart()(settle window and classification),stop()anduninstall()(both teardown arms) — against THROWAWAY units created for the run in the account's own user manager (a transientsystemd-run --userunit and three runtime-only unit files under$XDG_RUNTIME_DIR/systemd/user, all namedkirocrew-verif-<rand>*, all removed again by the script; the driver refuses any other unit name), never againstkirocrew.service, the pod's own unit or a host unit file.kirocrew logsagainst a live unit remains covered by the mocked tests only.Result=, which the confirmation reads, is a Service D-Bus property in systemd v219 (src/core/dbus-service.c), the oldest release the module supports — a source read, not a run; every run below is systemd 252.How the shell was obtained. The worker's sandbox shell cannot reach either bus (
kirocrew service statusthere readsnot reachable from this shell (Failed to connect to bus: Permission denied)for both scopes, exit 1);pod_upfor this PR's worktree was refused (FATAL: no python3.12 found), so transcripts 1-4 come from sessions inside an already-provisioned pod (kirocrew-pod@kirocrew-wt-autonudge-controls.service, asystemd --userunit whose child shells reach the account's manager), running this head's source throughPYTHONPATH=…/kirocrew-wt-13915/srcwith that pod's Python 3.12. Transcript 2's unit is the pod's own — a template instance whoseFragmentPathbasename (kirocrew-pod@.service) differs from the unit name, a definition the resolver never claims.Transcript 1 — inside the pod, the plain unit name: neither scope has
kirocrew.service.showon an unknown unit exits 0 withLoadState=not-foundand an emptyFragmentPath, which the parser reports asnot installed, neverinactive (dead):Transcript 2 — inside the pod, the module constant
SERVICE_NAMErepointed at the pod's own unit by a scratch driver that calls only_unit_state(),is_active()andstatus(). A running user unit readsuser scope: active (running)with itssystemctl statusblock; the same name isnot installedin the system scope;removableis False because the loaded fragment is the template file, souninstall()would reportleft in place (load state loaded, unit file /home/<user>/.config/systemd/user/kirocrew-pod@.service)and touch nothing:Redactions in every transcript: the account name reads
<user>, its uid<uid>, the host<host>; theTasks/Memory/CPU/CGroupsub-lines ofsystemctl statusblocks are cut, as is transcript 2's status journal tail (the pod gateway's own boot log, nothing about the verbs).Transcript 3 — the mutating verbs against throwaway units (round 8; a fresh session inside the same pod,
bash verif_evidence.shwritten to a log). Trimmed to the decisive lines (<v>=kirocrew-verif-<rand>):status()blocks keep theActive/Processlines; the system-scope third of everystatedump (not installedin all eight), themodule:line every driver run printed (this head'slinux.py),Result=successandexit=0echoes are cut; otherwise verbatim.What transcript 3 shows. A (transient unit):
restart()on a unit that stays up returnsok=Trueafter 2.20 s — the settle window's measured price;stop()stops it;uninstall()takes the refusal arm in the manager's own words (disable:Unit file … does not exist.),unfinished=['user'], nothing unlinked. B1 (runtime unit file): the removed arm end to end in 0.65 s, the file gone. B2 (a real203/EXECloop,Restart=always/RestartSec=10like the rendered unit):systemctl --user restartexits 0 while every read from 0.21 s on saysactivating (auto-restart) Result=exit-code;restart()says NOT UP in 0.13 s,is_active()True andis_up()False,status()showsstatus=203/EXEC. B3 (dies 0.7 s after the fork): reads at 0.001 / 0.262 / 0.523 s all sayactive (running)— a single read would have called it a success — andrestart()returns NOT UP after 0.94 s. Cleanup: everykirocrew-verif-*unit stopped and file removed,leftover files: 0.The settle window is a fixed 2 s (
_RESTART_SETTLE_SECS); a gateway that dies later than that after its fork is reported up. If that surfaces on a real host, the bound is derived from the unit's ownRestartSec(read fromsystemctl show -p RestartUSec) rather than widened — the follow-up shape, not taken here: no such death has been observed and every measured one (transcript 3) landed inside 1 s. The restart confirmation (the First Principles lane's item 6, "rides along") is declared, not deleted: without it a user-scope restart of a gateway that dies on start reads as a success (the Opus lane's round-3 block), and transcript 3 above is the measurement the item asked for (A, B2, B3). The 2 s margin is a bound, not a measured maximum; it lifts out as_confirm_upplus its twoRESTART_*kinds if a maintainer wants the confirmation shipped separately.The alias follow-up the Design lane asked a tracker for: #14190 (
CLI refusal when an alias holds the service name, deferred-finding, due 2026-10-09).Transcript 4 — the destructive verbs refusing on unverified manager answers (round 11, the Design lane's suggestion; a fresh session inside the same pod,
verif_evidence_r11.sh→ a log). Every shape is a throwawaykirocrew-verif-<rand>-*runtime unit (<v>-*below) under$XDG_RUNTIME_DIR— the unit dir$RT, the higher-priority$CTL(user.control),$OPDoutside the search path — created and removed by the script (leftover files: 0); the driver refuses any other unit name. Six shapes, headed C1-C6 below (C4's driver hasXDG_RUNTIME_DIR/DBUS_SESSION_BUS_ADDRESSpointed at places with no manager socket — explicit, sosystemctl_user_env()leaves them).showfolded to one line;status()blocks,module:lines, the system-scope half of every state dump (not installedthroughout) and theUnitPathlist cut.What transcript 4 shows. C1-C4:
restart()attempts nothing,stop()issues nothing,uninstall()refuses whole before any verb (alias / masked /not-found: stop it first/not reachable from this shell (Failed to connect to bus: No such file or directory)), and afterwards the real unit still runs with every file and link where it was; the one verb that acts isstop()on a masked ornot-foundunit that IS ours and running (C2, C3), the safe verb, which leaves the mask link for the operator. C5 shows systemd 252 reporting the RESOLVED lower-priority file asFragmentPathfor a same-name link inside the search path, and its owndisablerefusing that layout (Refusing to operate on alias name or linked unit file). C5 and C6 ran on the round-11 head (its scan classified both as linked and removed C6's link); on this head both are unmarked operator files →left untouched (not installed by Kiro Crew: …), nothing stopped — the mocked tests cover that outcome and the marked, ours-by-link one. A live re-run of the resolver on C5/C6 shapes is owed; it and the no-Idrefusal (not producible on a real systemd) stay mocked-only on this head.Screenshots / video
N/A — backend/CLI only, no UI change.
Related Issues
Fixes #13915
Pattern harvest
Rule candidate: review-prompt
Pattern: a systemd verb that spawns
systemctlwithout--userin a module that also renders a user-scope unit — every scope the module can create is a scope its status/stop/uninstall verbs must read.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)