[lewisfab]

Why

The operator on tl-dell (2026-10-21) found that the dashboard's two deployment words mean something other than what they say:

What does "deployment current" actually mean? To me, that means there are no updates available. Check for update means ONLY to check.

They were right on both counts:

• "deployment current" only compared the running build with this box's own install record. The daemon never looks at hestia main, so it read "current" while dashboard(feed): event names overlap the detail column and repeat in it #1359 sat merged and undeployed. This is deployment gauge: 'current' names the wrong referent — binary==manifest reads as binary==main (23-commit lag invisible, incl. rust + dashboard fixes) #438, open since August.
• "check for updates" started a full deploy cycle: sync, then build, install and restart if main had moved. dashboard: auto-update toggle, "check for updates", dated stale-aware "updated" stamp #1334 (also from tl-dell) made it that way deliberately: with the timer off, nothing else could find out whether main had moved. Even the CLI's hestia-deploy --check wasn't check-only, because it self-updated ~/.local/bin/hestia-deploy.
• Nothing checked on a schedule. With auto-update off, a box never learned about updates.

What the operator asked for:

1. Make the status say what it means, including when it last checked.
2. Check automatically every 4 hours, but install nothing unless auto-update is on.
3. "check for updates" should only check, and should turn into "update" when there's an update.

What

Deploy script (deploy/from-main/hestia-deploy.sh)

• Every cycle that syncs records its verdict in $HESTIA_HOME/deploy-check.tsv, as <state> <checked_at> <running> <latest>. The states are checking, up-to-date, available and failed, and the file is written atomically.
  • A full cycle writes the verdict too, and rewrites it as up-to-date after DEPLOYED.
  • A write failure logs a warning and never stops a deploy.
• --check no longer self-updates the script, and a hold no longer skips it. A hold protects builds and restarts, and a check does neither.
• A check that dies before reaching a verdict (fetch failed, no checkout) records failed.
• A full cycle installs the check units if the box has the deploy service but not the check units. That's how existing boxes get the check. The check timer is enabled only on first install, so an operator who turns it off later isn't overridden.

New units

• hestia-deploy-check.service: hestia-deploy --check, with SuccessExitStatus=3 because "update available" is a result, not a failure.
• hestia-deploy-check.timer: 02/4:17, two hours off the deploy timer's marks so the two never contend for the lock.
• deploy/fleet/install.sh installs both and enables the check timer on first install. The deploy timer stays off by default, as before.

Daemon

• DeploymentHealth.check holds {state, at, latest}, read from the file against the running build:
  • available for a build that has since been installed reads up-to-date, compared by commit (Deploy must update itself: frictions the upgrade-path harness found (fresh-host bootstrap, atomic set, tag upgrade, unstable build ids, seeds, units) #1250), not by abbreviation;
  • up-to-date for a build that is no longer the one running reads unchecked;
  • a check still "checking" after 30 minutes reads failed.
• DeploymentHealth.check_capable is true when the check unit is installed. It's read from disk, so the dashboard poll still spawns no process (A visible dashboard tab stalls every request ~1.2 s every 20 s: /api/agents runs the inventory with a blocking Command::output() inside an async handler, and the 300 s gate-watch pass runs it under the state lock #1183).
• POST /api/operator/deployment/check:
  • it's behind the operator gate and takes no body;
  • it is witnessed (deployment_check_requested) before the trigger, and the outcome record says whether it was witnessed;
  • it writes requested so the UI shows "checking…" immediately;
  • it starts only hestia-deploy-check.service.

Dashboard header

header	button
● up to date · checked <time>	check for updates (checks only)
! update available · checked <time>	update
● checking for updates…	(disabled)
! update check failed · <time>	retry check
● not checked yet / ● not checked since this build	check for updates
! install incomplete (the old "stale")	update
● update status unknown (no check unit: macOS, or a box before its next update)	update

The tooltip lists the running build, main's build at the last check, the check schedule and the last deploy run. The words "deployment current" are gone.

Rolling out to an existing box

The first update after this merges installs the new script but runs the old one, which has already been read into memory, so it doesn't install the check units. The new daemon then shows ● update status unknown with an update button. One more update installs and enables the check timer. After that, the header is driven by the check. Alternatively, re-run deploy/fleet/install.sh.

Tests

• New deploy/from-main/check_mode_test.py runs the real script in --check against a throwaway HOME, local bare origins and a stub daemon, with no network and no real unit.
  • It checks the up-to-date and available verdicts, no self-update, a hold not stopping a check, and an unsyncable check recording failed.
  • Run against main's script, 8 of its 12 checks fail. That confirms the old --check self-updated, recorded nothing, and was stopped by a hold.
• deploy/fleet/deploy_supervisor_step_test.py now also checks that the check units are installed, that the check timer is enabled on first install and left alone on a re-run, and that the deploy timer still isn't enabled.
• New Rust tests:
  • deploy_check_reports_the_supervisors_verdict_against_the_running_build
  • deployment_check_starts_the_check_unit_and_never_the_deploy
  • deployment_check_in_flight_only_while_requested_or_checking
• Existing checks, all passing: tools/dashboard_deployment_update_contract_test.py (now with 7 check assertions), operator_surfaces_spec_test.py, operator_surfaces_ratchet_test.py, no_path_literals_test.py (the new units registered, the check service at 1 literal), dashboard_no_undef.mjs and the other dashboard contract tests.
• cargo test --lib (pinned web4 31990db7): 1256 passed, 0 failed, 2 ignored. The three new tests were also run by name and pass.
• Not tested:
  • the endpoint and header against a live daemon, because I didn't want to replace this box's governing daemon with an unreviewed build;
  • the check units under real systemd;
  • macOS, where the dashboard falls back to the "update" button with an honest "update status unknown".

Review gate

surface: operator_deployment_check   act: start the check-only supervisor run (sync deploy checkout, write deploy-check.tsv)
S: low/reversible [construct: hestia-deploy --check: no build, no install, no restart, no self-update; deploy-check.tsv is overwritten by the next check]
R: pass [construct: operator_gate route_layer on operator_surface]   W: pass [construct: current_operator_context + attach_operator_provenance]
O: pass [construct: deployment_check_requested append_chain before write_deployment_update_file / deployment_trigger_output]   A: pass [construct: deployment_check_requested + deployment_check_triggered|_trigger_failed, with `witnessed` in the reply]
V: n/a (no irreversible act; installing stays with operator_deployment_update)
verdict: PASS

surface: hestia-deploy full cycle (timer / update button)   act: install + enable hestia-deploy-check units where the deploy service is installed
S: low/reversible [construct: install_check_units; the timer only runs --check; systemctl --user disable undoes it, and a later cycle does not re-enable]
R/W: unchanged (same supervisor, same operator-originated or timer trigger)   O: pass [construct: runs after sync, before the BIN guard and any build]
A: pass [construct: deploy.log lines "installed the update-check units" / "enabled hestia-deploy-check.timer"]   V: n/a
verdict: PASS

Addresses #438: the header now answers "is the daemon current with main?" from a dated check. It doesn't add #438's second axis (lag size and whether it touches core/src). Follows #1334.

🤖 Generated with Claude Code

[dp-web4]

Reviewed current head: separates update check from deployment and surfaces checked/version state with scheduled check cadence. Three CI workflows green. No blocker found, contingent on check-only path truly not installing/restarting (as specified).