Tell the operator when a newer Colonizer is out, and update without losing colonies

[ParallelEntrepreneur]

Closes #45.

A build now knows where it came from, the mothership notices when a newer release is tagged and says so in the UI, and it can apply that release without the colonies underneath it noticing.

What changed

Know what's installed. crates/colonizer/build.rs stamps git describe --tags, the commit, whether the tree was dirty, and a build time (honouring SOURCE_DATE_EPOCH, so a release build is reproducible). Git failures produce empty strings, never a failed build. GET /api/version reports it, colonizer version prints the one-line form, and the startup banner carries it.

Check for updates, on by default. Sixty seconds after start and every six hours after, the mothership asks GitHub for the latest release of Colonizer-dev/harness and compares it with its own version. The request carries nothing about the install. A switch in Settings turns it off, COLONIZER_UPDATE_CHECK=off pins it off, and with checking off no request is made. A build from an untagged commit reports itself as a development build and is only told about releases newer than the last tag it contains.

The UI shows the installed version in Settings → Updates, a dismissable banner when a release is available, the release notes, and an Apply button with live progress. When apply is refused, it says why.

Versioned install layout. Both installers and the in-app updater now install into <data>/versions/<version>/ and atomically swap an app symlink (mv -T on GNU, ln -sfn fallback elsewhere), migrating an older real app directory in place. This is the part issue #45 calls out as unsafe by construction: colonies bind-mount vendored plugins read-only straight out of the app directory, so replacing it under them empties what they are reading.

Applying an update refuses while any colony is publishing (and while another apply is in flight, on an unsupported platform, or from a source checkout), downloads and SHA256-verifies into a staging directory so a failed attempt changes nothing, installs into the new version directory, swaps the symlink, then persists sessions, shuts the mesh children down cleanly, and re-execs through the link. sessions::recover reconnects each colony that was running. colonizer update does the same from the command line.

The rule that makes this safe: nothing still in use is ever deleted. A directory being replaced or retired is renamed aside first — a bind mount follows the inode, so a colony reading from it keeps working — and only the delete is deferred, until the app link no longer resolves into it, no colony bind-mounts out of it, and no running process executes from it. Deferred leftovers get dot-prefixed names that the next installer run and the mothership's startup prune both reclaim once nothing holds them.

Docs: a new docs/updates.md, plus the four endpoints in docs/protocol.md and the layout in docs/install.md and the README.

How it was verified

• cargo test --workspace: 143 passed, 0 failed, including unit tests against a fake GitHub API and an end-to-end install against a local fake release server. cargo check --workspace --all-targets is clean.
• npm run build in web/ (tsc --noEmit && vite build) passes.
• The install scripts were exercised in a sandbox with real mount --bind standing in for a colony's read-only mounts, asserting the mounted file stays readable through every destructive step: fresh install, same-version reinstall, two upgrades without a restart, legacy-directory migration, crash/leftover recovery, the macOS path with a mv that rejects -T, and the version-token matrix. shellcheck reports nothing new against baseline.
• colonizer version and --help run and print correctly.

Reviewing found several real defects along the way, all fixed and re-verified, each reproduced before the fix:

• The release workflow computed VERSION but passed -e COLONIZER_BUILD_VERSION, which was never set, so the Linux release binary shipped unstamped — claiming to be an exact release even on PR builds. The commit variable had the same hole.
• Three ways the new installers still destroyed directories live colonies were mounting: prune sparing only installed+previous (a two-generation-old version was deleted out from under a live mount), same-version reinstall deleting the running install, and the legacy migration — the path every existing install takes.
• Two ways the "is it in use?" check answered no while a colony held the directory: /proc/self/mountinfo octal-escapes spaces, so any path with a space silently missed every comparison; and the Rust mount-point match used a bare string prefix, so pfxLONG matched against a mount at pfx. Both emptied a live mount in reproduction.
• install.sh's final version fallback produced a token its own validator rejected, dead-ending a successful build in a refused install.

Worth a close look

• The dir_in_use predicate (scripts/install.sh, scripts/install-release.sh, crates/colonizer/src/install.rs). It is the load-bearing safety check, it parses /proc/self/mountinfo, and it has already been wrong twice. Where it cannot tell — no /proc, i.e. macOS — it answers "in use", so deferred deletes never complete there and old versions accumulate until removed by hand. That trade-off is deliberate and now documented; it is worth confirming it is the one you want.
• The re-exec path was not exercised end-to-end. The acceptance criterion "two colonies mid-turn, both still working afterwards" was verified in pieces — mount safety live, protocol and refusal logic under unit test — but no real mothership with live colonies was updated and re-execed in this sandbox. Mesh child shutdown and recover reconnection are the parts resting on code reading rather than observation.
• The release workflow could not be run. Docker is unavailable here, so the env-var plumbing was verified by reading plus a YAML parse. Note this PR touches release.yml and the install scripts, and that workflow triggers on PRs touching exactly those paths — so it will actually run on this PR.
• macOS was not tested. The ln -sfn fallback is genuinely non-atomic: a crash mid-swap leaves app missing, not merely dangling. POSIX sh offers no atomic rename there.
• Overlap with work in flight. This branch is based on main, which has neither Say which Colonizer this is, and when a newer one is out #110 (version stamp and check) nor Install the app behind a symlink, so an interrupted install never leaves no app at all #104 (versioned app directory). It implements both halves plus the apply, so expect overlap if those land first.

main.rs and sessions.rs are deliberately small diffs (+77/−2 and +15/−1); an earlier cargo fmt had rewritten ~2,200 unrelated lines in them and that churn was reverted, since the committed baseline predates the current rustfmt's style edition.

---

🤖 Generated by Colonizer in a microVM

[ParallelEntrepreneur]

Superseded. The same feature landed from the other side while this was in review, and this branch is based on a main that no longer exists in that shape — #110 stamped the build, #112 applied updates in place, #104 made an install a symlink move, and #115/#118 have moved main on again since.

What this branch had that main did not, I have taken in #133:

• colonizer version / --version / -V, and a --help.
• development on /api/version, so a UI can tell a release from a build after a tag or from a modified tree.
• User-facing update documentation — rewritten against the merged design rather than copied, since this branch's docs/updates.md describes a versions/<v> layout that does not exist on main.

What I did not take, and why: install.rs, the in-process Rust installer. The merged implementation runs scripts/install-release.sh — the same installer a person runs — which already unpacks beside the running app and moves the symlink with one rename. Taking this one would mean a second implementation of the download, the checksum verification against SHA256SUMS, the Sigstore attestation check and the swap, free to diverge from the one users run by hand. One installer, exercised by everybody, is worth more than a faster one only the update button uses.

Nothing here is lost: the branch stays, and this is linked from #133 for anyone who wants to compare.