Repository navigation
refactor(service): split linux.py into four owner modules - #22273
Conversation
service/linux.py (2,232 lines) was over the 2,000-line cap. It keeps the verbs that read and drive an installed unit (status, stop, restart and its settle window, is_active, is_up, alias_holder and the user-scope queries) and becomes a kiro_crew._facade_mirror facade over four sibling owners: - linux_unit: the unit and overrides paths, the service account and render_unit - linux_systemctl: privilege, systemctl in either scope and one scope's unit state - linux_install: install, the SELinux refusal and the AppArmor profile steps - linux_uninstall: the ownership decision and the per-scope teardown The suites patch names every layer reads, so the mirror sends a write through the facade to every owner binding the name, and moved bodies keep their AST. The one exception is _systemctl's system-scope branch, which decodes with **UTF8_TEXT like its user-scope branch; _sudo_run and _write_unit_via_sudo carry the locale marker instead. The owners log as kiro_crew.service.linux and ServiceInstallError keeps that module. test_linux_facade.py pins the contract, three source pins read the facade with its owners, and cli.md gains the owner map. Part of #20192
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check one thing before merge: the system-scope [DESIGN-REVIEWED] 0291d31 Description read[DESCRIPTION-READ] ca105201deac84927e7358eb87a3542d23059d19d9d6a95e37b510b56b24e39e 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Check the one behaviour edit: system-scope What this change shipsInventory (7 items) — 7 justifiedIntent: get
[FIRST-PRINCIPLES-REVIEWED] 0291d31 Description read[DESCRIPTION-READ] f214603254f224a402f75e6e0d365284764b53a06f11d2db51f590d578e4d2b1 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
|
Problem / Motivation
Goal: Bring
src/kiro_crew/service/linux.py(2,232 lines) under the 2,000-line cap without changing how the Linux service installs, reports, restarts or uninstalls, so new work on the unit, systemd access, install and uninstall lands in modules sized for it.service/linux.pyis past the repository's 2,000-line cap for hand-written files and is listed in.github/file-line-cap-baseline.txt(row 2,232). One file holds what the unit says and whom it runs as, the privilege andsystemctlplumbing with each scope's unit state, the install path with its SELinux refusal and AppArmor steps, the uninstall ownership decision with its teardown arms, and the verbs that read and restart a running unit.Why it matters
A file over the cap makes every feature PR that touches it grow a baselined file, which the line-cap guard reports and the campaign must later undo. The service module is changed often (install, doctor, restart and SELinux work all land here), so it keeps collecting code.
Not a goal
kiro_crew.service.linuxoffers, or to how a test patches them.service/macos.py), the controller or the AppArmor and SELinux modules.What changed (motivation → approach → change)
linux.pykeeps the verbs that read and drive an installed unit and becomes akiro_crew._facade_mirrorfacade over four sibling owners. The suites patch names that every layer reads (_systemctl,_sudo_run,UNIT_PATH,_current_user,kirocrew_bin, ...), so a plain re-export would leave moved readers unpatched; the mirror sends a write through the facade to every owner binding the name, which keeps each moved body as it was.service/linux.pyuser_unit_installed,user_unit_active,user_unit_path,is_active,is_up,alias_holder,stop,restartwith its settle window,status; the mirror glueservice/linux_unit.pyrender_unitservice/linux_systemctl.py_privilege_prefix,_sudo_run,ServiceInstallError),_systemctlin either scope, one scope's unit state (_UnitState,_unit_state,_stale_unit_line)service/linux_install.pyinstall: the root-owned writes, the overrides seed, the SELinux refusal and start-failure hint, the AppArmor profile install and removalservice/linux_uninstall.pyuninstall: the ownership decision_owned_unit, the per-scope teardown arms,UninstallReportEach owner imports only the owners above it in the table, never the facade. The owners log as
kiro_crew.service.linux, andServiceInstallErrorkeepskiro_crew.service.linuxas its__module__.cli.md's Service Management section gains the owner map.Behaviour changes
_systemctl's system-scope branch (plainsystemctl show|status, no sudo) decodes with**UTF8_TEXTinstead oftext=True: the same mapping its user-scope branch already uses, since systemd writes UTF-8. It differs from the base only on a host whose locale is not UTF-8, and a malformed byte becomes U+FFFD instead of raising. This is the one non-move edit to a moved body (ruled for this split under the subprocess-encoding ratchet).3 src/kiro_crew/service/linux.pyrow of.github/subprocess-encoding-baseline.txtis replaced by the two inline locale markers on_sudo_runand_write_unit_via_sudo(whose children, sudo and coreutils, print in the locale, as the base decodes them) plus the**UTF8_TEXTfix in_systemctl.Backwards compatibility
Compatible: every public name
kiro_crew.service.linuxbound before the split still resolves on it and is the same object (test/campaign_facade_inventories/kiro_crew.service.linux.json, 49 names, 39 re-bound by import), every module-level name it bound, private helpers included, still resolves (test_linux_facade.py::test_every_base_module_name_resolves_through_the_facade), and a patch through the facade reaches every owner that reads the name (test_linux_facade.py::test_a_patch_through_the_facade_reaches_every_family_reader, plus the repo-widetest_facade_mirror_guards.py).The take-away check flags the 12 public defs that moved to owners; each is still bound on the facade:
Reader: src/kiro_crew/service/common.py:user_unit_file_path -- release -- restart_command_hint() reads linux.user_unit_file_path() through the facade, which serves linux_unit's function (test_service_controller.py)
Reader: src/kiro_crew/service/controller.py:linger_warning_for_service_account -- release -- install_service() calls linux.linger_warning_for_service_account(), the facade binding of linux_unit's function (test_service_controller.py)
Reader: src/kiro_crew/service/linux_install.py:render_unit -- release -- install() and _user_scope_remedy() import it from linux_unit; the facade serves the same object (test_service.py)
Reader: src/kiro_crew/service/linux_install.py:selinux_refusal -- release -- install() calls it in the same owner; the facade serves it (test_service_selinux.py)
Reader: src/kiro_crew/service/linux_install.py:selinux_start_failure_hint -- release -- install() calls it in the same owner; the facade serves it (test_service_selinux.py)
Reader: src/kiro_crew/service/controller.py:install -- release -- install_service() calls linux.install(), the facade binding of linux_install.install (test_service_controller.py)
Reader: src/kiro_crew/service/linux_install.py:install_apparmor_profile -- release -- install() calls it in the same owner; the facade serves it (test_service_apparmor.py)
Reader: src/kiro_crew/service/controller.py:remove_apparmor_profile -- release -- uninstall_service() calls linux.remove_apparmor_profile(), the facade binding of linux_install's function (test_service_apparmor.py)
Reader: src/kiro_crew/service/controller.py:install_launcher_profile -- release -- controller.install_launcher_profile() calls linux.install_launcher_profile(), the facade binding (test_service_controller.py)
Reader: src/kiro_crew/service/controller.py:remove_launcher_profile -- release -- controller.remove_launcher_profile() calls linux.remove_launcher_profile(), the facade binding (kiro_crew.service.linux.json rebound check)
Reader: src/kiro_crew/service/controller.py:unit_file_carries_managed_marker -- release -- installed_service_has_managed_marker() (read by kirocrew doctor) calls linux.unit_file_carries_managed_marker(), the facade binding (test_service.py)
Reader: src/kiro_crew/service/controller.py:uninstall -- release -- uninstall_service() calls linux.uninstall(), the facade binding of linux_uninstall.uninstall (test_service_controller.py)
Move audit
move_audit.py --base c3f2b27de7 --head 0291d31396(the merge-base and this head):Every other moved unit's AST is identical to the base. Non-move edits:
text=True→**UTF8_TEXTin the system-scopesubprocess.run_systemctl(linux_systemctl.py)linux.pyrow, and systemd writes UTF-8logging.getLogger(__name__)→logging.getLogger("kiro_crew.service.linux")log(linux_install.py)# subprocess-encoding: locale -- ...on thetext=True,line_sudo_run(linux_systemctl.py),_write_unit_via_sudo(linux_install.py)ServiceInstallError.__module__ = "kiro_crew.service.linux"linux_systemctl.py_systemctl,_stale_unit_line,selinux_start_failure_hint,_teardown_scope(×2)Glue, not moves: each owner's docstring and import header; the facade's header imports for the code it keeps, the owner-map comment,
_OWNERSand its import loop,_facade_mirror.install(..., excluded=()), the class swap, the derived__all__and the twoTYPE_CHECKINGmanifests. The split is reproducible from any base by the name-keyed recipe in the campaign'sscratch/S76/recipe/.L36 parity (default diff vs
--minimal, identical+lines): every changed file equal;linux.py138/1778 both. Diff size: 216,804 bytes.Path union
This head (
0291d31396) is the reviewed commit (5768fdb753, plus one docstring fold inlinux_systemctl.py) rebased ontoc3f2b27de7with no conflict; its-U0patch and path set equal the folded commit's.git diff --name-only c3f2b27de7 0291d31396names 16 paths; there are no staged, unstaged or untracked paths.src/kiro_crew/service/linux.py.src/kiro_crew/service/linux_{unit,systemctl,install,uninstall}.py.test/test_linux_facade.py; the facade inventorytest/campaign_facade_inventories/kiro_crew.service.linux.json..github/file-line-cap-baseline.txt,.github/black-baseline.txtand.github/subprocess-encoding-baseline.txt.test/test_spawn_audit.py(BENIGN_SPAWNSrows),test/test_service.py,test/test_service_linux_unit_ownership.py.docs/system-specs/modules/cli.md, and citation edits insrc/kiro_crew/cli.py,test/test_sandbox_slice_encoding.py,test/test_service.py.Tests
test/test_linux_facade.py(new, 22 tests): the facade serves a mirror over exactly thelinux_*modules beside it (excluded == (), nothing divergent); every module-level name the base file bound resolves through it, to each holder's object; a patch through the facade reaches every family module reading 11 shared names (UNIT_PATH,ENV_FILE_PATH,_current_user,_home_for_user,_privilege_prefix,_require_privilege,_sudo_run,_systemctl,_unit_state,kirocrew_bin,time) and its undo restores each one, with a non-vacuity check that those names are read by more than one member; each owner imports only the owners before it, and nothing outside the family imports an owner (each with a planted self-test); the owners log askiro_crew.service.linux; every served non-owner name is in aTYPE_CHECKINGgroup (with a dropped-name self-test);ServiceInstallError.__module__is the facade.test_every_text_write_in_the_linux_service_names_its_encodingandtest_every_teardown_arm_rests_on_the_one_ownership_decisionread the facade joined with every module in_OWNERS;BENIGN_SPAWNSrows follow_current_group,_linger_enabled,_sudo_run,_systemctland_write_unit_via_sudoto their owners.encoding=from_install_file_via_sudo'sos.fdopen; annotate_finish_scope(owned: object); revert oneBENIGN_SPAWNSrow; plant an owner import inservice/common.py; plant an upward import inlinux_unit.py; log under__name__; drop the__module__line; dropkirocrew_binfrom the manifest; remove the facade's class swap.test_linux_facade.py5 runs at-n0and one at-n 3, 22 passed each time; no sleeps, clocks, ports or ordering assertions.local-gate --dry-runselects 1,226 backend files (1,031 of them from the stemcli, which the one-line comment edit incli.pyadds) and 481 frontend files (nowebsite/change), so it was not run whole. Instead: every test naming the family (27 files) plus every src tree-scan guard (299) and the ratchets, 323 files at-n 3: 19,062 passed, 81 skipped, 5 xfailed, 2 failed. Both failures are main's (test_name_grant_facade.py::test_the_patch_scan_reads_every_spelling_and_nothing_else[helper-binding]andtest_backend_cards_advertised.py::test_no_new_runtime_site_gates_a_field_backed_line_on_a_set, both fixed on main by test: clear main's four reds left by #21753, #21598 and later backend edits #22178, which this head includes; on this head they pass, 6 of 6). That run's tree differs from this head only in two comment lines ofgateway_lock.py(since restored to the base) and one docstring line oftest_linux_facade.py; both files were re-run on this head (107 passed). The service suites alone: 809 passed.src/kiro_crew: no issues in 3,307 files.isort --check-only src/kiro_crew test conftest.py xdist_budget.pyandflake8on the changed files: clean. Comment-history, brand, black, subprocess-encoding, agent-sdk boundary, sync-io, feature-map and line-cap gates anddocs_lint.py: clean. The harness-parity gate failed on the gated base for the same reason (ACP_BACKENDS_MEMBER_CAPABILITIES [claude], test: clear main's four reds left by #21753, #21598 and later backend edits #22178) and passes on this head. Semgrep 1.78 with the CI configs and--baseline-commit 2cf3d0d69f(the gated base) over the 11 changed Python files: 0 findings, no parse errors. Installed-mode smoke: a wheel built from agit archiveexport of this head ships all fiveservice/linux*.pymodules, and each imports from the unpacked wheel under the isolatedenv -iwrapper.test_cli_doctor.pyandtest_cli_server_more_coverage.py):linux.py99%,linux_unit96%,linux_systemctl99%,linux_install88%,linux_uninstall97% (floor 80%).Manual verification
N/A — a move of definitions behind the same import path; the service suites that drive install, status, restart and uninstall through mocked
systemctlandsudorun unchanged against the facade and pass (see Tests).Citation edits (L29)
src/kiro_crew/cli.py:795(comment)(service/linux.py)→(service/linux_unit.py): the unit'sRestartPreventExitStatus=is rendered byrender_unit.test/test_spawn_audit.py:1717(comment)service/linux.py::_current_group→service/linux_unit.py::_current_group, beside the re-keyedBENIGN_SPAWNSrows.test/test_sandbox_slice_encoding.py:7(docstring)asservice/linux.pydoes→asservice/linux_unit.pydoes: the UTF-8errors="replace"spawns are_current_groupand_linger_enabled.test/test_service.py:850(docstring)(linux.py:448)→(_env_file_is_untouched_seed): a line cite, already stale at the base, becomes the symbol.docs/system-specs/modules/cli.md:1943"the module docstring inservice/linux.pysits next to the call sites, names the current set" → "names the current set for the whole family"; the owner map is added under## Service Management.Import-path spellings (
kiro_crew.service.linux.<name>,linux.<name>,:func:kiro_crew.service.linux.install``) are unchanged: they still name where the code is reached. The moved docstrings that say "this module" or "the module docstring" read at family level, which each owner's docstring states.References not edited (cost)
src/kiro_crew/gateway_lock.py:128citesservice/linux.pyand:161service/linuxas the module that feedsLIVE_HOLDER_EXIT_CODEintoRestartPreventExitStatus; that is nowrender_unitinservice/linux_unit.py. The file sits inmacos-on-demand.yml's darwin path filter, so a comment edit there would start the 4-shard macOS suite on every push of this PR; left for the batched docs PR.CI path references
None: no workflow path filter or explicit file list names
service/linux.py, and nosensitive_change_review.pyglob matchesservice/linux*.Portability
Cross-Platform Portability flags four moved lines; each is POSIX-only code moved byte-identically, and the systemd backend runs only on Linux:
src/kiro_crew/service/linux_unit.py:UNIT_PATH = Path(f"/etc/systemd/system/{SERVICE_NAME}.service")andENV_DIR = Path("/etc/kirocrew")(baselinux.py:103,:135).src/kiro_crew/service/linux_install.py:os.getuid(),ininstall_apparmor_profileand ininstall_launcher_profile(baselinux.py:1270,:1297).Notes for reviewers
kiro_crew._facade_mirror(L28), not a plain re-export, because the suites patch names through the facade that every layer reads (31 distinct names;_systemctlalone is read bylinux_systemctl,linux_install,linux_uninstalland the facade). The facade keeps the verbs on top of the layering, so no owner needs anything the facade defines.logbindslogging.getLogger("kiro_crew.service.linux"), the base logger object; no test or filter reads the name, the records simply keep it.ServiceInstallErrorkeepskiro_crew.service.linuxas its__module__(an exception's dotted name shows in tracebacks). The moved dataclasses (_UnitState,UninstallReport,_ScopeTeardown,OwnedUnit) report their owner module: none is an exception or enum, nothing reads their__module__, nothing pickles them, and their reprs name the class only.linux_parts/package, the same shape asacp/liveness_*.py; the compound stems keep the related-test selection narrow.__all__is derived (the mirror's shape): it equals the base's star-import set plusTYPE_CHECKING; nothing star-imports this module.Related Issues
Part of #20192
Follow-up: #21320 (the gateway_lock.py comment cites listed under References not edited)
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)