Skip to content

fix(service): bake KIROCREW_HOME into the installed service - #32493

Open
SaRedfiche wants to merge 1 commit into
kirodotdev:mainfrom
SaRedfiche:crew/kirocrew-helper/service-home-env
Open

SaRedfiche wants to merge 1 commit into
kirodotdev:mainfrom
SaRedfiche:crew/kirocrew-helper/service-home-env

Conversation

@SaRedfiche

@SaRedfiche SaRedfiche commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: kirocrew service install run from a shell with KIROCREW_HOME set installs a service that runs that same crew, instead of silently starting a new, empty one in ~/.kiro/crew.

A user with export KIROCREW_HOME=$HOME/crew-data runs the gateway happily, then runs kirocrew service install for 24/7 use. The unit carries HOME, PATH, the locale, KIROCREW_PORT and KIROCREW_KIRO_BIN, but no KIROCREW_HOME. The service resolves the default ~/.kiro/crew and starts a fresh crew there: signed out, no chats, nothing printed.

Why it matters

Keeping the crew up after logout is the natural next step after a custom data home works. Today that step swaps the user's crew for an empty one, and nothing on screen or in the logs connects the two. It hits every Linux and macOS user who relocated their data home.

Not a goal

What changed (motivation → approach → change)

The service never learned which crew to run, so it ran the default one. service_environment() already copies KIROCREW_PORT and KIROCREW_KIRO_BIN from the installing shell into the one dict both the systemd unit and the launchd plist render from. It now copies KIROCREW_HOME the same way, only when it is set.

Installer's KIROCREW_HOME Baked into the service
unset or blank nothing (same as today)
/srv/crew-data /srv/crew-data, untrimmed, exactly as config_dir() reads it
crew-data (relative) made absolute, because the service runs from another directory
~/crew-data kept as typed; config_dir() expands it against the baked HOME, which stays right under sudo -H

The KIRO_API_KEY warning used to add "KIROCREW_HOME is set here but is also not inherited". That claim is false now, so the caveat says something true instead: a service installed from a shell with another value, or whose override file (/etc/kirocrew/kirocrew.env on Linux) sets its own, runs a different home, so confirm the home. It shows on install and in kirocrew doctor, in both the KIRO_API_KEY note and the inherited-variables note (service/inherited_env.py), which share the helper, since neither command can see which home the service really starts with. The cli spec names KIROCREW_HOME among the installer-derived values and describes the caveat.

Backwards compatibility

Compatible: with KIROCREW_HOME unset the dict, the unit and the plist are byte-identical to today. An existing install keeps its old unit until the next service install.

Removes nothing: the warning keeps its caveat on the same condition (KIROCREW_HOME set); only its wording changes, and no function or key is removed.

Tests

  • test_propagates_crew_home_only_when_set: absent when unset or empty, copied untrimmed when set.
  • test_relative_crew_home_is_absolutized_and_tilde_kept: a relative home is made absolute; ~/... is kept verbatim.
  • test_crew_home_reaches_both_rendered_service_definitions: the value, with a space in it, reaches the plist's EnvironmentVariables and the unit's quoted Environment= line.
  • test_custom_home_caveat_only_when_home_is_overridden additionally pins that the caveat no longer says "not inherited" and names the override file.

Proof: PROVEN test/test_service_environment.py::TestServiceEnvironment::test_crew_home_reaches_both_rendered_service_definitions, test/test_service_headless_api_key.py::TestHeadlessApiKeyWarning::test_custom_home_caveat_only_when_home_is_overridden (head 16c467b)

Locally: test/test_service*.py, test_env_file_bom.py, test_linux_facade.py, test_doctor*.py and test_service_inherited_env.py pass (1262), the two changed files pass 3 repeats and a reversed order, as do mypy --platform linux, flake8, isort, pinned black on the changed lines, semgrep on the diff, the flake-pattern ratchet, and the repo's check_* scripts that run without CI inputs.

Manual verification

N/A — unit coverage renders both real service definitions end to end. I did not run a live systemctl / launchctl install.

Related Issues

Closes #32366

Related: #32362 (installer-side KIROCREW_HOME, out of scope here).

Related: #11289 (Windows Task Scheduler service) does not render from service_environment() and refuses an install whose KIROCREW_HOME is not persisted with setx, so Windows needs nothing here. It reformats the same caveat line this PR rewords in service/common.py; whichever lands second takes a one-line rebase.

Sibling sweep

Swept: git grep -n 'environ.get("KIROCREW_' -- src/kiro_crew/service/
Sibling: src/kiro_crew/service/common.py:198 -- not affected -- KIROCREW_KIRO_BIN is already baked
Sibling: src/kiro_crew/service/common.py:207 -- not affected -- KIROCREW_PORT is already baked
Sibling: src/kiro_crew/service/macos.py:252 -- not affected -- KIROCREW_SERVICE_BIN picks the program path at install, never needed at runtime
Sibling: src/kiro_crew/service/controller.py:129 -- not affected -- Windows has no managed service on main (install prints the unsupported-platform message); #11289's Windows service handles the home by refusing an unpersisted one

Pattern harvest

Not generalizable: the set of variables a managed service must inherit is a per-variable product decision (credentials are deliberately excluded), so no lint can tell a missing key from an intentionally omitted one.

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

@SaRedfiche
SaRedfiche requested review from a team and KiroCrewCaptain as code owners November 7, 2026 18:01
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Nov 7, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 8, 2026
@SaRedfiche
SaRedfiche force-pushed the crew/kirocrew-helper/service-home-env branch from af6b381 to 40a0d5d Compare November 8, 2026 19:38
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 8, 2026
`kirocrew service install` captured KIROCREW_PORT and KIROCREW_KIRO_BIN
from the installing shell but not KIROCREW_HOME, so a user with a custom
data home got a service that resolved the default ~/.kiro/crew and
started a new, empty, signed-out crew there with no warning.

service_environment() now bakes KIROCREW_HOME when it is set, exactly as
config_dir() reads it: made absolute, untrimmed, and with a leading "~"
kept for the service to expand against the baked HOME (right under
`sudo -H`). Both the systemd unit and the launchd plist render from that
dict. The KIRO_API_KEY warning's
caveat no longer claims the home is not inherited; it asks the operator
to confirm the service's home, since a unit from another shell or an
override file can still set a different one. Default installs are unchanged.

Closes kirodotdev#32366
@SaRedfiche
SaRedfiche force-pushed the crew/kirocrew-helper/service-home-env branch from 40a0d5d to 16c467b Compare November 9, 2026 23:43
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 10, 2026
@SaRedfiche

Copy link
Copy Markdown
Contributor Author

Hi maintainers, could someone approve the workflow runs for this fork PR? It's rebased onto current main (head 16c467b), merges cleanly, and the local tests and proof script pass. Thanks!

This branch has not been deployed

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

Labels

fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

kirocrew service install drops KIROCREW_HOME: the service starts a new, empty crew in ~/.kiro/crew with no warning

1 participant