kandev/docs/decisions/2026-07-31-system-service-user-continuity.md

# ADR-2026-07-31-system-service-user-continuity: Preserve System Service Identity Across Reinstallation

**Status:** accepted
**Date:** 2026-07-31
**Area:** backend, cli, security, operations

## Context

`kandev service install --system` currently derives its service account from the process that runs
the installer. A command invoked through `sudo` normally sees the non-root `SUDO_USER`, while the
same command invoked from a root login resolves to root. Re-running installation after a package
upgrade can therefore silently rewrite an existing non-root service as root while leaving
`KANDEV_HOME_DIR` and its managed repositories owned by the original account.

Git correctly rejects a repository owned by another account when the process runs with greater or
different authority. The new managed-checkout origin reconciliation made that latent mismatch
visible during every launch and resume: `git remote set-url` exits 128 before an agent starts. The
same identity drift can affect database access, secrets, generated files, executor credentials, and
any future operation, so treating only the Git symptom would leave the underlying operational and
security boundary broken.

Kandev also writes `<KANDEV_HOME_DIR>/service/install.json`. That file is intentionally readable and
writable by the service account. A privileged installer cannot trust it as the authority for a
future run-as account: a compromised service could edit the file to request a more privileged
identity before an administrator reruns installation.

## Decision

System-service identity is durable installation state. `kandev service install --system` resolves
the target account in this order:

1. An explicit `--run-as <user>` supplied for this installation.
2. The account in an existing root-controlled, Kandev-managed systemd unit or launchd plist.
3. A non-root `SUDO_USER` for a first installation.
4. Otherwise no implicit account: installation fails and requires `--run-as`, including the
   explicit `--run-as root` choice.

Only an existing definition carrying Kandev's managed-service marker participates in preservation.
The installer parses the effective account from the root-controlled unit or plist, validates that
the account exists, and rejects malformed or contradictory managed definitions before writing.
Service-owned install metadata remains useful for status and update compatibility checks, but it
may only corroborate the selected account; it cannot select or elevate it.

Before replacing or restarting a system service, the installer validates the system Kandev home:

- If the home does not exist, installation fails with pre-create and ownership guidance. Kandev
  does not create a privileged system data root implicitly.
- If it exists, its owner UID must match the selected account's UID.
- A mismatch fails before the service definition is changed or restarted and reports the current
  owner, selected account, and explicit recovery choices.

Kandev does not recursively chown an existing data tree, add `safe.directory=*`, or suppress Git's
ownership check. An operator intentionally migrating service identity must explicitly select the
new account and reconcile the home ownership according to local policy before installation can
complete. This keeps destructive or privilege-changing filesystem operations outside an otherwise
routine package update.

`--run-as` is valid only with `service install --system`. User services continue to run as the
calling user and do not expose an account override.

## Consequences

- Reinstalling after a Homebrew, npm, or bundle upgrade cannot silently change an established
  system service from a non-root account to root merely because the command was run from a root
  shell.
- First-time root-shell installs become explicit. Operators who genuinely want a root service use
  `--run-as root` and receive a reviewable command history.
- Existing installations that already run as root remain root when their managed definition is
  valid; continuity does not force an unrelated migration.
- A service/data ownership mismatch is detected before restart, instead of appearing later as an
  opaque database, Git, or secret-store failure.
- Service-owned metadata cannot be edited to cause privilege escalation on the next privileged
  install.
- Deliberate account migration requires an additional operator-managed ownership step and may need
  ACL-specific handling on unusual deployments.

## Alternatives Considered

### Continue deriving the account from the current shell

Rejected. The account running a package update is not durable service configuration, and root
logins lack the `SUDO_USER` signal that happened to make earlier installs work.

### Trust `service/install.json` as the preserved identity

Rejected. The service account owns that file. Letting it choose the account written into a
root-controlled service definition would create a privilege-escalation path.

### Automatically chown the Kandev home when the account changes

Rejected. Recursive ownership changes are destructive, can cross operator-managed mount or
symlink boundaries, discard intended ACL semantics, and turn a typo into a broad data mutation.

### Add a broad Git `safe.directory` exception

Rejected. That would mask service identity drift, weaken Git's repository-ownership protection,
and leave non-Git files under the wrong operational authority.

### Always run system services as root

Rejected. It expands task and integration authority unnecessarily and breaks existing non-root
installations whose data and credentials belong to their established service account.