Skip to content

fix: ask systemd whether a pod host has a per-user manager - #31980

Merged
bolichen97 merged 1 commit into
mainfrom
fix/7399-ask-systemd-user-manager
Nov 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/7399-ask-systemd-user-manager

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Decide whether a Linux host has a per-user systemd manager by asking systemd itself, so a masked unit or a moved unit path no longer gets the wrong pod remedy.

The pod gate (require_systemd()) and kirocrew doctor decided "can this host have a systemd --user instance" by walking a hand-copied list of systemd's unit directories with os.path.exists. That walk reads a masked user@.service (a symlink to /dev/null) as present, cannot see $SYSTEMD_UNIT_PATH, and is a list someone has to keep in step with a manual page. On such a host, a pod verb tells the user to run loginctl enable-linger, which cannot work.

Why it matters

A user on a host whose administrator masked the per-user manager is sent after a remedy that cannot succeed, instead of being pointed at ./dev-backend.sh. Doctor gives the same wrong answer. Every fix to the directory list so far has been one more directory found missing in review.

Not a goal

  • Changing what a host WITH a session bus does: that path runs no unit check and is unchanged.
  • Changing how backend absence is classified: the missing bus socket still alone makes a refusal PodBackendAbsent.
  • Removing the directory walk: it stays as the fallback for a host where the system manager cannot be asked.
  • macOS or Windows pod backends.

What changed (motivation → approach → change)

A pod command or kirocrew doctor on a Linux host whose per-user manager is masked, or whose units sit on a path only systemd knows, gets the right advice: there is no manager here, use ./dev-backend.sh, instead of a loginctl enable-linger that cannot work. The wrong advice came from user_manager_unit() re-implementing systemd's unit lookup instead of asking for its result.

user_manager_unit() now asks the SYSTEM manager first: systemctl show --property=LoadState user@<uid>.service. System scope needs no user bus, so it answers on exactly the hosts where systemctl --user cannot. PID 1 resolves that name the way it would to start it: a concrete user@<uid>.service before the template, any mask, and its own unit path. not-found and masked mean no manager; any other state means one exists. This asks about the exact unit rather than listing user@*.service (the issue's suggestion), because one word needs no row parsing and covers both unit shapes in one call. When the call cannot answer (no trusted systemctl, an error, a timeout), the existing directory walk decides, as it did before.

Both callers share the one helper, so the pod gate and doctor cannot disagree. The gate reaches it only on its no-bus branch, which refuses either way: the answer picks the remedy text, never the error class, and no --user call is spawned there. The refusal text names the unit and template instead of the directory list. pod/README.md, the doctor row in cli.md, the Dev Fleet pod section and src/kiro_crew/docs/troubleshooting.md say the same.

Backwards compatibility

Compatible: hosts where systemd's answer matches the directory walk get the same message as before; the only hosts that change are those where the walk was wrong (a masked unit, a unit path the list did not hold), and a host where systemd cannot be asked keeps today's walk.

Removes nothing: no key, function or record is removed; the refusal message drops its directory list because systemd, not that list, now decides.

Tests

  • test_user_manager_unit_takes_the_system_managers_answer: with a template file on disk, a masked or not-found answer makes user_manager_unit() return None, loaded returns the unit, and the call is system scope (no --user). A failed call, a non-zero exit, an unparseable or empty answer and a timeout each fall back to the directory walk.
  • test_missing_bus_spawns_only_the_system_unit_query (renamed from test_missing_bus_is_reported_without_spawning): the user-bus probe still spawns nothing on a missing bus; each gate spawns exactly one systemctl show --property=LoadState user@4242.service and still raises PodBackendAbsent when that query fails. Its old spawned == [] for the two gates is the one assertion this PR changes, because asking systemd on that branch is the fix; the new list is pinned exactly.
  • test_user_manager_unit_finds_a_hand_installed_uid_unit pins the system answer as unavailable, so it keeps testing the directory walk it was written for.

Determinism: the three tests 20 times at -n0, then 10 times at -n 4 --dist loadgroup --max-worker-restart=2 beside test/test_cli_doctor.py and test/test_pod_cli.py, all green; test/test_pod_systemd.py in a shuffled order (seed 9211), green.

Proof: PROVEN test/test_pod_systemd.py::TestSessionBus::test_missing_bus_spawns_only_the_system_unit_query, test/test_pod_systemd.py::TestSessionBus::test_user_manager_unit_takes_the_system_managers_answer (head afeb99f)

Manual verification

On a Linux host with systemd 252, as an unprivileged user: systemctl show --property=LoadState user@<uid>.service prints LoadState=loaded, and LoadState=not-found for a unit with no file or template, with exit 0 in both cases. A masked or $SYSTEMD_UNIT_PATH host was not available; those answers come from systemd's own lookup.

Screenshots / video

N/A — no frontend change.

Related Issues

Closes #7399

Sibling sweep

Swept: git grep -nE "os.path.exists([^)]systemd|lib/systemd/system"|/etc/systemd/system"" -- 'src/.py'
Siblings: none -- the only load-path walk is the one in pod/runtime.py; the service module writes its own unit at a fixed path and does not probe for another one.

Pattern harvest

Not generalizable: a single hand-copied lookup of systemd's unit directories; the fix is to ask systemd, and there is no second copy to catch.

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

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 7, 2026 02:03
@bolichen97
bolichen97 enabled auto-merge (squash) November 7, 2026 02:14
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision ac74ff3064f0fbf45ad78ac2e3cdd5f8e22912b5 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of ac74ff3064f0fbf45ad78ac2e3cdd5f8e22912b5 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: on the no-bus branch, the system manager's answer only changes the remedy text, never the error class, and the directory walk is still the fallback when systemd can't be asked.

Notes

  • If PID 1 isn't systemd, or the system bus can't be reached, systemctl show either fails or answers not-found. A not-found answer means "no manager", not the walk's answer. Only the remedy text changes there, so this is reversible, but a pinned case would document the choice.

[DESIGN-REVIEWED] ac74ff3

Description read

[DESCRIPTION-READ] 79a92b8c02e69c066f57be85cf1236ffca4284de49dca666648ee011dd9f5f78

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ac74ff3064f0fbf45ad78ac2e3cdd5f8e22912b5 — 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 does not.

First-Principles-Verdict: PASS

Nothing to check. The fix replaces the lookup with systemd's own answer, which is the cause, not the symptom. Both callers (pod/runtime.py:849, doctor_checks/services.py:80) share the one helper. The rewritten no-spawn pin is declared in the description and explained there.

What this change ships

Inventory (7 items) — 6 justified

Intent: a user on a Linux host whose per-user systemd manager is masked, or whose units live on a moved unit path, is told to use ./dev-backend.sh instead of a loginctl enable-linger that cannot work. This is a FIX (Closes #7399).

  1. A pod verb on a masked or moved-unit-path host with no bus now gives the ./dev-backend.sh remedy — justified
  2. kirocrew doctor gives the same answer on those hosts — justified
  3. The pod gate's no-bus branch now spawns one system-scope systemctl show call, bounded by the probe timeout — justified
  4. The refusal text names the unit and template instead of listing directories — justified
  5. When systemctl cannot answer, the directory walk still decides — justified
  6. user_manager_unit may now return a unit name rather than a path — undeclared; both counted callers only test for None
  7. The pod README, cli.md, dev-fleet.md and troubleshooting docs now describe the new lookup — justified

[FIRST-PRINCIPLES-REVIEWED] ac74ff3

Description read

[DESCRIPTION-READ] 6c825cfdab097a15c7d8a3a89e070c32654160150d900936027f0ce9d8bc267a

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ac74ff3064f0fbf45ad78ac2e3cdd5f8e22912b5 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ac74ff3

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ac74ff3064f0fbf45ad78ac2e3cdd5f8e22912b5 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ac74ff3

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable ac74ff3064f0fbf45ad78ac2e3cdd5f8e22912b5 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026
@bolichen97
bolichen97 force-pushed the fix/7399-ask-systemd-user-manager branch from afeb99f to a9aa783 Compare November 7, 2026 03:58
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/cli.md, docs/system-specs/modules/dev-fleet.md, test/test_pod_systemd.py since this head went green (42f45e3 -> e6524c8); CI re-running.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 7, 2026
@bolichen97
bolichen97 force-pushed the fix/7399-ask-systemd-user-manager branch from a9aa783 to 90e8c2b Compare November 7, 2026 07:01
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/cli.md, docs/system-specs/modules/dev-fleet.md, src/kiro_crew/docs/troubleshooting.md, src/kiro_crew/pod/runtime.py since this head went green (e6524c8 -> 1a1e609); CI re-running.

[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/7399-ask-systemd-user-manager branch from 90e8c2b to 52da632 Compare November 7, 2026 09:02
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/cli.md, src/kiro_crew/pod/windows.py, test/test_pod_windows.py since this head went green (1a1e609 -> 0795ebc); CI re-running.

[operator: bolichen97]

@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: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 7, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The red Backend Tests shard 2 on Linux, Windows and macOS (and the Coverage Gate and PR Readiness that follow it) is test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget, which fails on main as well: the security package measures 34,855 lines against a 34,845 budget, and this PR changes nothing in it. #32183 raises the budget to the size on main. This PR waits for that to merge and then re-syncs onto it.

The pod gate and doctor decided whether a host can run systemd --user by
walking a hand-copied list of systemd's unit directories. A masked
user@.service read as present and $SYSTEMD_UNIT_PATH was invisible, so a
host with no usable manager was told to enable linger.

Ask the system manager instead (systemctl show --property=LoadState
user@<uid>.service): it needs no user bus and applies systemd's own
instance-then-template lookup, masks and unit path. The directory walk
stays only for when that call cannot answer. Both pod gates and doctor
use the one helper; on the missing-bus branch the refusal is still
PodBackendAbsent whatever the answer, and no --user call is spawned.

Closes #7399
@bolichen97

Copy link
Copy Markdown
Contributor Author

Re-sync budget reset

This head's only red is main's former line-budget test, which main fixed in #32252; every other check, including every AI review lane, passed, so one more re-sync is granted to pick that fix up.

[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/7399-ask-systemd-user-manager branch from 52da632 to ac74ff3 Compare November 7, 2026 13:36
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/dev-fleet.md (another section, no conflict) and test/test_security_gate_liveness.py (the line-budget fix from #32252 that this head's only red needed) (0795ebc -> f58c3cf); the patch is unchanged; CI re-running.

[operator: bolichen97]

@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 readiness: checking Automated validation is still running labels Nov 7, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved: PR Readiness passed on ac74ff3, and all five review lanes (Opus 5.5, GPT 6.1, Design, UX, First Principles) report no blocking finding on this head. No conflict and no open change request.

@bolichen97
bolichen97 merged commit e6f6a10 into main Nov 7, 2026
99 checks passed
@bolichen97
bolichen97 deleted the fix/7399-ask-systemd-user-manager branch November 7, 2026 19:47
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026
buluoray added a commit that referenced this pull request Nov 8, 2026
The pod gate and doctor decided whether a host can run systemd --user by
walking a hand-copied list of systemd's unit directories. A masked
user@.service read as present and $SYSTEMD_UNIT_PATH was invisible, so a
host with no usable manager was told to enable linger.

Ask the system manager instead (systemctl show --property=LoadState
user@<uid>.service): it needs no user bus and applies systemd's own
instance-then-template lookup, masks and unit path. The directory walk
stays only for when that call cannot answer. Both pod gates and doctor
use the one helper; on the missing-bus branch the refusal is still
PodBackendAbsent whatever the answer, and no --user call is spawned.

Closes #7399

(cherry picked from commit e6f6a10)

Original author: Bolin Chen (#31980). Hand-resolved, comment only: src/kiro_crew/pod/runtime.py takes main's comment above the load-path fallback, which describes the code this commit adds; every code line is identical to main.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

pod: ask systemd for the per-user manager unit instead of reading its load path

2 participants