acpmux enroll: an update step that keeps a machine's daemon current

Merged
TE
25d ago
+1568-22

Leo asked: "and why dont i see that the acpmux things are there? how is our setup flow anyways? like cmux-next remote and whatnot" and "plus the fucking qr code or whatever easy setup for my phone just like codex".

This is one of four PRs that make "add a machine" one or two clicks with no terminal step:

  • this one: the daemon a machine gets is kept current;
  • #25939: the app's checklist row for this step (lands after this one);
  • #25838: Add Device also lists ~/.ssh/config hosts;
  • #25823: an "Add Machine…" row in the environment picker, and New Cloud VM… in Add Device.

What changes

Enroll keeps the daemon current: a new update step.
acpmux host enroll (what Add Machine and Add Device run) and host doctor now have an update step, right after daemon and before harness.

  • Linux host without acpmux-update.timer. Before, enroll only installed the timer when it restarted the daemon. A host whose daemon already ran this build was never given the timer, so it fell behind as soon as the next build landed. Now:
    • enroll / doctor --fix install the timer (host_auto_update::install_script) under the host's update lock, then read it back as fixed.
    • doctor without --fix reports warn, with the fix. It changes nothing.
  • Already updates itself:
    • Linux with acpmux's own timer enabled and running: ok, "updates itself every 15 minutes". A stopped or disabled one is a warn that --fix starts.
    • A Mac: ok (the app moves it to its build on connect).
    • A cmux Cloud VM (/etc/cmux/vm-kind): ok (cmux link machine update --to-bundled on connect, CloudMachineUpdates).
  • Left alone, with a reason:
    • ~/.acpmux/no-auto-update: skip, and it stays off, on every kind of host (checked first).

    • cmux's own acpmux runs on the host (the app-installed cmux-tui, which the install and daemon steps already leave alone): skip. It is updated with cmux, not by the timer, whose service runs ~/.local/bin/acpmux.

    • Not Linux (an unknown or failed uname too), or /etc/cmux there but unreadable: warn, and nothing is written.

    • No user systemd: warn.

    • A user manager that does not linger stops at logout and takes the timer with it. Without --fix, a timer there is a warn. With --fix, the install asks loginctl enable-linger under the lock, as host setup does, and writes nothing if that is refused.

    • A unit path this user can't search, or one under a directory they can't search: the probe can't say what is in it, so it is not checked, and nothing is written.

    • An XDG_CONFIG_HOME other than ~/.config, in the shell or the user manager: warn. systemd would read units from there, while install_script writes ~/.config/systemd/user.

    • A unit someone else wrote: warn. Nothing is written. Enabled or not, the timer's units count as acpmux's own only when:

      • each file in ~/.config/systemd/user has the exact text install_script writes;
      • each unit the manager knows loads from there, with no DropInPaths;
      • no acpmux-update.service.d, acpmux-update.timer.d, acpmux-.service.d or acpmux-.timer.d directory exists in any path that systemd-analyze --user unit-paths lists, or in the XDG and system defaults.

      A type-wide service.d/timer.d drop-in counts too, on disk or in DropInPaths, unless this user neither owns nor can write the drop-in, its directory or the directory above. Distros ship those (Fedora's 10-timeout-abort.conf). The check is on ownership and writability, not on how the path is spelled. The paths read are systemd-analyze --user unit-paths, the running manager's UnitPath, and the XDG and system defaults. Paths are never globbed, and the probe uses no sed or tr. A unit that is not a regular file (a FIFO, a symlink, a dangling link) is foreign. The units count as foreign if UnitPath's space-separated list could hide a path with a space in it.

    • The install runs the same probe again under the host's update lock. It installs only when that probe says it read the manager and its units to the end. It writes nothing if it now finds such a unit or drop-in, or another XDG_CONFIG_HOME.

    • A probe that did not read to the end, first or under the lock: warn, and nothing is written. That includes UnitPath or systemd-analyze failing or answering nothing. The probe's words count only after its own begin line, so a login banner is not read. Its checked must be its last line, and nothing about the units counts without it.

    • Another update holding the lock: warn.

    • The step's own read of whose daemon runs gets no full answer: warn, and nothing is written. That covers a dropped connection, a failed exit with more than the trailing config read missing, and an answer in which no daemon reports its status. It never guesses "acpmux's own".

  • The report stays ok with a warn here. A machine that works but does not self-update never fails the add.

The app's checklist row ("Keep it up to date") is #25939. Until that lands, base shows this step after the last done row, labelled by its raw name update.

Where things stand (audit summary)

StepBeforeAfter this PR
Daemon kept current on a Linux hostOnly if the daemon happened to restart during setup; else a terminal acpmux host updateenroll installs acpmux-update.timer
Daemon kept current on a Mac / Cloud VMthe app updates on connectunchanged, now reported in the checklist

Takes back #22823: not a revert. This PR extends the README lines #22823 wrote: the enroll row gains the new update step, and the timer paragraph names host enroll as a third installer.

Size

1590 changed lines, 1084 of them tests. The code is 506 lines. The tests are mostly the shell probe's cases, which I kept with the probe rather than splitting them out.

Risk

Medium-low. Every install goes through the existing install_script and the host update lock that host setup and host update already use. No new remote script beyond a read-only probe. Doctor without --fix stays read-only (tested).

Tests

  • cli::host_enroll::update_step::tests: each kind of host; cmux's own acpmux never gets the timer; doctor read-only; install fenced under the lock; a foreign unit at install; an enabled timer acpmux did not write; a stopped timer; a timer that does not start after install; lock held.
  • update_step::tests::probe_in_a_shell: the real probe script, run by sh against a fake systemctl: own and running; stopped, disabled, enabled-runtime, half written; and foreign whether enabled or not (a drop-in on either unit, a drop-in directory on disk or in a path systemd-analyze lists, a unit in /etc, only loaded, only on disk, other text). A type-wide drop-in this user cannot change does not count, running or stopped, listed by the manager or on disk; but a file in that directory they can change, a dot-file included, or a link there that points nowhere, is foreign (a_hidden_or_dangling_type_wide_drop_in_is_foreign). One they own or can write does count: read-only, spelled /usr/../home/..., or in a path only the running manager names (including one with a space or glob characters in its name). A unit file of either name in any unit path but ~/.config/systemd/user is foreign too, since a reload would load it over acpmux's. Beside a drop-in for this unit, the unit is still foreign.
  • probe_in_a_shell::the_running_managers_unit_paths_are_read (also paths with spaces), the_install_writes_nothing_under_another_xdg_config_home, the_install_writes_nothing_when_the_manager_does_not_answer; an_unread_unit_path_list_is_never_checked; update_step::tests::a_probe_that_did_not_read_to_the_end_installs_nothing, the_probes_words_are_framed.
  • probe_in_a_shell::another_xdg_config_home_is_read_from_the_shell_and_the_manager and update_step::tests::another_xdg_config_home_is_said_and_nothing_is_written.
  • probe_in_a_shell::a_unit_path_that_cannot_be_searched_is_never_checked, an_unreadable_off_mark_is_never_checked (~/.acpmux that cannot be searched), the_install_needs_a_lingering_manager; update_step::tests::a_manager_that_does_not_linger_is_said (also: a running timer that does not linger, with --fix, gets lingering through the guarded install under the lock).
  • probe_in_a_shell::the_install_writes_nothing_beside_a_drop_in and update_step::tests::a_drop_in_found_under_the_lock_stops_the_install: the guarded install.
  • cli::host_enroll::tests::the_update_step_runs_between_the_daemon_and_the_harness: the order the steps run and print in, a failed daemon skipping it, and the cmux-own path handed to the step.
  • cli::host_enroll::tests::an_update_step_that_cannot_tell_whose_daemon_runs_writes_nothing: the daemon step sees the app's daemon, then the next probe fails, with an empty answer, a whole-looking standalone one, or a whole one with no daemon status. The step warns and never runs.
  • Runs at this head on a Linux testbox: cargo fmt --check; cargo test -p acpmux --lib (1478 passed; the one failure, agent_tools::tests::own_servers_run_under_the_daemon_prefix, is base's: neither file differs from base, and base's resolve lists an acpmux-mcp server that test does not expect); clippy -D warnings, clean.

Checked live: on a GCP lane VM, host doctor showed the daemon one build behind, while acpmux-update.timer (installed earlier by a host update) was enabled and had run 3 minutes before. This step turns that into an ok row, and installs the timer where it is missing.

Agent session: agent session

🤖 Generated with Claude Code