[lewisfab]

Why

The operator on tl-dell asked: "on a BRAND NEW install, will that code have to be run or will it just work from the getgo?" It would not just work. The deploy supervisor that the dashboard's update button starts (hestia-deploy.service) is a separate once-per-box install from deploy/from-main/README.md, and no installer runs it. So every box set up with deploy/fleet/install.sh gets an update button that can only fail with Unit hestia-deploy.service not found (#791: Nomad 2026-09-01, tl-dell 2026-10-16).

Companion to #1334, which adds the dashboard's auto-update toggle and "check for updates" button and hides both where no supervisor is installed. This PR is what makes them present on a fresh box. The two PRs are independent and can merge in either order.

What

New step_deploy_supervisor in deploy/fleet/install.sh, run after the workspace marker:

• Checkout install (a resolved HESTIA_WORKSPACE) with git and cargo, on Linux:
  • clones hestia and web4 into $HESTIA_HOME/deploy over https, since the units run without an ssh agent;
  • installs ~/.local/bin/hestia-deploy and both units, with HESTIA_WORKSPACE rendered into the service;
  • reads the unit back, then runs daemon-reload.
• The timer stays OFF by default. Nothing builds or restarts until the operator clicks update or turns auto-update on. HESTIA_AUTO_UPDATE=1 arms it at install time. A re-run never disarms a timer the operator turned on.
• Skips, and says why:
  • Release (curl | sh) installs: they track releases, not main, and are updated by re-running the installer. Converting them to main-tracking is a choice this step doesn't make for them.
  • Missing git or cargo.
  • macOS: deriving the launchd agent's binary path isn't automated yet.
  • HESTIA_SKIP_DEPLOY is set.
• deploy/from-main/README.md: a note at the top of the Linux install section. The manual lines stay as the reference and as the opt-in route for release installs.

Questions for review

1. Release installs. Should a release box get a "check for updates" that re-runs the installer for the latest release, instead of being skipped? That would be a different supervisor, so I've left it out of this PR.
2. Default off. It matches the operator's choice here: hestia moves daily, so scheduled deploys of unreviewed main are opt-in. Say if the fleet default should differ.

Tested

• New deploy/fleet/deploy_supervisor_step_test.py (picked up by tools/ci_discovery.py bare): 17 checks. It runs the step itself in a temporary HOME, with stub git, cargo, systemctl and uname, against the real shipped hestia-deploy.{sh,service,timer}. It covers:
  • the files installed, with the workspace rendered;
  • nothing asking systemd to enable the timer by default;
  • opt-in enabling it, and an armed timer left armed;
  • each skip arm, with its message.
• Existing: install_version_test.py, tools/no_path_literals_test.py, tools/public_boundary.py, tools/ci_test_coverage_test.py, tools/shebang_exec_bit_test.py, and the deploy/from-main/*_test.py files all pass.
• Not tested: a full install.sh run on a real fresh box. On this box it would replace the main-built daemon with a release binary.

Review gate

surface: deploy/fleet/install.sh step_deploy_supervisor   act: install a supervisor that can deploy hestia main to this box
S: med/reversible [construct: timer off by default; units removable; nothing builds until an operator act]
R: n/a (operator-run installer, same trust as the rest of install.sh)   W: n/a (no daemon surface; the deploy act itself stays behind operator_gate / the operator's own timer choice)
O: pass [construct: prerequisites (checkout, git, cargo, Linux) checked before the first write]   A: n/a (installer output; the deploy acts it enables are witnessed by the daemon)
V: present [construct: hestia-deploy.sh preflight_gate + rollback, unchanged]
verdict: PASS

🤖 Generated with Claude Code

[dp-web4]

NOVA review follow-up (2026-10-17): HOLD: installer systemd Environment= path rendering mishandles spaces/special chars and custom HESTIA_HOME may not propagate into installed unit. Verify parsed unit with systemd-analyze and add non-default-home/path tests.

[dp-web4]

Addressed Nova's HOLD in 5e5c552 (pushed onto this branch, no force):

• Path rendering:
  • The new systemd_env_line writes Environment="HESTIA_WORKSPACE=…", escaping \ and " and doubling %.
  • awk substitutes it from the environment, so sed metacharacters in the path are harmless.
  • The read-back uses grep -F.
  • Where systemd-analyze is installed, it has to parse the unit without an environment warning.
  • The test models systemd's parser and checks that six awkward workspace names round-trip with no stray variable. It also runs systemd-analyze verify directly. On the previous commit, "My Projects" reached systemd as …/My, and the step still printed "the dashboard update button works".
• Custom HESTIA_HOME: the shipped deploy unit, hestia-deploy's clone default, and the daemon unit this installer writes are all bound to ~/.hestia. The step now skips a non-default HESTIA_HOME and names the manual route, rather than cloning into one home and deploying into another. Making the units follow HESTIA_HOME would be a larger change across all three.
• Not changed, but the same class: install.sh's daemon unit heredoc renders Environment=HESTIA_WORKSPACE=${HESTIA_WORKSPACE} unquoted (main, line ~241). systemd_env_line could fix it in a follow-up.

— cbp-claude