Skip to content

fix(service): report and remove the user-scope gateway unit on Linux - #13964

Merged
bolichen97 merged 1 commit into
mainfrom
fix/service-linux-status-user-scope
Sep 27, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/service-linux-status-user-scope

Conversation

@pepmach

@pepmach pepmach commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On Linux, kirocrew service status, is_active() and uninstall() see a gateway that runs as a systemd user unit, instead of asking only the system manager and reporting it inactive (dead).

On Linux, kirocrew service status reports a running gateway as inactive (dead) when that gateway is a systemd user unit. status(), is_active() and uninstall() in src/kiro_crew/service/linux.py ask only the system manager, never systemctl --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 to systemctl --user enable --now it, and then admits that service 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 stop and kirocrew restart gate on the same is_active(), so they cannot reach the unit either; kirocrew logs opens the journal only when the system unit file exists, so the crash loop's 203/EXEC lines in the user journal are never shown; and service uninstall leaves the unit running while printing "stopped and removed". Backend/CLI only, no UI change.

Not a goal

  • The install scope: service install still writes the system unit, and preferring user units at install time stays with feat(service): prefer systemd user units #10813.
  • Any UI change: backend/CLI only.
  • Deriving the restart settle window from the unit's own 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.
  • A CLI refusal when an alias holds the service name: on a host whose only unit under our name is an alias, kirocrew stop / restart take the foreground-gateway path, tracked as #14190 (deferred-finding, due 2026-10-09).

What changed (motivation → approach → change)

Piece What it does now
src/kiro_crew/service/linux.py _systemctl(..., user=True) runs systemctl --user (never under sudo) with the environment from systemctl_user_env(). _unit_state() reads one scope with systemctl show -p Id -p LoadState -p ActiveState -p SubState -p FragmentPath -p Result, parsed as Key=value lines. status() prints system scope: … then user scope: … — not installed, not reachable from this shell (<reason>), or ActiveState (SubState) (, an alias of <Id> when the name resolves elsewhere) — and the systemctl status block 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 canonical Id show answers must be exactly kirocrew.service — an operator's Alias=kirocrew.service on their own unit, or an answer with no Id, is refused whole by uninstall, never selected by stop() / restart(), and not counted by is_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, any ActiveState but inactive / failed, so a unit crash-looping through activating (auto-restart) counts, and stop() / restart() act on each scope that does, selected by the same systemctl show (is-active answers non-zero for activating, which would let kirocrew stop issue nothing at a flapping unit); is_up() is HEALTH — active or reloading in either scope, what is-active exits 0 for — and the service status exit code follows it. restart() returns a per-scope RestartReport: systemctl restart in 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 is Type=simple and its start job succeeds the moment the process is forked — a unit seen in activating (auto-restart), failed, inactive or deactivating inside the window is a FAILED restart carrying that state and its Result (exit-code, start-limit-hit, …), activating (start) is waited for until the deadline, and only active at the deadline is ok; a non-zero systemctl restart is 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() answers controller.installed_unit_path() for the user scope: the FragmentPath of a LOADED unit whose canonical Id is ours and whose file exists, else None — fail-closed, so a blank or malformed show answer, 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=…) -> OwnedUnit
src/kiro_crew/service/common.py session_runtime_dir() and systemctl_user_env(): the one resolver for the environment a systemctl --user spawn runs with — os.environ plus XDG_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 from pod/runtime.py so 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 report restart() and controller.restart_service() return — attempted, ok (at least one scope restarted and every one up), restarted, failures; truthy exactly when ok, so if 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 and manual_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-aware kirocrew restart.
src/kiro_crew/pod/runtime.py _session_runtime_dir is the shared helper; _systemctl_env() is systemctl_user_env() plus the pod-only LC_ALL=C pin. Same mapping as before, one owner.
src/kiro_crew/service/controller.py installed_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()), so installed_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 through linux.unit_file_carries_managed_marker(), the same reading uninstall decides ownership by. service_status() exits 0 on linux.is_up() (health), not is_active() (reach). restart_service() returns the RestartReport (linux.restart()'s on Linux; on macOS one launchd outcome, a refusal carrying the bootout/bootstrap pair). manual_restart_hint() keeps its signature and answers the unconditional system_restart_command_hint() on systemd — never the circular kirocrew restart; the user-scope command reaches the operator through the report's per-scope hint, not through a parameter here. uninstall_service() prints one line per scope from the report; nothing installed anywhere prints No kirocrew service was removed. with both scope lines and exits 0; a scope in unfinished gets ⚠️ on its own line, the AppArmor profile is still removed, and the exit code is 1.
src/kiro_crew/cli_server.py kirocrew 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 status when the manager stopped answering — and NEVER falls through to the foreground spawn after an attempted restart (report.attempted is checked before the live is_service_active(), which now only covers a restart that attempted nothing): a unit that landed failed is 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: with user 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 shape service uninstall gives a teardown finished in one scope. The audit row reads outcome=partial restarted=user reason=service_restart_not_up for that case and outcome=denied reason=service_restart_denied / _not_up / _unconfirmed when nothing restarted. kirocrew logs tails 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 unprivileged journalctl -u kirocrew.service -n 1 --no-pager probe, exec unprivileged when it printed anything, the sudo journalctl rung (a TTY prompt, or the stdin is not a TTY refusal) 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-readable user-<uid>.journal are 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.py The auto-update failure handler awaits restart_command_hint() through asyncio.to_thread instead 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: a subprocess.run stand-in that answers per scope and verb (now with Result, and a restart_lands_in state or sequence a restarted scope answers afterwards), so no test touches the host's systemd; a fake clock walks restart()'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" with False now hand _restart an empty RestartReport.
docs/system-specs/modules/cli.md, docs/guides/install.md The service status / uninstall / logs / restart rows, 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 resolves restart_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 systemctl without --user never consults the second. Worse, is-active cannot tell "no unit in this scope" from "a unit that is stopped": both answer inactive, 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, whose LoadState=not-found is the one honest signal for an empty scope. A user scope the process cannot see is reported as not reachable from this shell, never as inactive, and uninstall deletes nothing there: the sudo case is decided from geteuid() and SUDO_USER before any spawn (under sudo, systemctl --user would 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 install still 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 stop it 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 read removed — so stop and disable are checked in both scopes and a refusal is reported, not acted past. And a systemctl --user spawned 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, so unreachable is a fact about the host, not the shell.

activating is "running" for one question and not for another, so the module asks two. stop and restart must reach a unit the manager is still trying to run — a crash loop lives in activating (auto-restart) — so is_active() counts it. The service status exit code answers "is the gateway up", and the crash loop is the failure that command exists to expose, so it follows is_up(): active, what is-active exits 0 for. The same distinction decides a restart: the unit is Type=simple, whose start job completes at the fork, so systemctl restart exits 0 for a gateway that dies at once. restart() re-reads the unit for two seconds and reports per scope — up, not up (state and Result), 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 (unit failed). Each kind gets its own remedy, and an attempted restart never falls through to the foreground spawn: a failed unit is still an installed, enabled definition.

Backwards compatibility

Compatible: status() still returns a string. The controller's service status exit code keeps the meaning the base gave it — 0 iff systemctl is-active would 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 through activating (auto-restart) exits 1 as it did on the base, with the headline naming that state. is_active() is true for any ActiveState but inactive / failed, so kirocrew stop / restart reach a flapping unit where the base issued nothing. uninstall() returns an UninstallReport instead of None; its only caller is controller.uninstall_service(), updated here. linux.restart() and controller.restart_service() return a RestartReport instead of a bool — truthy exactly when the restart took, so if restart_service(): keeps its meaning; the one caller (cli_server._restart) reads its attempted / failures. kirocrew restart on a systemd unit now exits 1 with the unit's real state where the base printed ✅ Restarted kirocrew service. after a systemctl restart that exited 0 into a crash loop, waits up to 2 s to confirm a restart, and no longer prints This process lacks the privileges… / sudo systemctl restart kirocrew for 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' unconditional the gateway was NOT restarted, and the audit row's outcome is partial (with restarted=<scopes>) rather than denied; 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 printed sudo systemctl restart kirocrew, which answers Unit kirocrew.service not found there); 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, so kirocrew doctor's Managed Service row and its credential check now fire for a user-scope gateway (read from the same Environment= lines the remedy bakes) where they read "no service installed"; installed_unit_path() spawns one systemctl --user show in that case, none when the system file exists. stop() / restart() keep, for a system unit, their exact sudo systemctl argv; they issue nothing for a scope whose unit is stopped, where the base issued a system-scope command regardless. uninstall refuses what the base tore down blindly: a loaded unit whose stop or disable the manager refuses, or that is still running after stop returned 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 uninstall on a host without sudo prints both scope lines and exits 1 instead of the base's single ❌ error, and removes the user unit on the way. Round 10: UninstallReport gains removed and removed_any reads it, not a line prefix (the fileless-stopped system unit headlines ✅ … stopped and removed.); a system-scope refusal with no file at UNIT_PATH and 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 followed FragmentPath to it. Round 12: uninstall acts only on units it owns — the installer's file, or one carrying the KIROCREW_SERVICE_MANAGED=1 marker line. A vendor unit loaded under our name with no file of ours (rounds 9-11 stopped and daemon-reloaded it, headline stopped and removed) and an operator's own unit linked under our name (rounds 10-11 removed its link) now read left untouched with 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 mask writes its /dev/null symlink 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) is left 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. The UnitPath query 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 → the sudo journalctl rung 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.run mocked per scope and verb): system unit absent + user unit active → system scope: not installed, user scope: active (running), no inactive (dead), is_active() True, no sudo; both absent → both not installed; user bus unreachable (Failed to connect to bus: No medium found) → user scope: not reachable from this shell with the diagnostic, system line intact; system active → its systemctl status block kept plus the user line; the reporter's layout (system loaded but stopped, user running) → system scope: inactive (dead) beside user scope: active (running); root with SUDO_USER → user scope unreachable and no --user spawn; every --user spawn carries the backfilled bus pointers (systemctl_user_env()) while the system-scope spawn keeps the inherited environment, and pod.runtime._systemctl_env() is the shared mapping plus LC_ALL=C; stop() / restart() reach a user-only unit through --user without 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-scope stop (RefuseManualStop wording) → the unit file still exists, no disable, no daemon-reload, os.unlink never 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-scope disableafter a successful stop → file kept,unfinished == {"user"}; a refused system-scope stop→ norm, no disable, 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-scope rm -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 no sudo on the host (shutil.which→ None,sys.platformpinned to linux) → nosudospawn at all,⚠️ system scope: left in place (privilege unavailable: … 'sudo' was not found …), 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 (every systemctlanswersSystem has not been booted with systemd as init system (PID 1)…, /run/systemd/systemabsent) → nostop/disable, rm -fissued,removed (…), user scope not reachablewith that diagnostic, nothing unfinished; the same unreachable manager on a host where/run/systemd/system exists (Failed to connect to bus: Permission denied) → no rm, left in place (the system manager is not reachable from this shell: …), unfinished == {"system"}; a system unit file the manager answers LoadState=not-foundfor (astopwould exit 5, not loaded) → nostop/disable, rm -f+daemon-reload, removed (…); a RUNNING unit whose load state is masked, in either scope → no stop, 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 unit not-foundyetactive→ refusedstop it first, not not installed; an alias in the SYSTEM scope → no verb, left in place (kirocrew.service is an alias of shared.service; manage that unit); a stopthat 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 exactly show, stop, disable, show, daemon-reload; a unit in activating (auto-restart)→is_active()True,user_unit_active()True,stop()issuessystemctl --user stop, no is-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".
  • Red-first: with the production files restored to the base of the time (4926e50b3c) and only the tests kept, test/test_service.py is 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, on 011b9fa475: the four fileless system-scope cases all read not installed with no stop issued, and user_unit_path() took a blank LoadState / Id answer 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.
  • Round-13 cases, TestLinuxServiceScopes: test_a_persistent_mask_of_our_name_is_removed_in_the_system_scope (both loader readings of FragmentPath, the mask entry and /dev/null) → sudo rm -f <mask> + daemon-reload, no stop / 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_mask pins 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 on 47e51b3527: the three positive cases fail with left in place (load state masked, unit file …) — the Opus reading, verbatim.
  • Round-12 cases, TestLinuxServiceScopes (the fake reports the module's UNIT_PATH as the system fragment and user_unit_file_path is pinned under tmp_path; a test's own unit files carry the marker, an operator's or vendor's do not): a vendor kirocrew.service (a /usr/lib stand-in) loaded and RUNNING with nothing at UNIT_PATH → left untouched (not installed by Kiro Crew: …), sudo systemctl stop NOT issued, no verb at all, removed == unfinished == {}, controller exit 0 with No kirocrew service was removed. (test_a_vendor_unit_with_no_unit_file_of_ours_is_left_untouched_not_stopped); an operator's unit systemctl --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 with disable refused → 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", …) and os.unlink reachable only from functions whose first parameter is an OwnedUnit (the installer's temp-file cleanups aside), and with _owned_unit patched to None, uninstall() issues no verb in either scope across running / stopped / one-scope layouts. Red-first on ae04ae9172: 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.
  • Round-10 cases, TestLinuxServiceScopes: a link entry os.unlink cannot 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 is show, stop, disable, show, daemon-reload; removed_any is the removed set, not a prefix; a system-scope inactive alias with no file at UNIT_PATH finishes the scope (exit 0) while the same alias running, or with the file present, stays unfinished.
  • Round-9 cases: with no unit file uninstall() asks the system manager (unprivileged show) before answering not installed; a LOADED, running unit of ours whose file is gone gets stop + daemon-reload, no disable, no rm, stopped (… already gone …); the same unit left not-found by a daemon-reload is refused whole; a runtime mask with no file is left in place (load state masked, …); an unreachable manager reads not reachable only where /run/systemd/system exists; user_unit_path() answers only for loaded + Id=kirocrew.service. restart_command_hint()'s call-time import carries the # circular import note.
  • Round-7 cases: test_slack_gateway.py::…::test_failure_path_resolves_the_restart_hint_off_the_event_loop — the hint double blocks on a threading.Event only 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 restarted absent, audit outcome=partial; TestControllerDispatch::…mixed_report… — restarted / failures partition the outcomes.
  • Identity, teardown, hint and platform cases: an alias in either scope (Id=shared.service) → is_active() / is_up() False, stop() and restart() issue nothing, headline active (running), an alias of shared.service; an answer with NO Id → not acted on, left in place (the manager did not report kirocrew.service's canonical Id, …), unfinished; a manager that vanishes after stop → left in place (the user manager stopped answering after …), no unlink; the report hint does not depend on the host running the module (UNSUPPORTED / LAUNCHD pinned — 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. TestLogsCmdSystemd is the base's contract again: rows → unprivileged exec; an EMPTY probe → the sudo journalctl rung on a TTY (the base pin restored verbatim) and the stdin is not a TTY refusal without one; rows WITH the access hint → still the exec.
  • Restart, health and doctor cases, TestLinuxServiceScopes / TestControllerDispatch / TestInstalledUnitPath / TestManagedServiceMarkerDetection (fake clock, no wall time): a user-only unit whose systemctl --user restart exits 0 and then reads activating (auto-restart) with Result=exit-code → ok False, kind not-up, the reason names the state and last result: exit-code, the hint is journalctl --user -u kirocrew.service -n 50 --no-pager, is_active() still True and is_up() False; a first active reading followed by auto-restart inside the window → failure (the window is walked, one reading is not confirmation); activating (start) twice then active → ok; still activating (start) at the deadline → still activating (start) … 2s after the restart, the whole window walked; active at every poll → ok with the window walked; failed with Result=start-limit-hit → not-up with sudo journalctl -u kirocrew.service -n 50 --no-pager; the bus going away mid-window → kind unconfirmed, hint kirocrew service status, no "exits" claim; a non-zero systemctl restart with the unit still active afterwards → refused, sudo systemctl restart kirocrew; a non-zero exit (Job for kirocrew.service failed …) with the unit failed (start-limit-hit) afterwards → not-up, the journal, never "refused"; both scopes running and both refused → two refusals with sudo systemctl restart kirocrew and systemctl --user restart kirocrew respectively; is_active() / is_up() over active, 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 while is_active() is True and the headline reads user scope: activating (auto-restart); installed_unit_path(): a system file answers with no spawn; absent → one systemctl --user show, no sudo; a loaded (even stopped) user unit → its FragmentPath; not-found, a mask (/dev/null), an alias, an unreachable user scope, and a fragment the operator deleted → None; installed_service_has_managed_marker() reads False then True off 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, audit service_restart_denied; a user unit not up → Read why it exits: journalctl --user -u kirocrew.service …, no sudo, audit service_restart_not_up; an attempted restart whose unit reads failed → exit 1, is_service_active never 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 a None uninstall return drive the same fake (system unit active) or a real UninstallReport, asserting the same sudo systemctl stop|restart argv; 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 of journalctl --user --no-pager -u kirocrew.service -n 42 -f after exactly one journalctl --user --quiet … -n 1 probe, 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_file admits the one systemctl --user show query (answering not-found) and still forbids any journal probe.
  • Green with -n0 on 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, TestSessionBus included). Black ratchet, black --check on the non-baselined files, isort, flake8, mypy on the changed files, check_subprocess_encoding.py, check_comment_history.py and docs-lint.sh pass. test/e2e/scenarios/test_service_install_dry_run.py needs the pod fixture and was not run here; it drives render_unit, which this diff does not touch. Rebased onto main 4d683462c2 after fix(ci): stop platformdirs' pytest11 plugin killing Windows pytest lanes #14268 merged (a pure replay, like the earlier rebase onto 7b2da39c53 after 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. The Backend Tests (Windows) (5) reds of 88b3d04bd8 (a UnitPath filter dropping C:\…) cannot recur: the query is gone. The Backend Tests (Windows) (1) red is test/test_history_index_worker.py::test_a_contended_write_waits_instead_of_failing, #13215 (the test asserts elapsed >= hold literally), not this change. The Backend Tests (Windows) (7) red on 47e51b3527 is test/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) and Await Fast Gate red (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.
  • One local GPT review lane (read-only) read rounds 4-6's deltas before their push; every Critical/High and Medium it raised was fixed with the tests above but one, recorded: on a host whose ONLY unit under our name is an alias, kirocrew stop / restart take 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's src/kiro_crew/service/linux.py. Transcripts 1-2 use read-only verbs only — show, list-units, is-active, status, and the module's status() / is_active() / is_up() / _unit_state(). Transcript 3 records the mutating verbs — the module's own restart() (settle window and classification), stop() and uninstall() (both teardown arms) — against THROWAWAY units created for the run in the account's own user manager (a transient systemd-run --user unit and three runtime-only unit files under $XDG_RUNTIME_DIR/systemd/user, all named kirocrew-verif-<rand>*, all removed again by the script; the driver refuses any other unit name), never against kirocrew.service, the pod's own unit or a host unit file. kirocrew logs against 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 status there reads not reachable from this shell (Failed to connect to bus: Permission denied) for both scopes, exit 1); pod_up for 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, a systemd --user unit whose child shells reach the account's manager), running this head's source through PYTHONPATH=…/kirocrew-wt-13915/src with that pod's Python 3.12. Transcript 2's unit is the pod's own — a template instance whose FragmentPath basename (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. show on an unknown unit exits 0 with LoadState=not-found and an empty FragmentPath, which the parser reports as not installed, never inactive (dead):

== shell identity: uid=<uid>, XDG_RUNTIME_DIR=/run/user/<uid>, DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/<uid>/bus, systemd 252 (252.23-12.amzn2023); `systemctl --user list-units 'kirocrew-pod*' --all` listed the account's three pod units (cut) ==
== systemctl --user show kirocrew.service -p Id,FragmentPath,LoadState,ActiveState,SubState ==
Id=kirocrew.service
LoadState=not-found
ActiveState=inactive
SubState=dead
FragmentPath=
exit=0
== kirocrew service status (PR head code via PYTHONPATH=/workplace/<user>/KiroCrew/kirocrew-wt-13915/src) ==
system scope: not installed

user scope: not installed
exit=1

Transcript 2 — inside the pod, the module constant SERVICE_NAME repointed at the pod's own unit by a scratch driver that calls only _unit_state(), is_active() and status(). A running user unit reads user scope: active (running) with its systemctl status block; the same name is not installed in the system scope; removable is False because the loaded fragment is the template file, so uninstall() would report left in place (load state loaded, unit file /home/<user>/.config/systemd/user/kirocrew-pod@.service) and touch nothing:

== systemctl --user show kirocrew-pod@kirocrew-wt-autonudge-controls.service -p Id,FragmentPath,LoadState,ActiveState,SubState ==
Id=kirocrew-pod@kirocrew-wt-autonudge-controls.service
LoadState=loaded
ActiveState=active
SubState=running
FragmentPath=/home/<user>/.config/systemd/user/kirocrew-pod@.service
exit=0
== systemctl --user is-active kirocrew-pod@kirocrew-wt-autonudge-controls.service ==
active
exit=0
== driver: PR head service module, SERVICE_NAME repointed at the pod unit ==
module: /workplace/<user>/KiroCrew/kirocrew-wt-13915/src/kiro_crew/service/linux.py
[plain unit name: both scopes `not installed`, `is_active(): False` — as transcript 1]
--- SERVICE_NAME repointed at the pod's own unit: SERVICE_NAME='kirocrew-pod@kirocrew-wt-autonudge-controls' ---
_unit_state(user=True): scope=user load='loaded' active='active' sub='running' unit_id='kirocrew-pod@kirocrew-wt-autonudge-controls.service' fragment='/home/<user>/.config/systemd/user/kirocrew-pod@.service' error=''
  headline: user scope: active (running)
is_active(): True
status():
  | system scope: not installed
  | 
  | user scope: active (running)
  | [the `systemctl status` block for kirocrew-pod@kirocrew-wt-autonudge-controls.service: Loaded: loaded (…/kirocrew-pod@.service; disabled), a Drop-In dir, Active: active (running) since 28 min, Main PID (kirocrew); then the pod gateway's own journal lines (~2 KB each, host name on every line) — cut]
exit=0

Redactions in every transcript: the account name reads <user>, its uid <uid>, the host <host>; the Tasks / Memory / CPU / CGroup sub-lines of systemctl status blocks 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.sh written to a log). Trimmed to the decisive lines (<v> = kirocrew-verif-<rand>): status() blocks keep the Active / Process lines; the system-scope third of every state dump (not installed in all eight), the module: line every driver run printed (this head's linux.py), Result=success and exit=0 echoes are cut; otherwise verbatim.

== shell identity: uid=<uid>, XDG_RUNTIME_DIR=/run/user/<uid>, systemd 252 (252.23-12.amzn2023), runtime unit dir /run/user/<uid>/systemd/user; kirocrew-verif-* leftovers from an earlier run swept first (0 files after the sweep) ==


######## PHASE A: transient unit via systemd-run (the conductor's route) ########
== systemd-run --user --unit <v> sleep infinity ==
Running as unit: <v>.service
== systemctl --user show <v>.service -p Id,LoadState,ActiveState,SubState,FragmentPath,Result ==
Id=<v>.service
LoadState=loaded
ActiveState=active
SubState=running
FragmentPath=/run/user/<uid>/systemd/transient/<v>.service
== driver: state, restart (settle window on a unit that stays up), state ==
_unit_state(user=True): load='loaded' active='active' sub='running' result='success' fragment='/run/user/<uid>/systemd/transient/<v>.service'; installed=True running=True up=True removable=True
--- restart() SERVICE_NAME='<v>' settle=2.0s poll=0.25s ---
restart() returned after 2.20s: ok=True attempted=True
  ScopeRestart(scope='user', ok=True, kind='', hint='')
  restarted=['user'] failures=[]
[state after restart(): unchanged — active (running)]
== driver: stop, then state (a stopped transient unit is collected by the manager) ==
--- stop() SERVICE_NAME='<v>' ---
stop() returned after 0.02s (best-effort verb, no report)
_unit_state(user=True): load='not-found' active='inactive' sub='dead' result='success' fragment=''; installed=False running=False up=False removable=False
== systemctl --user show <v>.service (after stop) ==
Id=<v>.service
LoadState=not-found
ActiveState=inactive
SubState=dead
FragmentPath=
== fresh transient unit, then driver: uninstall (a transient unit has no unit file to disable) ==
Running as unit: <v>.service
--- uninstall() SERVICE_NAME='<v>' ---
uninstall() returned after 0.02s
  system: not installed
  user:   left in place (`systemctl --user disable <v>.service` failed: Failed to disable unit: Unit file <v>.service does not exist.; the unit file was not removed)
  unfinished=['user'] incomplete=True removed_any=False
[state after uninstall(): not-found, both scopes `not installed`]

######## PHASE B: runtime-only unit files under /run/user/<uid>/systemd/user (tmpfs, removed below) ########
== B1: <v>-file (sleep infinity): driver state, uninstall, state ==
Id=<v>-file.service
LoadState=loaded
ActiveState=active
SubState=running
FragmentPath=/run/user/<uid>/systemd/user/<v>-file.service
_unit_state(user=True): load='loaded' active='active' sub='running' result='success' fragment='/run/user/<uid>/systemd/user/<v>-file.service'; installed=True running=True up=True removable=True
--- uninstall() SERVICE_NAME='<v>-file' ---
uninstall() returned after 0.65s
  system: not installed
  user:   removed (/run/user/<uid>/systemd/user/<v>-file.service)
  unfinished=[] incomplete=False removed_any=True
[state after uninstall(): load='not-found', both scopes `not installed`, is_active()=False is_up()=False]
unit file after uninstall: ls: cannot access '/run/user/<uid>/systemd/user/<v>-file.service': No such file or directory
== B2: <v>-exec (203/EXEC loop): show, then driver restart ==
Result=exit-code
NRestarts=0
ExecMainCode=1
ExecMainStatus=203
Id=<v>-exec.service
LoadState=loaded
ActiveState=activating
SubState=auto-restart
FragmentPath=/run/user/<uid>/systemd/user/<v>-exec.service
-- systemctl --user restart + immediate reads --
0.210s: Result=exit-code ExecMainStatus=203 ActiveState=activating SubState=auto-restart 
0.471s: Result=exit-code ExecMainStatus=203 ActiveState=activating SubState=auto-restart 
0.732s: Result=exit-code ExecMainStatus=203 ActiveState=activating SubState=auto-restart 
0.993s: Result=exit-code ExecMainStatus=203 ActiveState=activating SubState=auto-restart 
--- restart() SERVICE_NAME='<v>-exec' settle=2.0s poll=0.25s ---
restart() returned after 0.13s: ok=False attempted=True
  ScopeRestart(scope='user', ok=False, kind='not-up', hint='journalctl --user -u <v>-exec.service -n 50 --no-pager')
    reason: <v>-exec.service is activating (auto-restart) (last result: exit-code) after the restart — the gateway exits as soon as it starts
  restarted=[] failures=['user']
[state after restart(): activating (auto-restart), result exit-code; is_active()=True is_up()=False]
  |     Process: 143001 ExecStart=/nonexistent/kirocrew-verif-binary (code=exited, status=203/EXEC)
== B3: <v>-late (dies 0.7 s after the fork): timing reads, then driver restart ==
0.001s: Result=success ExecMainStatus=0 ActiveState=active SubState=running 
0.262s: Result=success ExecMainStatus=0 ActiveState=active SubState=running 
0.523s: Result=success ExecMainStatus=0 ActiveState=active SubState=running 
0.787s: Result=exit-code ExecMainStatus=1 ActiveState=activating SubState=auto-restart 
1.051s: Result=exit-code ExecMainStatus=1 ActiveState=activating SubState=auto-restart 
1.313s: Result=exit-code ExecMainStatus=1 ActiveState=activating SubState=auto-restart 
--- restart() SERVICE_NAME='<v>-late' settle=2.0s poll=0.25s ---
restart() returned after 0.94s: ok=False attempted=True
  ScopeRestart(scope='user', ok=False, kind='not-up', hint='journalctl --user -u <v>-late.service -n 50 --no-pager')
    reason: <v>-late.service is activating (auto-restart) (last result: exit-code) after the restart — the gateway exits as soon as it starts
  restarted=[] failures=['user']
[state after restart(): activating (auto-restart), result exit-code; is_active()=True is_up()=False]
  |     Process: 143100 ExecStart=/bin/sh -c sleep 0.7; exit 1 (code=exited, status=1/FAILURE)

== journal of the throwaway units (unit names only; --user -o cat) ==
[Stopped …-exec.service (203/EXEC crash loop); then for the -late unit, per restart: Started … / "Main process exited, code=exited, status=1/FAILURE" / "Failed with result 'exit-code'." / Stopped … — three rounds, cut]
== cleanup (every <v>* unit stopped, files removed, daemon-reload, reset-failed) ==
leftover files: 0

What transcript 3 shows. A (transient unit): restart() on a unit that stays up returns ok=True after 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 real 203/EXEC loop, Restart=always / RestartSec=10 like the rendered unit): systemctl --user restart exits 0 while every read from 0.21 s on says activating (auto-restart) Result=exit-code; restart() says NOT UP in 0.13 s, is_active() True and is_up() False, status() shows status=203/EXEC. B3 (dies 0.7 s after the fork): reads at 0.001 / 0.262 / 0.523 s all say active (running) — a single read would have called it a success — and restart() returns NOT UP after 0.94 s. Cleanup: every kirocrew-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 own RestartSec (read from systemctl 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_up plus its two RESTART_* 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 throwaway kirocrew-verif-<rand>-* runtime unit (<v>-* below) under $XDG_RUNTIME_DIR — the unit dir $RT, the higher-priority $CTL (user.control), $OPD outside 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 has XDG_RUNTIME_DIR / DBUS_SESSION_BUS_ADDRESS pointed at places with no manager socket — explicit, so systemctl_user_env() leaves them). show folded to one line; status() blocks, module: lines, the system-scope half of every state dump (not installed throughout) and the UnitPath list cut.

== inside the pod ($RT=/run/user/<uid>/systemd/user, $CTL=$RT.control, $OPD=/run/user/<uid>/kirocrew-verif-operator) ==
systemd 252 (252.23-12.amzn2023)

## C1: an ALIAS holds the name (<v>-alias -> <v>-real)
show: Id=<v>-real.service LoadState=loaded ActiveState=active FragmentPath=$RT/<v>-real.service
restart() -> 0.01s: ok=False attempted=False
stop() -> 0.01s
uninstall() -> 0.01s
  system: not installed
  user:   left in place (<v>-alias.service is an alias of <v>-real.service; manage that unit)
  unfinished=['user'] removed=[] incomplete=True removed_any=False
== after ==
show: Id=<v>-real.service LoadState=loaded ActiveState=active FragmentPath=$RT/<v>-real.service
  ls: $RT/<v>-alias.service -> <v>-real.service
  ls: $RT/<v>-real.service

## C2: a RUNTIME MASK while the unit runs (<v>-mask)
show: Id=<v>-mask.service LoadState=masked ActiveState=active FragmentPath=$RT/<v>-mask.service
uninstall() -> 0.01s
  system: not installed
  user:   left in place (an active unit whose load state is masked: unmask and stop it first, then run `kirocrew service uninstall` again)
  unfinished=['user'] removed=[] incomplete=True removed_any=False
== after ==
show: Id=<v>-mask.service LoadState=masked ActiveState=active FragmentPath=$RT/<v>-mask.service
  ls: $RT/<v>-mask.service -> /dev/null
stop() -> 0.02s
_unit_state(user=True): load='masked' active='inactive' (stopped; the mask link is left for the operator)

## C3: NOT-FOUND while the unit runs (<v>-gone: file removed under it + daemon-reload)
show: Id=<v>-gone.service LoadState=not-found ActiveState=active FragmentPath=
uninstall() -> 0.01s
  system: not installed
  user:   left in place (an active unit whose load state is not-found: stop it first, then run `kirocrew service uninstall` again)
  unfinished=['user'] removed=[] incomplete=True removed_any=False
stop() -> 0.02s
after the stop, show: Id=<v>-gone.service LoadState=not-found ActiveState=inactive FragmentPath=

## C4: UNREACHABLE user manager (<v>-bus running; the driver sees no manager socket)
show: Id=<v>-bus.service LoadState=loaded ActiveState=active FragmentPath=$RT/<v>-bus.service
_unit_state(user=True): load=None active='' unit_id='' fragment='' error='Failed to connect to bus: No such file or directory'
restart() -> 0.01s: ok=False attempted=False
stop() -> 0.01s
uninstall() -> 0.01s
  system: not installed
  user:   not reachable from this shell (Failed to connect to bus: No such file or directory)
  unfinished=[] removed=[] incomplete=False removed_any=False
== after (from a shell that reaches the manager) ==
show: Id=<v>-bus.service LoadState=loaded ActiveState=active FragmentPath=$RT/<v>-bus.service
  ls: $RT/<v>-bus.service

## C5: the GPT layout -- HIGHER-priority link $CTL/<v>-hi.service -> LOWER-priority direct file $RT/<v>-hi.service
show: Id=<v>-hi.service LoadState=loaded ActiveState=active FragmentPath=$RT/<v>-hi.service
  ls: $CTL/<v>-hi.service -> $RT/<v>-hi.service
  ls: $RT/<v>-hi.service
_user_unit_search_path() -> the manager's 16 UnitPath directories (cut)
_user_unit_removal(fragment='$RT/<v>-hi.service') -> unit_file=None links=['$CTL/<v>-hi.service']
uninstall() -> 0.03s
  system: not installed
  user:   left in place (`systemctl --user disable <v>-hi.service` failed: Failed to disable unit: Refusing to operate on alias name or linked unit file: <v>-hi.service; the unit file was not removed)
  unfinished=['user'] removed=[] incomplete=True removed_any=False
== after ==
  ls: $CTL/<v>-hi.service -> $RT/<v>-hi.service
  ls: $RT/<v>-hi.service
file content intact: 1 line(s)
show: Id=<v>-hi.service LoadState=loaded ActiveState=inactive FragmentPath=$RT/<v>-hi.service

## C6: link in a search dir $RT/<v>-ext.service -> an operator's file OUTSIDE the search path ($OPD/<v>-ext.service)
show: Id=<v>-ext.service LoadState=loaded ActiveState=active FragmentPath=$RT/<v>-ext.service
_user_unit_removal(fragment='$RT/<v>-ext.service') -> unit_file=None links=['$RT/<v>-ext.service']
  user:   removed (the link to $OPD/<v>-ext.service; the linked unit file $OPD/<v>-ext.service itself was kept)
  ls: $OPD/<v>-ext.service
file content intact: 1 line(s)
== cleanup (every kirocrew-verif-<rand>* unit stopped, links/files removed, daemon-reload, reset-failed) ==
leftover files: 0
Sat Sep 26 19:52:11 UTC 2026

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 is stop() on a masked or not-found unit 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 as FragmentPath for a same-name link inside the search path, and its own disable refusing 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-Id refusal (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 systemctl without --user in 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@pepmach
pepmach requested review from a team and dwu96 September 25, 2026 20:08
@pepmach

pepmach commented Sep 25, 2026

Copy link
Copy Markdown
Contributor Author

Intent, for the review lanes and the maintainers: on Linux, kirocrew service status, is_active, stop/restart, service uninstall and kirocrew logs asked only the system systemd manager, so the per-user unit the installer's own SELinux remedy stands up was reported as inactive (dead) and could not be stopped, removed or tailed (#13915). Every scope-reading verb now asks both managers and names the scope it reports on; the install scope is unchanged (system; preferring user units at install time stays with #10813). The user-scope teardown acts only on a loaded unit whose canonical Id is kirocrew.service in a file named after it — an alias, a mask or an unparseable unit is reported left in place and never stopped, disabled or deleted. Backend/CLI only, no UI change; every systemd interaction in the tests is mocked (the systemd user manager is host state).

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of 6067a763bbcf0ad58092ff645420ff94e72f74b1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The ownership resolver that gates uninstall's file deletion is mocked-only on this head; the owed live C5/C6 re-run hasn't happened.

Watch

_owned_unit (marker/link classification) is new in rounds 12-13 and decides what uninstall deletes on an operator's host, but transcript 4's link layouts ran on the round-11 head — the description concedes "a live re-run of the resolver on C5/C6 shapes is owed," so a real-systemd FragmentPath shape the fake doesn't reproduce would be caught only in the field. Failure direction is fail-closed by construction, which is why this is not a blocker.
Clears when: transcript 4's C5/C6 (and the round-13 persistent-mask arms) re-run against this head's resolver, or an issue tracks that run like #14190 tracks the alias gap.

Suggestions

The fixed 2 s _RESTART_SETTLE_SECS follow-up (derive from RestartUSec) deserves the same tracker treatment as #14190, so the "if that surfaces" promise survives the PR description.

[DESIGN-REVIEWED] 6067a76

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 6067a763bbcf0ad58092ff645420ff94e72f74b1 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 ships

Inventory (10 items) — 10 justified

Intent: make kirocrew's service verbs see, manage and remove the per-user systemd unit the SELinux remedy stands up, instead of reporting a running gateway as dead — a FIX (provenance: the base install.md's own admission, tracked as #7165).

  1. service status names both scopes; a running user unit no longer reads inactive (dead) — justified
  2. service status exit code follows health, so a crash-looping unit exits 1 — justified
  3. kirocrew stop/restart reach a user-scope or crash-looping unit via the manager's show answer — justified
  4. kirocrew restart confirms the unit stays up (2 s settle) and reports per-scope failures with remedies and new audit kinds — justified
  5. kirocrew logs tails the user journal when the user unit runs or is the only one — justified
  6. service uninstall tears down both scopes behind one fail-closed ownership decision (marker, alias/mask/link refusals), per-scope report, exit 1 when unfinished — justified
  7. kirocrew doctor treats a loaded user unit as the installed service definition — justified
  8. Restart hints (update path, Slack, install warning) pick the scope by two file stats, else defer to kirocrew restart — justified
  9. Slack's update-failure hint resolves off the event loop (new home-dir stat can block on a network mount) — justified
  10. Pod runtime's systemctl --user env resolver moved to service/common and shared with the new user-scope verbs — justified

[FIRST-PRINCIPLES-REVIEWED] 6067a76

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 6067a763bbcf0ad58092ff645420ff94e72f74b1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6067a76

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6067a763bbcf0ad58092ff645420ff94e72f74b1: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 6067a763bbcf0ad58092ff645420ff94e72f74b1 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6067a76

Verdict parsed from the review's SHA-scoped output markers for commit 6067a763bbcf0ad58092ff645420ff94e72f74b1.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 6067a763bbcf0ad58092ff645420ff94e72f74b1: <one-sentence reason>

@pepmach
pepmach force-pushed the fix/service-linux-status-user-scope branch from 8dc5a7e to b34d750 Compare September 25, 2026 21:42
@pepmach

pepmach commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _stop_and_disable() checks stop then disable per scope; the unit file is deleted only when both took; UninstallReport.unfinished names the scopes whose attempted teardown did not finish

  • Failed teardown still deletes the user unit (span=6b3286a41273) — fixed in b34d750

Real: on 8dc5a7e both _systemctl("stop"/"disable", user=True) results were discarded before os.unlink(state.fragment), so a stop the manager refused (RefuseManualStop=yes, a bus gone mid-run) left a running gateway with no unit file and a report reading removed.
Fix, red-first: _stop_and_disable(user=...) runs stop then disable and returns the left in place (`… stop kirocrew.service` failed: <first diagnostic line>; the unit file was not removed) line on the first non-zero exit; uninstall() returns that line on the scope, unlinks nothing, and the controller marks that scope ⚠️ and exits 1.
Every branch of the teardown chain, both scopes: system stop refused -> no disable, no rm -f, exit 1; system disable refused -> no rm -f, exit 1; system rm -f non-zero -> stopped and disabled, but its unit file … could not be removed (…), exit 1 (the base claimed removed); user stop refused -> no disable, no unlink, no daemon-reload, exit 1; user disable refused -> no unlink, exit 1; user unlink OSError -> reported, exit 1 (unchanged); alias / mask / foreign fragment -> left in place, nothing issued, exit 0 (unchanged, a refusal not an attempt); unreachable user scope -> untouched (unchanged).
The system scope is the sibling branch of the same class (the adjudication named it: the base discarded the same results and rm -f'd the path), so it takes the same check rather than waiting for the next round.
Tests: test_a_refused_user_stop_leaves_the_unit_file_in_place_and_exits_1, test_a_refused_user_disable_after_a_successful_stop_still_keeps_the_file, test_a_refused_system_stop_leaves_the_system_unit_and_still_reports_the_user_scope, test_a_system_unit_file_rm_that_does_not_take_is_reported_not_claimed_removed — all four fail on the 8dc5a7e sources (the unit file of a unit that did not stop was deleted; ['sudo', 'rm', '-f', …] issued after the refused stop) and pass on b34d750.

@pepmach

pepmach commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: service.common.systemctl_user_env() / session_runtime_dir() — the pod runtime's env backfill moved to the shared module; both systemctl --user spawn sites resolve their environment there

  • Item 9 — duplicate of src/kiro_crew/pod/runtime.py (user-scope runner without the bus-pointer backfill) (span=69e8114662e4) — fixed in b34d750

Accepted: _systemctl(user=True) spawned with the inherited environment, so from a shell descended from the gateway's system unit it would read "Failed to connect to bus: No medium found" as not reachable while pod/runtime.py's _systemctl_env() cured exactly that.
Subtraction taken at the level where the two spellings actually diverged: _session_runtime_dir() and the backfill body moved out of pod/runtime.py into kiro_crew.service.common (session_runtime_dir(), systemctl_user_env()); pod/runtime.py binds _session_runtime_dir to the shared function and its _systemctl_env() is the shared mapping plus the pod-only LC_ALL=C pin (same mapping as before, one owner); service/linux.py's user-scope spawn runs with env=systemctl_user_env().
Not routed through pod.runtime.systemctl() itself: that runner raises PodError with pod wording when the bus is absent, resolves the binary through trusted_system_bin, and applies a 15 s timeout that raises — the service verbs report an unreachable scope as data and never raise, so sharing the runner would have changed their contract; sharing the resolver is where the divergence lived.
Test: test_the_user_scope_spawn_carries_the_shared_backfilled_bus_env — every --user spawn carries XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS=unix:path=<runtime dir>/bus when that socket exists while the system-scope spawn keeps the inherited env, and pod_runtime._systemctl_env() == {**systemctl_user_env(), "LC_ALL": "C"}; red on the 8dc5a7e sources (env is None), green on b34d750, and test_pod.py::TestSessionBus is unchanged and green.

@pepmach

pepmach commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Unverified real-systemd semantics behind the new scope-aware verbs (span=36f68e4e0e30) — fixed in b34d750

The body's Manual verification section no longer says N/A: it carries three transcripts on real systemd (systemd 252 (252.23-12.amzn2023)) running this head's service/linux.py, captured from a shell inside a systemd --user unit (a pod) because the worker's own sandbox shell cannot reach either bus.
Transcript 1 (plain unit name, neither scope installed): systemctl --user show kirocrew.service -p Id,FragmentPath,LoadState,ActiveState,SubState exits 0 with LoadState=not-found and an empty FragmentPath, and kirocrew service status prints system scope: not installed / user scope: not installed, exit 1 — the not-found assumption the parser rests on holds on 252.
Transcript 2 (SERVICE_NAME repointed at the pod's own running user unit, a template instance): show answers LoadState=loaded ActiveState=active SubState=running FragmentPath=/home/<user>/.config/systemd/user/kirocrew-pod@.service; the module reads user scope: active (running) with the systemctl status block, is_active() True, the same name not installed in the system scope, and removable=False because the fragment basename is the template file — the alias/mask/foreign-fragment guard's left in place arm exercised against a real unit.
Transcript 0 (the sandbox shell): both scopes not reachable from this shell (Failed to connect to bus: Permission denied) — the unreachable arm (non-zero exit, diagnostic on stderr, no LoadState line) on real systemctl.
Not transcribed: stop / restart / disable / uninstall / logs against a live unit — mutating verbs were deliberately not run against this host's user manager from an agent shell; those paths remain covered by the mocked tests (including the checked-teardown cases this head adds). pod_up of this PR's own worktree was refused (FATAL: no python3.12 found (need it to build the venv)), quoted in the body; an already-provisioned worktree's pod supplied the unit.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
@pepmach
pepmach force-pushed the fix/service-linux-status-user-scope branch from b34d750 to f0c1687 Compare September 25, 2026 22:43
@pepmach

pepmach commented Sep 25, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _teardown_system_scope() — the system-scope teardown as one helper returning (line, finished); _require_privilege() is caught there and reported on the system line

  • _require_privilege() aborts before removing a reachable user unit when a stale system unit exists but sudo is unavailable (span=95458d4eeff1) — fixed in f0c1687

Real: on b34d750 uninstall() called _require_privilege() unguarded once UNIT_PATH existed, so on a host without sudo the ServiceInstallError escaped to the controller's ❌ path before the user scope was reached — the SELinux remedy's own layout (stale system file, running user unit) could not be torn down at all from that host.
Fix: _teardown_system_scope() catches the error and returns left in place (privilege unavailable: <message>) with the scope unfinished; uninstall() continues into the user scope, which is stopped, disabled and unlinked; the controller prints ⚠️ system scope: … and exits 1.
Test test_no_sudo_reports_the_system_unit_and_still_removes_the_user_unit (shutil.which → None, sys.platform pinned to linux): no sudo spawn, user unit file gone, ⚠️ system scope: left in place (privilege unavailable: … 'sudo' was not found …), exit 1 — red on the b34d750 sources (the reachable user unit was not removed), green on f0c1687.

@pepmach

pepmach commented Sep 25, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: both kirocrew logs journal probes carry --quiet

  • "-- No entries --" satisfies probe.stdout.strip(), so an empty user journal suppresses fallback logs (span=470edb982285) — fixed in f0c1687

Real, and measured on this host (systemd 252): journalctl --user -u kirocrew.service -n 1 --no-pager and the system form both exit 0 and print -- No entries -- on STDOUT for an empty journal (the system form adds the group hint on stderr); with --quiet both print nothing.
Fix: the user-scope probe is journalctl --user --quiet -u <unit> -n 1 --no-pager, so an empty user journal falls through to the system journal / log file instead of exec-ing a tail that shows nothing. The sibling system probe (same class, one row down: a user outside systemd-journal / adm sees the same notice) is journalctl --quiet -u <unit> -n 1 --no-pager, so it reaches the sudo journalctl rung the comment above it promises instead of exec-ing an unprivileged journal that prints only the notice.
Every rung of the chain after the change: user unit running or alone → quiet --user probe: rows → exec journalctl --user …; empty → next rung. System unit file present → quiet unprivileged probe: rows → exec journalctl …; empty and no TTY → the 👻 refusal, exit 1; empty with a TTY → exec sudo journalctl …. No system unit → launchd file (macOS) → gateway.log → the "no logs" guidance. Real rows never carry the notice, so no rung that showed logs before shows fewer now.
Tests: test_an_empty_user_journal_saying_no_entries_still_falls_through and test_a_no_entries_probe_is_not_rows_and_reaches_the_sudo_rung (a journalctl fake answers -- No entries -- unless asked with --quiet) — both exec'd journalctl on the b34d750 sources where tail / sudo were expected, green on f0c1687; the exact-argv expectation in test_user_journal_is_execed_when_only_the_user_unit_exists carries --quiet.

@pepmach

pepmach commented Sep 25, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _teardown_system_scope() requires the checked stop/disable only when _unit_state(user=False).load == "loaded"

  • gating the system unit's rm on stop/disable makes a stale unit file unremovable on a host where systemctl cannot reach the manager (span=07625eb8f478) — fixed in f0c1687

Accepted: on b34d750 every system-scope teardown ran the checked stop/disable first, so the file install() writes before its daemon-reload raises (a container where systemd is not PID 1; every later verb answers System has not been booted with systemd as init system (PID 1). Can't operate.) came back left in place (…) with exit 1 on every retry, where the base rm -f'd it.
Fix, as proposed: the verbs are required to take only for a unit the manager has LOADED (systemctl show, unprivileged — the same query the user scope already uses); a manager the shell cannot reach, LoadState=not-found (a file dropped without a daemon-reload), a mask or an unparseable unit runs nothing under this name, so the file is removed and daemon-reload issued as the base did. The GPT-round guard stays exactly where a process can be running: loaded + refused stop/disable → left in place, nothing unlinked, exit 1.
Every branch of the system-scope teardown now: no unit file → not installed; file + no sudo → left in place (privilege unavailable: …), exit 1, user scope still torn down; file + manager unreachable or unit not loaded → rm -f + daemon-reload, removed (…); file + unit loaded + refused stop/disable → left in place (…), exit 1; file + unit loaded + rm -f non-zero → stopped and disabled, but its unit file … could not be removed (…), exit 1; file + unit loaded + all took → removed (…).
Tests test_a_stale_system_unit_file_is_removed_when_the_manager_is_unreachable (every systemctl fails with the PID 1 message: no stop/disable, rm -f issued, removed, user scope not reachable with that diagnostic) and test_a_system_unit_file_the_manager_has_not_loaded_is_removed_without_a_stop (LoadState=not-found, a stop that would exit 5: rm -f + daemon-reload, removed) — both read left in place (…) on the b34d750 sources, green on f0c1687; the full-teardown test models a LOADED stopped unit and still asserts sudo systemctl stop/disable/rm -f/daemon-reload.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Sep 25, 2026
@pepmach
pepmach force-pushed the fix/service-linux-status-user-scope branch from f0c1687 to 21d1fbc Compare September 25, 2026 23:48
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 25, 2026
@pepmach

pepmach commented Sep 25, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _teardown_refusal() (alias, or a running unit not loaded, refused before any verb in either scope); _stop_and_disable() re-reads ActiveState after stop before anything is unlinked; _SYSTEMD_BOOTED_DIR decides an unreachable system manager

  • A running masked unit is deleted without being stopped (span=6b3286a41273) — fixed in 21d1fbc

Real: on f0c1687 the system-scope gate load == "loaded" skipped stop/disable for a unit systemd reports as masked / error / bad-setting while ActiveState=active, then rm -f'd its file and reported removed — the r1 class again, opened by the r2 fold that read "not loaded" as "not running". Load state says nothing about a process; ActiveState does.
Fix: in EITHER scope the order is stop → disable → verify inactive (a second show) → unlink → daemon-reload, and nothing is unlinked without the manager's word that the unit is stopped. Before any verb, _teardown_refusal() refuses whole (nothing stopped, disabled or unlinked, ⚠️ + exit 1) an alias and any unit that is running under a load state other than loaded: left in place (an active unit whose load state is masked: unmask and stop it first, then run `kirocrew service uninstall` again); the same line with stop it first for error / bad-setting / not-found-while-running (a file removed under a running unit). A stop that returns 0 while the unit is still running is refused by the re-read (still active (running) after `… stop` returned 0), no unlink.
Every branch of the system-scope chain now: no file → not installed; no sudo → left in place (privilege unavailable: …), exit 1, user scope still torn down; manager unreachable and /run/systemd/system present (sd_booted) → left in place (the system manager is not reachable from this shell: …), exit 1, nothing removed; manager unreachable and that directory absent (no systemd on this host, the r2 container case) → rm -f + daemon-reload, removed; alias → refused whole; running and not loaded → refused whole, exit 1; loaded → stop, disable, re-read: refused verb or still running → left in place (…), exit 1; verified stopped → rm -f (non-zero → stopped and disabled, but its unit file … could not be removed (…), exit 1) → daemon-reload → removed; not running and not loaded (not-found after a dropped file, an inactive mask, an unparseable unit) → rm -f + daemon-reload, removed, as the base did.
Tests: test_a_running_masked_system_unit_is_refused_whole, test_a_running_masked_user_unit_is_refused_whole, test_a_running_unit_whose_file_was_removed_under_it_is_not_reported_not_installed, test_a_system_scope_alias_is_never_stopped_or_disabled_on_our_name, test_a_stop_that_returns_0_but_leaves_the_unit_running_is_not_followed_by_unlink, test_uninstall_reads_the_state_back_after_the_stop_before_unlinking (verb order show, stop, disable, show, daemon-reload), test_an_unreachable_manager_on_a_systemd_host_keeps_the_system_unit_file — all red on the f0c1687 sources (rm -f issued for the running masked unit; stop/disable issued on the alias; unlink after an ignored stop; no re-read), green on 21d1fbc; the fake manager is now stateful (a scope told to stop answers inactive (dead) afterwards unless stop_is_ignored).

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 26, 2026
@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: uninstall() followed the manager-reported FragmentPath of the loaded user unit to os.unlink, so a systemctl --user link /path/kirocrew.service unit — whose FragmentPath is the link's resolved target on the older loader — lost the operator's own file

  • Externally linked units lose their source file (span=6b3286a41273) — fixed in 88b3d04

Accepted, the lane's fix verbatim. What the user-scope unlink may touch is now settled BEFORE the verbs, against the user manager's own unit search path (_user_unit_search_path(): systemctl --user show -p UnitPath, the Manager object's UnitPath — present in systemd 219's dbus-manager.c — asked rather than derived from XDG variables, because those directories are exactly the ones this manager loads units from). Only a DIRECT file — os.path.islink false — inside one of those directories is unlinked (_user_unit_removal()). Everything else the manager names is a linked unit: the name-map loader (unit_file_resolve_symlink, systemd >= 245: "this is a linked unit file … we return the link source") reports the link inside the search directory, the older open_follow() loader reported the resolved target outside it, and both shapes are handled — the source is never touched, disable removes the link entry (it undoes link on every supported version), any entry that survives it — the reported link itself, or a search-directory entry that resolves to the source — is unlinked as a LINK, which removes the entry and never what it points at, and the line reads removed (the link to <source>; the linked unit file <source> itself was kept). A link entry that cannot be removed is reported (stopped and disabled, but the link … could not be removed (…); remove the link by hand — not the file it points at, unfinished), and a manager that does not answer UnitPath is handed the unit back whole before any verb (left in place (the user manager did not report its unit search path, …)), the way every other unverified shape is. The system scope was never exposed: its rm -f targets the literal UNIT_PATH, and rm on a symlink removes the link. Red-first on this head, test_uninstall_never_deletes_a_linked_units_source_file (source outside the search path reported as FragmentPath, the older loader's shape): "the operator's linked unit file was deleted"; also …removes_only_the_link_when_the_manager_reports_the_link_itself (the name-map shape), …a_link_entry_that_cannot_be_removed…, …refuses_whole_when_the_manager_does_not_report_its_search_path, and the order pin now reads show, show UnitPath, stop, disable, show, daemon-reload. Spec: docs/system-specs/modules/cli.md (the service uninstall row and the module paragraph) and docs/guides/install.md carry the rule. Fourth occurrence of this span: the class is "the teardown acts on something the manager did not confirm is ours to act on" — the retrospective the conductor owns is due.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: UninstallReport.removed_any tested startswith("removed") on each scope's line, so the finished system-scope outcome stopped (its unit file … was already gone, so nothing was disabled or unlinked; daemon-reload run) headlined ℹ️ No kirocrew service was removed.

  • removed_any keys on the literal prefix startswith("removed"), so the finished system-scope stopped (…) line yields the headline "No kirocrew service was removed." (span=07625eb8f478) — fixed in 88b3d04

Accepted. The report now carries its outcome as structure: UninstallReport.removed is the set of scopes whose unit is gone from its manager on this call's account — its file unlinked, its link entries removed, or the fileless unit stopped and daemon-reloaded away — filled from a per-scope _ScopeTeardown(line, finished, removed) that _teardown_system_scope() returns and from the user-scope arms in uninstall(); removed_any is bool(self.removed) and the controller's headline reads it, never a line's wording. The fileless-stopped system unit is removed=True (after the daemon-reload the manager has no such unit), so the headline is ✅ kirocrew service stopped and removed. and its line still says what happened. Red-first on this head: test_a_running_system_unit_whose_file_was_deleted_is_stopped_not_reported_not_installed now asserts report.removed == {"system"} and the ✅ headline ("no attribute removed" / No kirocrew service was removed printed), and test_removed_any_is_the_reports_structure_not_a_line_prefix pins that a bare removed (…) line with no scope in the set is False. Spec: cli.md row and module paragraph ("the headline follows the report's removed set, never a line's wording"); Backwards compatibility names the headline change.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: UninstallReport's docstring said "a system-scope refusal of any kind … [is] unfinished" while _teardown_system_scope's elif not file_present: arm returned left in place (…), True (finished) for a not-loaded, not-running unit with no file at UNIT_PATH

  • UninstallReport's docstring states "A system-scope refusal of any kind … are unfinished", but the elif not file_present: arm returns left in place (…), True for a runtime mask with no file (span=07625eb8f478) — fixed in 88b3d04

Accepted — the lane's first arm, the docstring was wrong and the code was right, with one adjacent arm aligned so the narrowed statement is a single rule. Which and why: the mask arm stays FINISHED. The rule that decides "unfinished" is what the call leaves behind for the operator — a unit still running, this module's own file still at UNIT_PATH, a manager whose word could not be had (unreachable, or a stop / disable it refused), a file or link that would not go, or a system unit this process lacks the privilege to touch. A runtime mask with no file at UNIT_PATH and nothing running leaves none of those: nothing this module owns is on disk and no process runs, so it is a report (exit 0), exactly the reading the user scope already gave an inactive alias, mask or unparseable unit. The docstring now states that rule and lists the unfinished arms by name. The aligned arm: _teardown_refusal()'s system-scope refusals (an alias, an unverified Id, a running unit under a load state other than loaded) were ALL unfinished; they are now unfinished iff file_present or state.running — an inactive alias of another unit provided from a directory this module does not own, with nothing at UNIT_PATH, is a report too, because leaving it unfinished would have been the same contradiction one arm over (a "leaves nothing behind" refusal exiting 1). With the module's file present, or the unit running, every refusal stays unfinished as before. Red-first on this head: test_a_fileless_system_refusal_that_leaves_nothing_behind_finishes_the_scope (unfinished == {"system"} for the inactive fileless alias on the old code; the running and file-present arms still unfinished on both). Spec: cli.md row ("exit 1 whenever a unit may still be running, or the module's own file stays at /etc/systemd/system/kirocrew.service; a system refusal with no file there and nothing running … exits 0") and module paragraph; Backwards compatibility names the exit-code change.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: docs/guides/install.md's user-scope paragraph said a per-user restart that lands in activating (auto-restart) "points at kirocrew logs", while _journal_hint(user=True) — the remedy ScopeRestart.hint carries for that scope — prints journalctl --user -u kirocrew.service -n 50 --no-pager

  • the added sentence claims a per-user restart that lands in activating (auto-restart) "points at kirocrew logs", while _journal_hint(user=True) prints journalctl --user -u kirocrew.service -n 50 --no-pager (span=0f675d2b3984) — fixed in 88b3d04

Accepted. The sentence now names the command the code emits: "says so and prints that unit's own journal read, journalctl --user -u kirocrew.service -n 50 --no-pager, rather than a sudo systemctl command that would not find the unit" — the string is the one test_service.py's restart cases assert on the report (hint == "journalctl --user -u kirocrew.service -n 50 --no-pager"), so the guide and the code cannot part again without a test noticing the code side. kirocrew logs was the round-4 wording from before the hint became per scope (round 4 made the journal hint scope-specific precisely so that a mixed two-scope result does not point at the healthy sibling's journal, which a generic kirocrew logs would have). The same paragraph also gained the linked-unit sentence for the uninstall change on this head. docs-lint.sh green.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _confirm_up / _RESTART_SETTLE_SECS re-read the unit for 2 s after systemctl restart in either scope, so restart() also fixes the Type=simple false-success that the reported one-scope blindness did not name

  • Item 4 — rides along: the settle-window health confirmation fixes a second defect (Type=simple's exit-0 at fork), not the scope-blindness the title names; declared at length and derived from systemd semantics (span=30496457e28c) — declared (kept) on 0d67d96

Declared and kept, as the item grants. The verb this PR makes reach the user unit is restart, and on the host the issue describes a user-scope restart of a gateway that dies on start reads as success without the confirmation: the unit is Type=simple, the start job succeeds at the fork (systemd.service(5): the manager considers a Type=simple unit started immediately after the main process has been forked), systemctl --user restart exits 0 into activating (auto-restart), and the base's path printed ✅ Restarted kirocrew service. — the Opus lane's round-3 blocking item on this PR. Derived from that rule, measured rather than asserted (transcript 3: 2.20 s per successful restart; a real 203/EXEC loop classified NOT UP in 0.13 s; a process dying 0.7 s after the fork caught at 0.94 s where three single reads said active (running)), named in the body's What-changed table and Backwards compatibility as a change to every restart in both scopes, and pinned by tests that fail on base (test_restart_into_a_crash_loop_is_a_failure_not_a_refusal, test_restart_confirmed_up_stays_ok_after_the_window, test_restart_reports_a_manager_that_vanished_mid_window_as_unconfirmed in TestLinuxServiceScopes). Unchanged on this head.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _teardown_refusal() and _UnitState.ours / removable refuse an alias, an unverified Id, a running unit under a load state other than loaded, and a mask or unparseable unit before any verb, in both scopes

  • Item 6 — rides along: the alias/mask/unparseable refusals guard shapes unrelated to the reported defect; derived from systemd name resolution (a verb on the name acts on the resolved unit, and the unlink follows manager-reported FragmentPath) (span=6d400463a3df) — declared (kept) on 0d67d96

Declared and kept, as the item grants. The refusals are not a feature beside the fix; they are what the fix must carry to be safe on the surface it opens. The base acted on one scope through a path it wrote itself; this PR makes stop, restart and uninstall act through the account's own manager on a name whose file it did not write — so the module has to know whose unit it is acting on. systemctl show <name> answers for the unit the name RESOLVES to (an alias reports the target's Id and FragmentPath), a runtime mask hides the fragment while the process keeps running, and an unparseable edit leaves a loaded process with no readable definition: a verb or an unlink issued on the bare name would land on another unit or delete the wrong file — the three GPT/Opus blocks of rounds 3, 5 and 6 on this PR were exactly those shapes. Each refusal derives from a named systemd rule (name resolution for aliases; systemctl mask leaving a running unit running; daemon-reload semantics for a removed file), each has a red-first test in TestLinuxServiceScopes, and the body declares them. One correction to the item's own parenthetical on this head: the unlink follows manager-reported FragmentPath only for a DIRECT file inside the manager's own UnitPath; a linked unit's source is never followed (the GPT block on this head, 6b3286a41273). Unchanged otherwise.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: common.restart_command_hint() picks the restart command by which unit file exists (system, user, or kirocrew restart when both or neither), _journal_hint(user=…) names the scope's own journal, and slack/gateway.py's auto-update failure handler awaits the hint via asyncio.to_thread

  • Item 9 — rides along: scope-aware hint strings and the Slack asyncio.to_thread wrap extend the fix into the update path; declared, single call site wrapped (span=ace56c2ca0e7) — declared (kept) on 0d67d96

Declared and kept, as the item grants. The hint strings are the fix's own consequence, not an extension: once a gateway can be the per-user unit, every place that told the operator how to restart it — the Slack update-failure line, headless_auth_warning() at install time and through doctor, the CLI's failed-restart remedy — printed sudo systemctl restart kirocrew, a command that does not find a user unit (the round-3 Opus block and the round-5 FP item 10 on this PR), so the strings had to learn the scope with the module. restart_command_hint() derives its answer from which unit file exists (systemd's own layout, UNIT_PATH vs ~/.config/systemd/user), defers to kirocrew restart when both or neither exist (a file says nothing about which scope runs — the round-5 local lane's Medium), and _journal_hint() names the scope whose unit failed rather than the healthy sibling's journal. The asyncio.to_thread wrap is the one call site that runs on the gateway's event loop — the round-7 GPT block on this PR: the hint stats a file under Path.home(), a possible network mount — and the other call site (install time) is synchronous by nature; both are counted in the body (grep restart_command_hint: 2 call sites). Pinned by tests that fail on base (TestRestartCommandHint, test_slack_gateway.py::TestAutoApplyUpdate::test_failure_path_resolves_the_restart_hint_off_the_event_loop). Unchanged on this head.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 26, 2026
@pepmach
pepmach force-pushed the fix/service-linux-status-user-scope branch from 88b3d04 to ae04ae9 Compare September 26, 2026 20:41
@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _user_unit_removal() classified the manager-reported FragmentPath as a direct file of ours from its own shape alone — parent inside the search path and not itself a symlink — so a kirocrew.service symlink in a HIGHER-priority search directory resolving to a direct file in a LOWER-priority one made the resolved file look like the remedy's unit, and uninstall() unlinked the operator's file

  • Linked user-unit source can be deleted (span=6b3286a41273) — fixed in ae04ae9

Accepted, the lane's fix verbatim. Before any direct-file classification, every search-path directory is scanned for a kirocrew.service entry that is a symlink resolving to the fragment (by path or by realpath); if one exists the unit is a linked unit — the source is kept and only the link entries are removed (disable first, any survivor unlinked as a link) — and only a direct file inside the search path that NO such link points at is unlinked. The premise is confirmed on a current loader, not only the pre-245 one the file's comment named: transcript 4 (PR body, C5) on a live systemd 252 lays out exactly this shape ($XDG_RUNTIME_DIR/systemd/user.control/<unit> → $XDG_RUNTIME_DIR/systemd/user/<unit>) and the manager reports the RESOLVED lower-priority file as FragmentPath; this head classifies it unit_file=None links=[<the user.control link>]. On that host the run then ends at systemd's own disable, which refuses the layout (Refusing to operate on alias name or linked unit file): the teardown stops after the stop, left in place (… disable … failed: …; the unit file was not removed), unit stopped, link and file both intact — fail closed either way, nothing deleted. Red-first on this head: test_a_higher_priority_link_to_a_lower_priority_unit_file_keeps_that_file ("the operator's lower-priority unit file was deleted"); the refused-disable outcome is pinned by test_a_disable_the_manager_refuses_on_that_layout_keeps_both_the_link_and_the_file, and test_a_direct_unit_file_nothing_links_to_is_still_unlinked keeps the remedy's own direct file on the unlink arm (a same-named direct file in a lower-priority directory is not a link and is not touched). Spec: docs/system-specs/modules/cli.md (the service uninstall row and the module paragraph) carries the scan-first rule. Fifth occurrence of this span (r1 failed teardown, r3 masked-running, r5 unreachable verification, r10 linked source, r11 higher-priority link) — one class, "the teardown acts on something the manager did not confirm is ours"; the retrospective the conductor owns is due.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the destructive verbs' fail-closed arms — alias, runtime mask, not-found while running, an unreachable manager, no UnitPath answer — were covered by mocked tests and the body's transcripts recorded only the read-only verbs and the happy-path teardown, so a real-host surprise had no recorded baseline

  • Capture the fail-closed transcript (span=3ab5da126ac1) — done in ae04ae9

Accepted as work: transcript 4 in the PR body's Manual verification section is the real run — a live systemd 252 user manager inside a pod, throwaway kirocrew-verif-<rand>-* runtime units created and removed by the script (leftover files: 0), the driver refusing any other unit name. Six shapes: C1 an alias holds the name; C2 a runtime mask replaces the file of a running unit (LoadState=masked ActiveState=active); C3 the file removed under a running unit (not-found + active); C4 the driver's bus pointers naming places with no manager socket; C5 the GPT layout (a higher-priority link to a lower-priority direct file); C6 a link in a search directory to an operator's file outside it. C1-C4: restart() attempts nothing, stop() issues nothing, uninstall() refuses whole before any verb (left in place (… is an alias of …), … load state is masked …, … not-found: stop it first …, not reachable from this shell (Failed to connect to bus: No such file or directory)) and afterwards the unit still runs with every file and link in place — the one verb that acts is stop() on a masked or not-found unit that is ours and running, the safe verb. C5 produced this round's finding (systemd 252 reports the resolved file for a same-name link inside the search path; the scan-first classification keeps the file; systemd's own disable then refuses the layout, so the run ends left in place, nothing deleted). C6 shows round 10's fix on a real manager: link gone, the operator's file kept. The shape that cannot be produced on a real systemd — a manager that answers without UnitPath or without an Id — stays covered by the mocked tests only, and the body says so. The scripts (verif_evidence_r11.sh, verif_driver_r11.py) live in the worker's scratch, not the repository: they are host-specific pod drivers, and the body carries the run.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: uninstall()'s fileless system arm acted on state.installed or state.running — the manager's word that SOME unit is loaded under our name — so a distribution's kirocrew.service under /usr/lib/systemd/system, loaded because no file of ours shadowed it, was stopped and daemon-reloaded while the headline read removed; the third block on the same span, each an arm deciding "ours" from a different partial signal (a file's shape, a link's shape, a load state)

  • Fileless teardown can stop an unowned system unit (span=6b3286a41273) — fixed in 47e51b3

Accepted as a RESTRUCTURE, not a third arm. One ownership resolver, _owned_unit(fragment, user=…) -> OwnedUnit | None, decides from the manager-reported FragmentPath (followed through a symlink to its source), the installer's own path for the scope (a plain file there is ours marker or not — units written before the marker; a symlink there resolving to the fragment is the higher-priority-link shape), and the ownership marker the installer already writes into every rendered unit — Environment="KIROCREW_SERVICE_MANAGED=1", the line kirocrew doctor reads, now through the same unit_file_carries_managed_marker() — and a definition under another name or a file that cannot be read is never ours. EVERY teardown arm consults only it: _teardown_owned(), _remove_stale_owned() and _remove_owned() take the OwnedUnit, and no other function in the module reaches _stop_and_disable, rm or os.unlink on a unit file (the structural test test_every_teardown_arm_rests_on_the_one_ownership_decision reads the module's AST for exactly that, and runs uninstall() with the resolver patched to None across running / stopped / one-scope layouts: no verb in either scope). Not ours → left untouched (not installed by Kiro Crew: …), nothing stopped, exit 0; ours-by-link → the link entries go, the definition stays; ours-direct → unlinked. Red-first on this head, test_a_vendor_unit_with_no_unit_file_of_ours_is_left_untouched_not_stopped: ['sudo', 'systemctl', 'stop', 'kirocrew.service'] was issued on the vendor unit. Spec: docs/system-specs/modules/cli.md (row + module paragraph) and docs/guides/install.md carry the ownership rule. This closes the class the five occurrences of this span shared — an arm deciding "ours" from a signal that does not carry it — by removing every such arm: there is one decision and the verbs cannot run without its result.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _user_unit_search_path() queried the manager's UnitPath and _user_unit_removal() scanned every one of its directories for links across two loader generations, for one consumer, to classify one fragment

  • Item 6 — one consumer, generalized (span=013a94339a1b) — fixed in 47e51b3

Subtraction taken, folded into the resolver. Both functions are deleted, with the UnitPath query, the os.path.isabs filter and the loader-generation reasoning; _owned_unit() looks only where the manager points — the reported FragmentPath (a symlink there is the link, its realpath the definition) and the installer's own path for the scope (a symlink there resolving to the fragment is the other link shape) — and decides ownership of the definition by the installer's path or its marker line. Which loader reports a link by its entry or by its resolved target no longer matters: both shapes resolve to the same definition and the same link entry. The "kirocrew user unit loaded from a non-remedy search directory that uninstall must remove" the item named as the other clearing condition is covered without a scan: a copy of our unit carries the marker wherever it lives, so it is ours by the marker and removed (direct) or unlinked-by-link. The two tests that existed only for the scan (…refuses_whole_when_the_manager_does_not_report_its_search_path, the ntpath-simulated filter) went with it; the Windows (5) reds of the previous head, a UnitPath filter artifact, cannot recur.

@pepmach

pepmach commented Sep 26, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _confirm_up() walks a fixed _RESTART_SETTLE_SECS = 2 window after systemctl restart; a Type=simple gateway that dies later than that after its fork is reported up

  • Derive the settle bound from RestartSec if the 2 s window misses (span=dbc132007ca7) — declared

Declared, follow-up shape named in the body (Manual verification): if a late death surfaces on a real host, the bound is derived from the unit's own RestartSec — read from systemctl show -p RestartUSec on the scope being restarted, so the window is the manager's restart cadence rather than a constant — instead of widening the constant. Not taken here: no death later than 2 s after the fork has been observed, every measured one landed inside 1 s (transcript 3: a 203/EXEC loop reported at 0.13 s, a death 0.7 s after the fork caught at 0.94 s), and the 2 s figure is a bound on a Python gateway's import-time death, not a measured maximum; the change would also touch the restart contract this PR already had to restructure once. It lifts out as one read in _confirm_up() plus the existing fake-clock tests when the evidence arrives.

`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
@pepmach

pepmach commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the spec's system-scope sentence (docs/system-specs/modules/cli.md, the module paragraph) lists an inactive mask among the not-loaded, not-running definitions that are "removed outright", while _owned_unit() followed the mask at /etc/systemd/system/kirocrew.service to its /dev/null realpath, read no MANAGED_MARKER_LINE there and answered None — so the mask was left in place (load state masked, …) and the doc and the code disagreed

  • the spec says an inactive mask is removed outright while _owned_unit() leaves a /dev/null mask at our path in place (span=9ffc04d5b952) — fixed in 6067a76

Accepted, and fixed in the resolver rather than the doc, so the sentence stands. systemctl mask kirocrew.service writes its /dev/null symlink at exactly the path the installer writes to — a mask is placed by unit NAME in the top-priority directory — so that entry masks OUR name and holds no definition to read a marker from. _owned_unit() now claims it by name before the link/definition reading: _is_mask_of_our_name() is true for a symlink at the installer's exact path whose realpath is /dev/null, and the result is an OwnedUnit(mask=True) whose definition is the mask entry itself; _remove_owned() unlinks that entry (rm -f under sudo / os.unlink, never /dev/null) and _remove_stale_owned() reports removed (the mask <path>; kirocrew.service is unmasked), then daemon-reload. A mask anywhere else (systemctl mask --runtime, under /run) is not at our path and stays left in place (load state masked, …); a symlink at our path resolving to anything but /dev/null is read as before (an unmarked source is not ours). The running-masked refusal (unmask and stop it first) is untouched — it fires before ownership. Red-first on this head: test_a_persistent_mask_of_our_name_is_removed_in_the_system_scope (both loader readings of FragmentPath: the mask entry, the name-map loader; /dev/null, the older open_follow() loader — the resolver reads the entry at our path either way) and …_in_the_user_scope fail with left in place (load state masked, unit file …), the reading this finding describes; test_a_link_at_our_path_that_does_not_resolve_to_dev_null_is_not_a_mask pins the boundary. The user scope reads the same rule at ~/.config/systemd/user/kirocrew.service (systemctl --user mask). Spec: the command row and the module paragraph in cli.md now state the rule (the row's parenthetical no longer calls a mask "never acted on"; the user-scope sentence names the ownership decision instead of the pre-resolver LOADED-only reading); the PR body's Backwards compatibility section records that the round-12 head alone had left a mask at our path in place, and that the base's behavior — the mask removed — is back through the resolver.

@pepmach

pepmach commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _finish_scope() (src/kiro_crew/service/linux.py:1541) discards the result of _systemctl("daemon-reload", …), so _teardown_owned() / _remove_stale_owned() still return removed (…) with removed=True when the manager rejects the reload — the scope counts in UninstallReport.removed, the headline reads stopped and removed, exit 0, while the manager holds the old definition until a later reload

Accepted, deferred: #14331 "service.linux: propagate a rejected daemon-reload in _finish_scope and document the installed/up predicates" — deferred-finding, bug, assignee pepmach, due 2026-10-09 — carries this site and the lane's fix verbatim ("propagate the reload failure and mark the scope unfinished"): _finish_scope() returns the reload's outcome, a non-zero daemon-reload makes the scope line removed (<path>), but \… daemon-reload` failed: <manager's first line>; run it by hand, the scope lands in unfinished(exit 1) and not inremoveduntil the reload took, red-first through_fake_systemctl's overrides=seam, with thecli.md spec sentence. Not folded here: this head is frozen green, and the change moves a contract (_finish_scope`'s return, two teardown arms, the report lines, the spec row). The exposure until then is a stale manager view after a successful unlink — the file is gone and the unit stopped — not a wrong deletion.

@pepmach

pepmach commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: two docstrings name a narrower predicate than the code reads — user_unit_installed() (src/kiro_crew/service/linux.py:1643) says the manager "has a kirocrew.service loaded" while _UnitState.installed is true for every load state but not-found (masked, bad-setting, error count), and restart() (:1880) says ok "only when every restarted unit is UP" while UP (_UnitState.up, read by _confirm_up()) is active or reloading

Accepted, deferred: #14331 — deferred-finding, assignee pepmach, due 2026-10-09 — carries both sites and the lane's fix verbatim ("document the actual predicates on lines 1643 and 1880"), with the wording the docstrings will take: user_unit_installed() → "the manager answers a load state other than not-found for a unit whose canonical Id is ours (loaded, masked, bad-setting and error all count; only not-found does not)"; restart() → "ok only when every restarted unit is UP — active or reloading, what systemctl is-active exits 0 for — at the end of the settle window". Prose only, no behavior moves; not folded here because this head is frozen green and every push restarts the review round, so it rides with the reload propagation in the same issue.

@pepmach

pepmach commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _owned_unit() (rounds 12-13) decides what uninstall() deletes from the manager-reported FragmentPath, the installer's own path and the managed-marker line; transcript 4's C5/C6 link layouts ran on the round-11 head, whose search-directory scan is gone, and the round-13 persistent-mask arms have run only under the mocked systemctl, so a real-systemd FragmentPath shape the fake does not reproduce is unobserved on this head (failure direction fail-closed: an unclaimed unit is left untouched)

  • The ownership resolver that gates uninstall's file deletion is mocked-only on this head; the owed live C5/C6 re-run hasn't happened (span=440e0f7590e0) — addressed on 6067a76 (tracker filed)

Accepted, issue arm: #14332 "Live re-run of _owned_unit on real systemd (transcript 4 C5/C6, persistent-mask arms) and a RestartUSec-derived settle bound" — deferred-finding, enhancement, assignee pepmach, due 2026-10-09, "Follows #13964" — specifies the run the WATCH names: the round-8/11 method (throwaway kirocrew-verif-<rand>-* units only, a driver that repoints SERVICE_NAME / user_unit_file_path() and refuses any other name, never the pod's own unit or a host unit), every shape with the line this head's resolver must produce — C5 marked (systemd 252's own disable refusal, unit stopped, link and file intact) and unmarked (left untouched), C6 marked (link removed, source kept) and unmarked, the persistent mask (removed (the mask …; … is unmasked), then not-found), a mask while running (refused whole), a runtime mask (left in place (load state masked, …)), a direct file marked and unmarked — plus the FragmentPath systemd 252 reports for each, cleanup proof, and the transcript's destination. This is the WATCH's second clearing arm ("or an issue tracks that run like #14190 tracks the alias gap"); the first — the run itself — was not taken on this head because it is frozen green and the transcript would need a body edit, which re-runs the review lanes. The resolver's behavior on every one of those shapes is pinned by red-first tests in test/test_service.py::TestLinuxServiceScopes on this head.

@pepmach

pepmach commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: _RESTART_SETTLE_SECS is a fixed 2 s with a 0.25 s read; the PR body promises to derive the bound from the unit's own RestartSec (systemctl show -p RestartUSec) "if that surfaces", and a promise in a PR description has no owner once the PR merges

Accepted, issue arm: #14332 — deferred-finding, enhancement, assignee pepmach, due 2026-10-09, "Follows #13964" — item 2 carries the derivation: read systemctl [--user] show -p RestartUSec for the unit being confirmed and derive both numbers from it (the read interval bounded above by a fraction of RestartUSec, so an activating (auto-restart) visit — which lasts RestartSec — is never stepped over; the window bounded by the unit's own timing rather than a constant), with transcript 3's measurements as the constraints a derivation must keep (2.20 s healthy confirm, 0.13 s 203/EXEC loop, a 0.7 s death caught at 0.94 s), a fallback to today's constants when the manager does not answer RestartUSec, and the red-first shape (RestartUSec=100ms, the unit flipping activating (auto-restart) → active between 0.25 s reads). Not folded here: this head is frozen green, and no late death has been observed on a real host — every measured one landed inside 1 s — so the change waits for its evidence with a tracker instead of a sentence in the description.

@pepmach

pepmach commented Sep 27, 2026

Copy link
Copy Markdown
Contributor Author

Description gains the **Goal:** line and ## Not a goal section the PR template requires since #14181 -- a first write of the frozen sections from this PR's opening intent, not an edit of a frozen goal. Head unchanged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

posix-only-approved Cross-Platform Portability findings reviewed and accepted as intentionally POSIX-only

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Linux: service status/uninstall inspect only the system scope, so a running user-scope gateway reports "inactive (dead)"

3 participants