maestro/docs/RESTART.md

Restart and upgrade contract

Maestro is upgraded in place: the operator reinstalls the binary and systemd restarts the daemon under every browser tab and TUI that is attached to it. tmux keeps the sessions alive across that (see docs/INSTALL.md), but clients lose their sockets. This document is the contract for what a client does about it — what the daemon publishes, how a client tells a restart from a blip, and what the user sees while it happens.

What the daemon publishes

GET /api/info carries two fields beyond identity and presets:

field	meaning
build	{ commit, commit_date, dirty } — the commit the binary was compiled from
instance	uuid regenerated on every daemon start

build is stamped at compile time by crates/maestro-daemon/build.rs, which runs git in the checkout it is compiled in. The Nix build has no .git in the crane-filtered source tree, so flake.nix passes the flake's own revision as MAESTRO_BUILD_COMMIT / MAESTRO_BUILD_DATE / MAESTRO_BUILD_DIRTY. A build with neither source reports empty strings — clients render that as "unknown release" and fall back to instance alone.

instance is the one that never goes missing. It says this process, so two replies that differ on it are two runs of the daemon, even when the commit did not change (a plain systemctl restart, or a crash).

How a client reads them

Three verdicts, from comparing the reply before an outage with the one after (compareIdentity in web/src/daemonLink.ts, mirrored by crates/maestro-tui/src/daemon_link.rs):

• upgraded — both commits are known and differ. New server code.
• restarted — commits match (or are unknown) and instance differs.
• same — neither changed; the socket blipped, the daemon never moved.

Only upgraded is special. A browser tab is holding a bundle that the upgraded daemon no longer serves, so it reloads the page rather than driving new server code from an old bundle. The TUI is its own binary — a reload would not replace it — so it stays up, reconnects, and says which release it is now talking to; the user restarts maestro tui when they want the new client.

What the user sees

The status indicator lives in the sidebar footer, left of the spawn button, in both clients. Its colour is the link state, and it names the running release — commit hash and commit date — on hover (web) or in the status bar (TUI).

state	colour	meaning
connecting	amber	first probe hasn't landed
online	green	daemon answered; same process, or a resolved new one
reconnecting	amber	socket dropped, still inside the grace window
down	red	unreachable past the grace window — the UI blocks
updating	red	answered on a new commit; the page is reloading

updating is web-only, because reloading is web-only. The TUI goes straight back to online after an upgrade and puts updated: <hash> (restart tui) on its status bar instead, until the user restarts it.

The restart overlay is up for exactly down and updating. It is not dismissable and it swallows the app's keyboard shortcuts: everything behind it would act on a daemon that is not there. In the TUI the quit binding still resolves, so a blocked client is never a trapped one. It clears itself the moment a probe succeeds — there is no "retry" button, because the client is already retrying.

Timing

• Grace window — 1200 ms between the socket dropping and the overlay appearing. A wifi hiccup or a laptop waking up should not throw a modal.
• Poll cadence — GET /api/info every 700 ms while unreachable, flat, not backed off: a restart takes a second or two and the point is to unlock as soon as it is over. The events socket keeps its own exponential backoff for the session stream; the two are independent, and the probe is what decides state.

The events socket dropping is the trigger, not a timer: the daemon cannot warn anyone it is about to die, so its socket closing is the earliest signal there is. A reconnect of that socket does not by itself clear the state — only a probe does, because the socket carries no identity and reconnecting to an upgraded daemon must reload rather than resume.