code-coordinator 0.5.312__tar.gz → 0.5.314__tar.gz

{code_coordinator-0.5.312 → code_coordinator-0.5.314}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.312
+Version: 0.5.314
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.312 → code_coordinator-0.5.314}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.312
+Version: 0.5.314
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.312 → code_coordinator-0.5.314}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.312",
+  "tag": "0.5.314",
   "distance": 0,
-  "node": "g809179d4ae62704f319b523abbe2d69427d5a406",
+  "node": "gc38f3dc007e19c5f559fba9c15807c1b5a0e4b7f",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-31"

{code_coordinator-0.5.312 → code_coordinator-0.5.314}/coord/commands/release.py

@@ -2319,10 +2319,26 @@ def _roll_tui(machine, *, local_name: str | None) -> tuple[bool | None, str]:
     (:func:`coord.tui_release.fetch_latest_release_tag`) — that is the
     :data:`~coord.release_propagate.CHANNEL_TUI` channel doing its own version
     selection, not this run guessing across a channel boundary.
+
+    #2981 — AN EMPTY CHANNEL IS NOT A FAILED ROLL.
+    A channel with zero releases/tags 404s on every ``coord tui update``
+    forever, until someone cuts a first release — that is a fact about
+    ``coord-tui``'s Releases, not about whatever this host just attempted.
+    ``coord tui update`` exits :data:`~coord.commands.tui.EXIT_EMPTY_CHANNEL`
+    specifically for that case (``EmptyReleaseChannelError``, raised at the
+    source in :func:`coord.tui_release.fetch_latest_release_tag`), so this
+    reads that exact exit code and returns ``ok=None`` — the same "no channel
+    to roll" treatment already given to a remote host above, which
+    :func:`coord.release_propagate.scope_verification` excludes from the
+    gate that ``--rollback-on-red`` acts on. A *genuine* failure (a real
+    release exists but the asset/checksum/install step fails) still exits
+    ``1`` here and stays ``ok=False`` — still blocking, still eligible to
+    trigger a rollback.
     """
     import subprocess  # noqa: PLC0415
 
     from coord import release_propagate as rp  # noqa: PLC0415
+    from coord.commands.tui import EXIT_EMPTY_CHANNEL  # noqa: PLC0415
 
     if local_name is None or machine.name != local_name:
         return None, (
@@ -2343,7 +2359,13 @@ def _roll_tui(machine, *, local_name: str | None) -> tuple[bool | None, str]:
             if installed
             else f"coord-tui updated from the {rp.CHANNEL_TUI} channel"
         )
-    return False, (proc.stderr or proc.stdout or f"exit {proc.returncode}").strip()[:300]
+    detail = (proc.stderr or proc.stdout or f"exit {proc.returncode}").strip()[:300]
+    if proc.returncode == EXIT_EMPTY_CHANNEL:
+        return None, (
+            f"{rp.CHANNEL_TUI} channel has no published release yet — "
+            f"nothing to install, not a roll failure (#2981): {detail}"
+        )
+    return False, detail
 
 
 def _installed_tui_version(stdout: str) -> str | None:

{code_coordinator-0.5.312 → code_coordinator-0.5.314}/coord/commands/tui.py

@@ -49,6 +49,7 @@ from coord.tui_release import (
     DEFAULT_INSTALL_PATH,
     DEFAULT_REPO,
     DEV_BUILD_SENTINEL_VERSION,
+    EmptyReleaseChannelError,
     ReleaseAssetNotFoundError,
     UnsupportedPlatformError,
     detect_target,
@@ -63,6 +64,15 @@ from coord.tui_release import (
     sha256_file,
 )
 
+#: `tui update`'s exit code when the channel has never published a release
+#: (#2981) — distinct from the generic ``1`` used for every other failure so
+#: `coord/commands/release.py`'s `_roll_tui` can tell "nothing to install
+#: yet" apart from "the roll actually failed" by exit code alone, with no
+#: string-matching of the error message. Kept here (not in `tui_release.py`)
+#: because it is a detail of *this command's* process-exit contract, the
+#: same reason `3` (the dev-build refusal below) lives here too.
+EXIT_EMPTY_CHANNEL = 4
+
 
 def _dest_path(dest: str | None) -> Path:
     return Path(dest).expanduser() if dest else Path(DEFAULT_INSTALL_PATH).expanduser()
@@ -230,7 +240,7 @@ def _print_skew_notice(
         "release publishes one) before an atomic rename into place -- so a "
         "running coord-tui, or an interrupted download, never observes a "
         "partial binary.\n\n"
-        "Dev-checkout guard: tui/Cargo.toml's committed [package] version "
+        "Dev-checkout guard: coord-tui's own Cargo.toml's committed [package] version "
         f"is the {DEV_BUILD_SENTINEL_VERSION!r} placeholder that only "
         "release-tui.yml's CI build stamps a real version over (never "
         "committed back) -- so a plain local `cargo build` always reports "
@@ -310,6 +320,15 @@ def tui_update(
             target_version = fetch_latest_release_tag(
                 repo=repo, api_base=api_base, timeout=timeout
             )
+        except EmptyReleaseChannelError as exc:
+            # #2981: this channel has never published a release -- there is
+            # nothing to install, but that is a fact about the CHANNEL, not
+            # evidence that this run's attempt failed. A distinct exit code
+            # (rather than the generic `1` below) lets a caller such as
+            # `coord release propagate` grade the two differently without
+            # parsing this message.
+            click.echo(f"error: {exc}", err=True)
+            sys.exit(EXIT_EMPTY_CHANNEL)
         except Exception as exc:  # noqa: BLE001 -- surface any network/HTTP failure plainly
             click.echo(
                 f"error: could not resolve coord-tui's latest release from "
@@ -321,11 +340,32 @@ def tui_update(
 
     if dest_path.exists() and not force:
         installed = read_installed_version(dest_path)
+        # #2984: check "already at the target version" BEFORE "looks like a
+        # dev build", not after. DEV_BUILD_SENTINEL_VERSION is coord-tui's
+        # committed placeholder, and it collides with coord-tui's real
+        # `v0.1.0` release tag -- a CI-built v0.1.0 binary reports the exact
+        # same string a bare `cargo build` always does. Version-equality
+        # can't tell those apart, but it doesn't need to here: if what's
+        # installed already matches what this run would install, installing
+        # again changes nothing, so there is nothing worth refusing over --
+        # dev build or not. This ordering is what makes the check stop
+        # depending on the release tag differing from the placeholder (see
+        # is_dev_build's docstring and the module docstring's "#2984"
+        # paragraph in tui_release.py); it does NOT resolve the one case
+        # that stays genuinely ambiguous -- a real dev build sitting at the
+        # destination while coord-tui's latest release also happens to be
+        # 0.1.0 -- which is a documented, self-limiting gap, not a bug here.
+        if normalize_version(installed) == target_version:
+            click.echo(
+                f"coord-tui is already v{target_version} at {dest_path} -- "
+                "nothing to do (--force to reinstall)."
+            )
+            return
         if installed == DEV_BUILD_SENTINEL_VERSION:
             click.echo(
                 f"refusing to overwrite {dest_path}: it reports version "
                 f"{DEV_BUILD_SENTINEL_VERSION!r}, the sentinel a locally "
-                "`cargo build`'d coord-tui always carries (coord-tui's "
+                "`cargo build`'d coord-tui always carries (coord-tui's own "
                 "Cargo.toml "
                 "committed version is only stamped for real in CI release "
                 "builds). This looks like a dev build someone is iterating "
@@ -335,12 +375,6 @@ def tui_update(
                 err=True,
             )
             sys.exit(3)
-        if normalize_version(installed) == target_version:
-            click.echo(
-                f"coord-tui is already v{target_version} at {dest_path} -- "
-                "nothing to do (--force to reinstall)."
-            )
-            return
 
     click.echo(f"Detected platform target: {target}")
     click.echo(f"Resolving coord-tui v{target_version} from {repo}...")

{code_coordinator-0.5.312 → code_coordinator-0.5.314}/coord/tui_release.py

@@ -3,7 +3,7 @@
 
 ``release-tui.yml`` builds ``coord-tui`` for linux/macOS/Windows on every
 ``vX.Y.Z`` tag push and attaches ``coord-tui-<target>`` assets to a GitHub
-Release, with ``tui/Cargo.toml``'s version stamped from that tag. This module
+Release, with coord-tui's own ``Cargo.toml``'s version stamped from that tag. This module
 is the client half: find the release to install, detect which of that
 workflow's build-matrix targets this host needs, and install the binary
 without a human ever visiting the Releases page by hand.
@@ -50,9 +50,9 @@ Two invariants drive the design:
   interrupted download, can only ever observe the old binary or the new
   one — never a partial file at the destination path.
 
-* **Never clobber a dev build silently.** ``tui/Cargo.toml``'s committed
-  ``[package] version`` is the ``0.1.0`` placeholder — see
-  ``tui/src/main.rs``'s ``version_string()`` docstring — and only
+* **Never clobber a dev build silently.** coord-tui's own committed
+  ``Cargo.toml``'s ``[package] version`` is the ``0.1.0`` placeholder — see
+  ``src/main.rs``'s ``version_string()`` docstring in that repo — and only
   ``release-tui.yml``'s CI build stamps a real ``vX.Y.Z`` over it, as a
   build-time edit that is never committed back. A binary built locally with
   a bare ``cargo build`` therefore *always* reports exactly ``coord-tui
@@ -61,6 +61,23 @@ Two invariants drive the design:
   destination is a developer's own local build, not a stale release —
   :func:`is_dev_build` checks for it, and ``coord tui update`` refuses to
   overwrite it without ``--force``.
+
+  #2984: version-equality is a *guess*, not a provenance check, and it has
+  exactly one collision — the sentinel is coord-tui's committed placeholder,
+  so a real CI-built binary reports it verbatim on precisely the tag that
+  reproduces the placeholder (``v0.1.0``, which is also where any new release
+  channel's tag line starts). ``coord tui update`` does not try to resolve
+  that collision by inspecting the binary harder; it sidesteps it by checking
+  "is the destination already at the version this run would install?"
+  *before* asking "does the destination look like a dev build?" — when they
+  already match there is nothing this run would change by installing again,
+  dev build or not, so refusing serves no purpose. The one case that stays
+  irreducibly ambiguous — a genuine local dev build sitting at the
+  destination while coord-tui's latest release *also* happens to be
+  ``0.1.0`` — is a real gap, not a bug in this check: nothing short of a
+  provenance marker neither path can fake (out of scope here; see issue
+  #2984's "alternative" fix) can tell those two apart from the version
+  string alone.
 """
 
 from __future__ import annotations
@@ -98,9 +115,13 @@ DEFAULT_API_BASE = "https://api.github.com"
 DEFAULT_INSTALL_PATH = "~/.local/bin/coord-tui"
 
 #: See the module docstring's "never clobber a dev build" invariant:
-#: `tui/Cargo.toml`'s committed `[package] version` field, which a plain
-#: `cargo build` always reports verbatim because only release-tui.yml's CI
-#: stamps a real version over it (and never commits that stamp back).
+#: coord-tui's own `Cargo.toml`'s committed `[package] version` field, which a
+#: plain `cargo build` always reports verbatim because only release-tui.yml's
+#: CI stamps a real version over it (and never commits that stamp back).
+#:
+#: #2984: this value collides with coord-tui's real `v0.1.0` release tag —
+#: see the module docstring's "#2984" paragraph for how `coord tui update`
+#: avoids misreading that collision as a dev build.
 DEV_BUILD_SENTINEL_VERSION = "0.1.0"
 
 #: release-tui.yml's build matrix, keyed by (system, machine) as reported by
@@ -127,6 +148,25 @@ class ReleaseAssetNotFoundError(RuntimeError):
     """The release exists but doesn't carry the asset this host needs."""
 
 
+class EmptyReleaseChannelError(RuntimeError):
+    """The channel has never published a release at all (#2981).
+
+    Distinct from :class:`ReleaseAssetNotFoundError` on purpose: that one
+    means a real release exists but is missing something (an asset, a usable
+    ``tag_name``); this one means there is **no release to even look at** —
+    ``/releases/latest`` 404s because the repo has zero releases and zero
+    tags, not because of a network problem or a malformed one.
+
+    The distinction matters to callers precisely because the two are not
+    graded the same way: "nothing has been published yet" is a fact about
+    the channel, not about whatever this run tried to do, so it must never
+    be treated as evidence that an install/roll attempt itself failed (see
+    ``coord/commands/tui.py``'s ``tui update`` and
+    ``coord/commands/release.py``'s ``_roll_tui``, which special-case this
+    exact exception type rather than string-matching an error message).
+    """
+
+
 @dataclass(frozen=True)
 class ReleaseAsset:
     name: str
@@ -220,9 +260,21 @@ def fetch_latest_release_tag(
     invocation, or worse, an accidental match on an unrelated release that
     happened to share a number.
 
-    Raises on any HTTP/network failure, or when the channel has no release at
-    all — callers decide whether that is fatal (``coord tui update`` has
-    nothing to install) or a soft "could not check" (``coord tui status``).
+    Raises :class:`EmptyReleaseChannelError` when the channel has no release
+    at all — a bare 404 from ``/releases/latest`` (GitHub's own signal for
+    "this repo has never published a release"), or a 200 whose body carries
+    no usable ``tag_name`` (belt-and-braces; not observed from the real API
+    but no less "nothing to resolve" if it ever happened). Any *other*
+    HTTP/network failure (5xx, auth, timeout, DNS) is left to raise as-is —
+    that is a real "could not check", not "nothing published yet".
+
+    #2981: this distinction is exactly what callers need to decide whether
+    an empty channel is fatal (``coord tui update`` has nothing to install)
+    or a soft "could not check" (``coord tui status``) *without* also
+    swallowing a genuine failure into the same bucket. Before this, a bare
+    404 escaped as an undifferentiated ``httpx.HTTPStatusError`` — callers
+    that wanted to tell "empty channel" apart from "the roll failed" had
+    nothing but the error message to match against.
     """
     import httpx  # noqa: PLC0415 — keep import cost off the non-network path
 
@@ -231,11 +283,16 @@ def fetch_latest_release_tag(
     if token:
         headers["Authorization"] = f"Bearer {token}"
     response = httpx.get(url, timeout=timeout, headers=headers, follow_redirects=True)
+    if response.status_code == 404:
+        raise EmptyReleaseChannelError(
+            f"{repo} has no published release to resolve a latest version "
+            f"from (GET {url} -> 404 — this repo has zero releases/tags)"
+        )
     response.raise_for_status()
     data = response.json()
     version = normalize_version((data or {}).get("tag_name"))
     if not version:
-        raise ReleaseAssetNotFoundError(
+        raise EmptyReleaseChannelError(
             f"{repo} has no published release to resolve a latest version from"
         )
     return version
@@ -318,7 +375,8 @@ def install_atomically(tmp_path: Path, dest_path: Path) -> None:
 def read_installed_version(binary_path: Path, timeout: float = 5.0) -> str | None:
     """Parse ``<binary_path> --version``'s ``coord-tui <version>`` output,
     or ``None`` when the path doesn't exist, isn't runnable, or its output
-    doesn't match that shape (see ``tui/src/main.rs``'s ``version_string``)."""
+    doesn't match that shape (see coord-tui's own ``src/main.rs``'s
+    ``version_string``)."""
     if not binary_path.exists():
         return None
     try:
@@ -342,7 +400,22 @@ def read_installed_version(binary_path: Path, timeout: float = 5.0) -> str | Non
     return None
 
 
-def is_dev_build(binary_path: Path) -> bool:
-    """True when *binary_path* reports the :data:`DEV_BUILD_SENTINEL_VERSION`
-    — see the module docstring's "never clobber a dev build" invariant."""
-    return read_installed_version(binary_path) == DEV_BUILD_SENTINEL_VERSION
+def is_dev_build(binary_path: Path, *, target_version: str | None = None) -> bool:
+    """True when *binary_path* reports :data:`DEV_BUILD_SENTINEL_VERSION` in
+    a way that isn't already explained by the destination holding
+    *target_version* — see the module docstring's "#2984" paragraph.
+
+    #2984: the sentinel collides with coord-tui's real ``v0.1.0`` release, so
+    version-equality alone cannot always tell a genuine local ``cargo build``
+    apart from a CI-built binary of that one release. It doesn't have to: pass
+    *target_version* — the version this run resolved as "the one to install"
+    (bare, e.g. via :func:`normalize_version`) — and a destination that
+    already reports exactly that version is never reported as a dev build,
+    sentinel or not, because there is nothing a refusal would protect there.
+    Omitting *target_version* falls back to the old, collision-prone,
+    version-only check — the most a bare *binary_path* can ever support.
+    """
+    installed = read_installed_version(binary_path)
+    if installed != DEV_BUILD_SENTINEL_VERSION:
+        return False
+    return target_version is None or installed != target_version

{code_coordinator-0.5.312 → code_coordinator-0.5.314}/tests/test_cli_release_propagate.py

@@ -1393,6 +1393,99 @@ def test_2026_08_09_a_good_roll_is_not_reverted_by_lanes_it_cannot_roll(
     assert "advisory" in result.output
 
 
+def test_2981_an_empty_tui_channel_does_not_roll_back_the_python_lanes(
+    valid_config_path, state_dir, no_network, monkeypatch
+):
+    """THE #2981 regression, end to end.
+
+    `JDonaghy/coord-tui` had zero releases/tags, so `coord tui update` 404s
+    from `/releases/latest` on every run, forever, until someone cuts a
+    first release. `_roll_tui` on the one host that actually has an install
+    path (`dellserver` in the real incident, `server` here) used to read
+    that 404 exactly like a genuine install failure and report `ok=False` —
+    a BLOCKING result. That put `(tui, server)` inside this run's attempted
+    scope, so a merely-advisory "coord-tui is stale" verify finding on that
+    same host turned blocking, `gate.red` went true, and
+    `--rollback-on-red` reverted the two good python rolls right alongside
+    the tui lane that was never actually broken — a fleet rolled forward
+    and straight back for nothing, twice in a row, per the issue.
+
+    `coord tui update` now exits `EXIT_EMPTY_CHANNEL` for exactly this case
+    (`EmptyReleaseChannelError`, raised at the source in
+    `fetch_latest_release_tag`), and `_roll_tui` reads that exit code back
+    into `ok=None` — the same "no channel to roll" treatment already given
+    to a remote host with no install path at all. `ok=None` excludes the
+    lane from `attempted_scope`, so the verify finding below stays
+    advisory, the gate stays green, and nothing gets rolled back."""
+    from coord import release_verify as rv
+
+    calls = _stub_lanes(monkeypatch)
+
+    def _tui(machine, **kwargs):
+        calls.append(("tui", machine.name))
+        if machine.name == "server":
+            # What `_roll_tui` itself now returns when `coord tui update`
+            # exits `EXIT_EMPTY_CHANNEL` — see its #2981 docstring section.
+            return None, (
+                f"{rp.CHANNEL_TUI} channel has no published release yet — "
+                "nothing to install, not a roll failure (#2981): "
+                "404 Not Found"
+            )
+        return None, "coord-tui is a per-host binary with no remote install path"
+
+    monkeypatch.setattr(release_cmd, "_roll_tui", _tui)
+    _stub_verify(
+        monkeypatch,
+        versions={"laptop": ["0.4.110"], "server": ["0.4.110"]},
+        findings=[
+            # Even a CRIT finding, on the very host that attempted this
+            # lane, must not turn the gate red once the attempt itself is
+            # `ok=None` — that is the whole point of #2052's scoping.
+            rv.Finding(severity="crit", host="server", lane="coord-tui",
+                       summary="coord-tui is 40h older than source"),
+        ],
+    )
+    monkeypatch.setattr(
+        release_cmd, "_rollback_host",
+        lambda *a, **k: pytest.fail(
+            "an empty coord-tui channel is not a failed roll — it must "
+            "never trigger --rollback-on-red"
+        ),
+    )
+    result = CliRunner().invoke(
+        main,
+        ["release", "propagate", "--config", str(valid_config_path),
+         "--target", "0.4.111", "--daemon-host", "server"],
+    )
+    assert result.exit_code == 0, result.output
+
+    record = _records(state_dir)[0]
+    # The run completed and verified — it was never reverted.
+    assert record["status"] == rp.STATUS_VERIFIED
+    # The python lanes for BOTH hosts stayed rolled.
+    for host in ("server", "laptop"):
+        python_lane = next(
+            l for l in record["lanes"] if l["lane"] == "python" and l["host"] == host
+        )
+        assert python_lane["ok"] is True, f"{host}'s good python roll must survive"
+
+    # The tui lane itself is recorded as unrollable, not failed.
+    server_tui = next(
+        l for l in record["lanes"] if l["lane"] == "tui" and l["host"] == "server"
+    )
+    assert server_tui["ok"] is None
+    assert server_tui["unrollable"] is True
+
+    # The verify finding is still journalled in full...
+    assert record["verification"]["severity"] == "crit"
+    assert len(record["verification"]["findings"]) == 1
+    # ...but the gate that `--rollback-on-red` actually acts on is clean.
+    assert record["gate"]["severity"] == "ok"
+    assert len(record["gate"]["blocking"]) == 0
+    assert len(record["gate"]["advisory"]) == 1
+    assert "advisory" in result.output
+
+
 def test_the_outside_reach_message_names_the_manual_remedy(
     valid_config_path, state_dir, no_network, monkeypatch
 ):
@@ -2386,3 +2479,47 @@ def test_roll_tui_surfaces_a_failed_update(monkeypatch):
     ok, detail = release_cmd._roll_tui(_machine(name="server"), local_name="server")
     assert ok is False
     assert "could not resolve" in detail
+
+
+def test_roll_tui_treats_an_empty_channel_as_unrollable_not_failed(monkeypatch):
+    """#2981: `coord tui update` exits `EXIT_EMPTY_CHANNEL` (not the generic
+    `1`) specifically when the channel has never published a release —
+    `JDonaghy/coord-tui`'s actual state, which 404s from `/releases/latest`
+    on every run forever. `_roll_tui` must read that exit code back into
+    `ok=None`, exactly like the "no remote install path" case, so this
+    lane never lands inside a run's attempted scope and can never be
+    grounds for `--rollback-on-red` — see
+    `test_2981_an_empty_tui_channel_does_not_roll_back_the_python_lanes` for
+    the full propagate-level regression this unlocks."""
+    from coord.commands.tui import EXIT_EMPTY_CHANNEL
+
+    class _Proc:
+        returncode = EXIT_EMPTY_CHANNEL
+        stdout = ""
+        stderr = (
+            "error: JDonaghy/coord-tui has no published release to resolve "
+            "a latest version from (GET .../releases/latest -> 404 — this "
+            "repo has zero releases/tags)"
+        )
+
+    monkeypatch.setattr("subprocess.run", lambda argv, **kw: _Proc())
+    ok, detail = release_cmd._roll_tui(_machine(name="server"), local_name="server")
+    assert ok is None
+    assert "not a roll failure" in detail
+    assert "no published release" in detail
+
+
+def test_roll_tui_a_real_failure_still_blocks_after_the_2981_fix(monkeypatch):
+    """The other half of the #2981 acceptance bar: a GENUINE failure (a real
+    release exists, but e.g. the asset/checksum/install step failed) must
+    still exit the generic `1`, and `_roll_tui` must still report `ok=False`
+    -- still blocking, still eligible to trigger a rollback."""
+    class _Proc:
+        returncode = 1
+        stdout = ""
+        stderr = "error: checksum mismatch for coord-tui-x86_64-linux"
+
+    monkeypatch.setattr("subprocess.run", lambda argv, **kw: _Proc())
+    ok, detail = release_cmd._roll_tui(_machine(name="server"), local_name="server")
+    assert ok is False
+    assert "checksum mismatch" in detail

{code_coordinator-0.5.312 → code_coordinator-0.5.314}/tests/test_cli_tui_update.py

@@ -284,12 +284,21 @@ def test_tui_update_default_version_comes_from_coord_tui_not_the_coordinator(
     assert os.popen(f"{dest} --version").read().strip() == f"coord-tui {TUI_VERSION}"
 
 
-def test_tui_update_fails_loudly_when_the_channel_is_unreachable(
+def test_tui_update_reports_an_empty_channel_distinctly(
     stub_server, tmp_path: Path
 ) -> None:
-    """Unlike `tui status`, this one is fatal: there is nothing to install,
-    and silently falling back to some other version (the coordinator's, say)
-    is precisely the cross-channel guess the split exists to prevent."""
+    """#2981: a repo with zero releases/tags 404s on `/releases/latest` on
+    every run, forever, until someone cuts a first release (this is
+    JDonaghy/coord-tui's actual state at the time of writing). This is still
+    fatal for `tui update` itself -- there is nothing to install, and
+    silently falling back to some other version (the coordinator's, say) is
+    precisely the cross-channel guess the split exists to prevent -- but it
+    must exit with `EXIT_EMPTY_CHANNEL`, not the generic `1` a real failure
+    uses, so a caller like `coord release propagate` can tell "nothing
+    published yet" apart from "the roll actually failed" by exit code alone
+    (`coord/commands/release.py`'s `_roll_tui` is the caller that cares)."""
+    from coord.commands.tui import EXIT_EMPTY_CHANNEL
+
     dest = tmp_path / "bin" / "coord-tui"
     result = CliRunner().invoke(
         main,
@@ -297,6 +306,24 @@ def test_tui_update_fails_loudly_when_the_channel_is_unreachable(
          "--dest", str(dest), "--timeout", "5"],
     )
 
+    assert result.exit_code == EXIT_EMPTY_CHANNEL, result.output
+    assert result.exit_code != 1
+    assert "has no published release" in result.output
+    assert not dest.exists()
+
+
+def test_tui_update_fails_loudly_on_a_genuine_network_failure(tmp_path: Path) -> None:
+    """A real network failure -- nothing is listening on this port, so the
+    connection itself is refused -- is NOT the #2981 empty-channel case
+    above and must keep the generic exit code `1`: there is a real
+    "could not check" here, not "nothing published yet"."""
+    dest = tmp_path / "bin" / "coord-tui"
+    result = CliRunner().invoke(
+        main,
+        ["tui", "update", "--repo", REPO, "--api-base", "http://127.0.0.1:1",
+         "--dest", str(dest), "--timeout", "2"],
+    )
+
     assert result.exit_code == 1, result.output
     assert "could not resolve coord-tui's latest release" in result.output
     assert not dest.exists()
@@ -514,6 +541,66 @@ def test_tui_update_force_overwrites_dev_build(stub_server, tmp_path: Path) -> N
     assert out == f"coord-tui {version}"
 
 
+def test_tui_update_v0_1_0_release_is_not_misclassified_as_dev_build(
+    stub_server, tmp_path: Path
+) -> None:
+    """#2984 regression, pinned at the CLI level.
+
+    `DEV_BUILD_SENTINEL_VERSION` is `"0.1.0"` -- and that is ALSO coord-tui's
+    real first release tag, because `release-tui.yml` stamps the tag straight
+    over `Cargo.toml`'s committed placeholder, and the one tag that
+    reproduces the placeholder exactly is the one every new release channel
+    starts on. A host that already carries a CI-built v0.1.0 binary must be
+    able to run `coord tui update` again, with no `--force`, and have that
+    recognised as "already current" -- not refused as if it were a dev
+    build someone is iterating on.
+    """
+    from coord.tui_release import DEV_BUILD_SENTINEL_VERSION
+
+    version = DEV_BUILD_SENTINEL_VERSION
+    assert version == "0.1.0"  # fixture assumption: this IS the colliding tag
+    dest = _installed(tmp_path, version)
+
+    server = stub_server
+    lpath, lpayload = _latest_route(version)
+    server.routes[lpath] = ("json", lpayload)
+    # No asset/download routes registered: reaching the download would 404,
+    # proving the "already current" short-circuit is what actually fired.
+
+    result = CliRunner().invoke(
+        main,
+        [
+            "tui", "update",
+            "--repo", REPO,
+            "--api-base", _api_base(server),
+            "--dest", str(dest),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert "nothing to do" in result.output
+    assert "refusing to overwrite" not in result.output
+    # Untouched -- the same bytes that were already there, not re-downloaded.
+    assert dest.read_bytes() == _fake_binary(version)
+
+
+def test_is_dev_build_does_not_misclassify_the_v0_1_0_collision(tmp_path: Path) -> None:
+    """#2984 regression, at the `tui_release.is_dev_build` unit level -- no
+    CLI or network involved. A sentinel-versioned binary whose
+    `target_version` (the release a run resolved as "the one to install") is
+    that very same value must not be reported as a dev build; that's exactly
+    the v0.1.0 collision. Omitting `target_version` keeps the old,
+    collision-prone, version-only check, asserted here as a control so this
+    test would fail loudly if that fallback ever silently changed too."""
+    from coord.tui_release import DEV_BUILD_SENTINEL_VERSION, is_dev_build
+
+    binary = _installed(tmp_path, DEV_BUILD_SENTINEL_VERSION)
+
+    assert is_dev_build(binary) is True
+    assert is_dev_build(binary, target_version=DEV_BUILD_SENTINEL_VERSION) is False
+    assert is_dev_build(binary, target_version="0.9.9") is True
+
+
 # ── version-skew notice (`coord tui status`, and bare `coord tui`) ─────────
 #
 # #2898's acceptance criterion: `coord tui status` compares against coord-tui's