A version somebody can read, instead of a sha nobody can

Updates follow a channel now. `stable` is the newest vX.Y.Z tag; `edge` is the
branch tip, which is what this did before. Stable is the default, because a
branch tip is not a release -- following one means deploying whatever was pushed
five minutes ago, possibly mid-feature, which is right for whoever builds this
and wrong for whoever runs it. The page can now say "running 1.0.0, 1.1.0
available" rather than showing two shas and leaving somebody to guess.

Read with git plumbing and never a forge API, for three reasons in the order
they bite. It would need a token on the deployment host -- a credential that can
reach the repository, sitting on a box, to answer a read-only question about
version numbers. It would tie this to one forge, so a fork on GitHub gets
nothing. And it breaks: checked against the Gitea this is developed on, `tea
whoami` works and `tea releases list` returns a 500 from a server-side panic
about token scopes, so a page resting on that endpoint would have shipped
already broken.

Release notes still travel, inside the annotated tag object, which
`git for-each-ref` reads with no API anywhere.

Two details that are only obvious after getting them wrong. A tag with a suffix
is not a release: git's version sort puts v1.1.0-rc1 *above* v1.1.0, so
accepting one would step a stable host onto a candidate on the strength of a
hyphen. And `--sort=-v:refname` rather than a lexical sort, which puts v1.9.0
above v1.10.0 and does it silently the first time a project reaches ten of
anything -- there is a test.

What is running is `git describe --tags --always`, so it reads "1.0.0" at a tag,
"1.0.0-7-gd4f56d" seven commits past one, and a bare sha before the first
release ever exists. That last case is what `--always` is for. When it lands
exactly on a tag whose name disagrees with __version__, the page says so: a tag
cut before the version bump names a release nobody can identify afterwards, and
the check costs no subprocess because both facts are already in hand.

update.sh resolves the channel the same way and detaches at the tag rather than
resetting -- a `reset --hard <tag>` while on main would move the local branch to
it, which is a rewrite of a ref nobody asked to rewrite. A host with no tags
falls back to the branch and says so, which is every host until the release.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/lembas/web/templates/admin/updates.html

@@ -7,8 +7,12 @@
 
 {% block admin_content %}
 <p class="admin-lede">
-  What is running here, what is on <code>{{ state.branch }}</code>, and what
-  changed between. Checking reaches the remote; opening this page does not.
+  This host follows the
+  <strong>{{ "stable" if state.channel == "stable" else "edge" }}</strong>
+  channel{% if state.channel == "stable" %} — the newest release tag{% else %} —
+  the tip of <code>{{ state.branch }}</code>, which is whatever was pushed most
+  recently and may be half finished{% endif %}.
+  Checking reaches the remote; opening this page does not.
 </p>
 
 {% if saved %}
@@ -23,16 +27,25 @@
   <dl class="mode-list">
     <div class="mode-list__row">
       <dt><strong>Version</strong></dt>
-      <dd>{{ state.version }}</dd>
+      <dd>
+        {#
+          `git describe`, not the version string: "1.0.0" exactly at a tag and
+          "1.0.0-7-gd4f56d" seven commits past one. The second is the honest
+          answer for an edge instance, where the version string alone would claim
+          to be a release it is not.
+        #}
+        <strong>{{ state.running or state.version }}</strong>
+        {% if state.running and state.running != state.version %}
+        <span class="faint text-xs">(reports {{ state.version }})</span>
+        {% endif %}
+      </dd>
     </div>
     {% if state.head %}
     <div class="mode-list__row">
       <dt><strong>Commit</strong></dt>
       <dd>
         <code>{{ state.head.short }}</code> {{ state.head.subject }}
-        {% if state.dirty %}
-        <span class="badge">uncommitted changes</span>
-        {% endif %}
+        {% if state.dirty %}<span class="badge">uncommitted changes</span>{% endif %}
       </dd>
     </div>
     {% endif %}
@@ -44,10 +57,21 @@
     {% endif %}
   </dl>
 
+  {% if state.version_mismatch %}
+  <div class="alert alert--warning">
+    {{ icon("warning", "icon--sm") }}
+    <span>
+      This is tagged <strong>{{ state.version_mismatch }}</strong> but reports
+      version <strong>{{ state.version }}</strong>. A tag cut before the version
+      bump names a release nobody can identify afterwards.
+    </span>
+  </div>
+  {% endif %}
+
   {% if not state.is_git %}
   <p class="field__hint">
     This was not installed from a git checkout — a container image, or a wheel —
-    so there is nothing here to compare or update. Update the image instead.
+    so there is nothing here to compare or update. Pull a new image instead.
   </p>
   {% else %}
   <form method="post" action="/admin/updates/check" class="btn-row">
@@ -62,51 +86,76 @@
 <section class="card">
   <h2 class="card__title">
     Available
-    {% if state.up_to_date %}<span class="badge badge--leaf">up to date</span>
-    {% elif state.behind %}<span class="badge">{{ state.behind | length }} behind</span>
+    {% if state.no_releases %}<span class="badge">nothing released yet</span>
+    {% elif state.up_to_date %}<span class="badge badge--leaf">up to date</span>
+    {% elif state.behind %}<span class="badge">{{ state.behind | length }} commit{{ '' if state.behind|length == 1 else 's' }} behind</span>
     {% endif %}
   </h2>
 
-  {% if not state.remote %}
+  {% if state.no_releases %}
   <p class="field__hint">
-    Nothing known about <code>origin/{{ state.branch }}</code> yet. Check the
-    remote above.
+    Nothing on <code>{{ state.branch }}</code> has been tagged as a release yet,
+    so the stable channel has nothing to offer. Switch this host to
+    <code>edge</code> in <code>lembas.env</code> to follow the branch instead.
   </p>
+
+  {% elif not state.available %}
+  <p class="field__hint">
+    Nothing known about the remote yet. Check it above.
+  </p>
+
   {% elif state.up_to_date %}
   <p class="field__hint">
-    <code>{{ state.remote.short }}</code> is what is running.
+    <strong>{{ state.available.label }}</strong> is what is running.
   </p>
+
   {% else %}
   <p class="card__lede">
-    <code>{{ state.remote.short }}</code> {{ state.remote.subject }}
+    <strong>{{ state.available.label }}</strong>
+    <span class="faint">— {{ state.available.subject }}</span>
   </p>
 
   {#
-    The log between, not just a count. "3 behind" is a number somebody has to go
-    and look up; the subjects are the thing that decides whether this is worth
+    Release notes, out of the annotated tag itself. Escaped and preformatted,
+    never through services/markdown.py: this comes from a tag object rather than
+    from a template, and markdown is the one path allowed to emit HTML.
+  #}
+  {% if state.available.notes %}
+  <pre class="tool-result__text">{{ state.available.notes }}</pre>
+  {% endif %}
+
+  {#
+    The commits between, not just a count. "3 behind" is a number somebody has to
+    go and look up; the subjects are what decides whether this is worth
     restarting for right now.
   #}
-  <ul class="model-list">
-    {% for commit in state.behind %}
-    <li class="model-list__item">
-      <div style="min-width: 0">
-        <code class="text-xs">{{ commit.short }}</code> {{ commit.subject }}
-      </div>
-    </li>
-    {% endfor %}
-  </ul>
+  {% if state.behind %}
+  <details>
+    <summary class="text-sm">
+      {{ state.behind | length }} commit{{ '' if state.behind|length == 1 else 's' }} between
+    </summary>
+    <ul class="model-list">
+      {% for commit in state.behind %}
+      <li class="model-list__item">
+        <div style="min-width: 0">
+          <code class="text-xs">{{ commit.short }}</code> {{ commit.subject }}
+        </div>
+      </li>
+      {% endfor %}
+    </ul>
+  </details>
+  {% endif %}
 
   {% if state.dirty %}
   <div class="alert alert--warning">
     {{ icon("warning", "icon--sm") }}
     <span>
-      This checkout has uncommitted changes. The update does a hard reset, which
-      would throw them away — nothing here is meant to be edited in place, so
-      this usually means somebody was debugging on the box.
+      This checkout has uncommitted changes, and updating discards them.
+      Nothing here is meant to be edited in place, so this usually means somebody
+      was debugging on the box.
     </span>
   </div>
   {% endif %}
-
   {% endif %}
 </section>
 
@@ -134,15 +183,18 @@
   {% elif state.helper %}
   <p class="card__lede">
     This host has the update helper installed, so the button below writes a
-    request that a systemd unit picks up and runs as root. It always deploys
-    <code>{{ state.branch }}</code> — the request carries no branch and no ref,
-    so pressing it is never “deploy something else”.
+    request that a systemd unit picks up and runs as root. It always deploys the
+    <strong>{{ state.channel }}</strong> channel — the request carries no ref and
+    no channel, so pressing it is never “deploy something else”.
   </p>
   <form method="post" action="/admin/updates/apply" class="btn-row"
         data-confirm="Update and restart? Replies being written are saved; open terminals are cut off.">
-    <button class="btn btn--primary" type="submit" {{ 'disabled' if state.up_to_date }}>
+    <button class="btn btn--primary" type="submit"
+            {{ 'disabled' if state.up_to_date or state.no_releases }}>
       {{ icon("sparkle", "icon--sm") }}
-      {{ "Nothing to apply" if state.up_to_date else "Update and restart" }}
+      {% if state.no_releases %}Nothing released
+      {% elif state.up_to_date %}Nothing to apply
+      {% else %}Update to {{ state.available.label }} and restart{% endif %}
     </button>
   </form>
   <p class="field__hint">
@@ -164,12 +216,11 @@
   <p class="field__hint">
     To install it, re-run the installer with
     <code>INSTALL_UPDATE_HELPER=1</code>. Doing so means anybody who can
-    administer this web interface can deploy whatever is on
-    <code>{{ state.branch }}</code> — which is the point, and worth deciding on
-    purpose rather than arriving at.
+    administer this web interface can deploy the <code>{{ state.channel }}</code>
+    channel — which is the point, and worth deciding on purpose rather than
+    arriving at.
   </p>
   {% endif %}
 </section>
 {% endif %}
 {% endblock %}
-