code-coordinator 0.5.147__tar.gz → 0.5.148__tar.gz

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.147
+Version: 0.5.148
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -506,6 +506,8 @@ after publication.
   overnight drives.
 - [`docs/PHONE_WEBAPP.md`](docs/PHONE_WEBAPP.md) — build and serve the phone control-center PWA
   over Tailscale.
+- [`docs/ADR_COORD_WEB_DIST.md`](docs/ADR_COORD_WEB_DIST.md) — how a built `coord-web` bundle
+  reaches the daemon host, and the alternatives rejected.
 - [`docs/AGENT_OPERATIONS.md`](docs/AGENT_OPERATIONS.md) — agent install, upgrade, and
   releasing to PyPI.
 - [`docs/OPERATING_GOTCHAS.md`](docs/OPERATING_GOTCHAS.md) — traps that cost a real dispatch or

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/README.md

@@ -466,6 +466,8 @@ after publication.
   overnight drives.
 - [`docs/PHONE_WEBAPP.md`](docs/PHONE_WEBAPP.md) — build and serve the phone control-center PWA
   over Tailscale.
+- [`docs/ADR_COORD_WEB_DIST.md`](docs/ADR_COORD_WEB_DIST.md) — how a built `coord-web` bundle
+  reaches the daemon host, and the alternatives rejected.
 - [`docs/AGENT_OPERATIONS.md`](docs/AGENT_OPERATIONS.md) — agent install, upgrade, and
   releasing to PyPI.
 - [`docs/OPERATING_GOTCHAS.md`](docs/OPERATING_GOTCHAS.md) — traps that cost a real dispatch or

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.147
+Version: 0.5.148
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -506,6 +506,8 @@ after publication.
   overnight drives.
 - [`docs/PHONE_WEBAPP.md`](docs/PHONE_WEBAPP.md) — build and serve the phone control-center PWA
   over Tailscale.
+- [`docs/ADR_COORD_WEB_DIST.md`](docs/ADR_COORD_WEB_DIST.md) — how a built `coord-web` bundle
+  reaches the daemon host, and the alternatives rejected.
 - [`docs/AGENT_OPERATIONS.md`](docs/AGENT_OPERATIONS.md) — agent install, upgrade, and
   releasing to PyPI.
 - [`docs/OPERATING_GOTCHAS.md`](docs/OPERATING_GOTCHAS.md) — traps that cost a real dispatch or

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/code_coordinator.egg-info/SOURCES.txt

@@ -365,6 +365,7 @@ deploy/coord-web-dist-build.timer
 deploy/coord-web-rollback.sh
 deploy/coord-web.service
 deploy/node-shim.sh
+docs/ADR_COORD_WEB_DIST.md
 docs/AGENT_OPERATIONS.md
 docs/ARCHITECTURE.md
 docs/ARCH_SECURITY_GATES.md

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/code_coordinator.egg-info/scm_file_list.json

@@ -343,6 +343,7 @@
     "deploy/coord-web-rollback.sh",
     "deploy/coord-web.service",
     "deploy/node-shim.sh",
+    "docs/ADR_COORD_WEB_DIST.md",
     "docs/AGENT_OPERATIONS.md",
     "docs/ARCHITECTURE.md",
     "docs/ARCH_SECURITY_GATES.md",

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.147",
+  "tag": "0.5.148",
   "distance": 0,
-  "node": "gbf9c09b2b36fbbb594b25c03bc8ef7844050cd84",
+  "node": "gc274183d70afe3f92607c261ef1ba839d2fb672a",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-18"

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/coord/commands/lifecycle.py

@@ -404,7 +404,7 @@ def web(
     # #1237: function-local + guarded — see _start_agent_server for why.
     with server_extra_guard("web"):
         import uvicorn
-        from coord.dashboard.server import build_app
+        from coord.dashboard.server import build_app, dist_has_bundle
         from coord.dashboard.terminal import resolve_web_token
 
     fixture = None
@@ -438,7 +438,26 @@ def web(
     app = build_app(cfg, token=token, fixture=fixture, dist_path=dist_path)
     click.echo(f"coord web: dashboard at http://{bind_host}:{bind_port}")
     if dist_path is not None:
-        click.echo(f"  serving webapp bundle from {dist_path} (#1543)")
+        # #2003: this used to unconditionally claim "serving webapp bundle
+        # from {dist_path}" even when that path was missing or empty — the
+        # server itself silently falls back to the legacy single-file
+        # dashboard in that case (build_app / index()), so the operator saw
+        # a success message for what was actually a silent regression to the
+        # legacy UI. Share the exact predicate build_app's index() route uses
+        # (dist_has_bundle) so this message can never drift from what
+        # actually gets served (#2096: two surfaces answering the same
+        # question must call the same function).
+        if dist_has_bundle(dist_path):
+            click.echo(f"  serving webapp bundle from {dist_path} (#1543)")
+        else:
+            click.echo(
+                f"  warning: --dist {dist_path} has no index.html (missing "
+                "or empty directory) — falling back to the legacy "
+                "single-file dashboard, NOT the bundle you pointed at. "
+                "Check the path / the build hook that populates it "
+                "(#2003).",
+                err=True,
+            )
     if fixture is not None:
         click.echo(
             f"  fixture mode: seeded board from {fixture_path} — reads are "

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/coord/dashboard/server.py

@@ -46,6 +46,22 @@ DASHBOARD_DIR = Path(__file__).parent
 # that existing behaviour (and the test suite) is completely unaffected.
 WEBAPP_DIST = DASHBOARD_DIR / "webapp" / "dist"
 
+
+def dist_has_bundle(dist_path: Path) -> bool:
+    """Does ``dist_path`` contain a servable built webapp bundle?
+
+    This is the single definition of "valid bundle" for the dashboard: the
+    ``index()`` route below uses it to decide whether to serve the built
+    React app or fall back to the legacy single-file dashboard, and
+    ``coord web``'s CLI (coord/commands/lifecycle.py) uses it to decide
+    whether to print a success or warning message. Both call sites MUST
+    share this function rather than re-deriving the check, so the CLI's
+    message can never drift from what the server actually serves (#2003,
+    epic #2096).
+    """
+    return (dist_path / "index.html").exists()
+
+
 # How often (seconds) the background poller queries agent servers.
 _POLL_INTERVAL = 30.0
 # How long (seconds) an assignment must be running with no agent record before
@@ -698,7 +714,7 @@ def build_app(
         # Serve the built React webapp when available; fall back to the legacy
         # single-file dashboard so existing behaviour is entirely unchanged.
         spa_index = webapp_dist / "index.html"
-        html = spa_index.read_text() if spa_index.exists() else (DASHBOARD_DIR / "index.html").read_text()
+        html = spa_index.read_text() if dist_has_bundle(webapp_dist) else (DASHBOARD_DIR / "index.html").read_text()
         return HTMLResponse(html)
 
     async def api_board(request: Request) -> JSONResponse:

code_coordinator-0.5.148/docs/ADR_COORD_WEB_DIST.md

@@ -0,0 +1,158 @@
+# ADR: How a built `coord-web` bundle reaches the daemon host
+
+**Status:** Accepted
+**Date:** 2026-08-18
+**Issue:** #2004 (UX-2, Phase 1 of milestone #62, epic #2002). Blocks UX-4
+("CI must know what it publishes") and UX-7.
+
+## Context
+
+`coord/dashboard/webapp/**` is moving out of this repo into its own
+`coord-web` repo. Today, before that split, the same question already has a
+shipped answer: **[`docs/PHONE_WEBAPP.md`](PHONE_WEBAPP.md), "Going live
+automatically (#1543)."** `deploy/coord-web-dist-build.timer` fires every 10
+minutes (retuned from 1 minute by #2122; see that unit's header), fetches
+`origin/main` read-only, builds it in a dedicated worktree
+(`~/.coord-web-checkout`), health-checks the result on a scratch port before
+ever publishing it (#1560), and atomically repoints `~/coord-web-dist` —
+which `coord web --dist` serves — at the new release. A one-command rollback
+(`coord-web-rollback.sh`) with a rollback-sentinel anti-flap guard exists for
+the class of bug the health check can't see. `coord release verify` already
+has a lane for it: `webapp_bundle` (#1834 lane 5), which grades the live
+bundle's staleness against the `coord/dashboard/webapp/` source tree it
+claims to be built from — deliberately *not* against `--expected`/PyPI,
+because the bundle is versioned by `origin/main`'s SHA on its own continuous
+publish timer, decoupled on purpose from the `~/.coord-venv` release
+cadence. `webapp_build_heartbeat` (#2122) catches the timer going silently
+dead, independent of whether there's unbuilt source to expose it.
+
+The question #2004 poses is really: **once the thing that timer builds lives
+in a different repo, does any of this change in kind, or only in which
+repo(s) it points at?**
+
+## Decision
+
+**Extend the existing mechanism to track `coord-web`'s `main`, instead of
+`coord/dashboard/webapp/` inside this repo.** This is Option 1 from the
+issue, and it is not a new lane so much as a redirection of a lane this
+fleet already built, hardened, and has a release-verify check for.
+
+Concretely, once the split lands:
+
+- `coord-web-dist-build.sh`'s `BASE_CHECKOUT`/`WEBAPP_CHECKOUT` point at a
+  dedicated clone of `coord-web` (never the operator's own checkout, same
+  rule #1543 already enforces) instead of a worktree of this repo.
+- The build step becomes `npm ci && npm run build` at `coord-web`'s repo
+  root instead of `coord/dashboard/webapp/`.
+- The health-check-before-cutover, atomic symlink publish, rollback script,
+  and rollback-sentinel guard carry over **unchanged** — none of that logic
+  is specific to which repo it's building.
+- `coord.health.checks.deploy_lane_facts.resolve_webapp_source_dir` (which
+  scans `ctx.checkouts` for a directory that looks like the webapp source)
+  gets pointed at a `coord-web` checkout's layout instead of
+  `<checkout>/coord/dashboard/webapp/src`. The `webapp_bundle` check's
+  *shape* — dist mtime vs. source mtime, WARN on staleness, never a version
+  comparison — does not change; only the path it looks under does.
+- The PyPI-wheel-bundled fallback path (`coord/dashboard/webapp/dist`
+  vendored into `claude-coordinator`'s own release, #758) stays, unchanged
+  in role: it is the answer for `pip install code-coordinator` on a machine
+  with no `--dist` configured (fresh installs, CI, one-off dev boxes), not
+  the primary path to a running daemon host. This is Option 4, kept
+  deliberately as the fallback it already is today rather than promoted to
+  primary — see "Rejected alternatives" below for why it can't be primary
+  post-split.
+
+## Rejected alternatives
+
+**Option 2 — GitHub release artifact (tarball per `coord-web` release).**
+Versioned and auditable, but it reintroduces exactly the coupling #1543 was
+built to remove: a webapp fix would sit merged-but-not-live until someone
+cuts a release, and nothing today gives that step the ~10-minute, unattended
+cadence the timer already provides. It would also need the health-check
+gate and rollback machinery rebuilt around a fetch/verify/unpack step
+instead of a `git fetch` + worktree build — real new surface for no
+capability the current mechanism lacks. Revisit if `coord-web` ever needs a
+public, pinned distribution channel independent of the daemon host (it
+doesn't today).
+
+**Option 3 — npm package.** Same coupling-to-publish-cadence problem as
+Option 2, plus it adds a registry-auth and install-on-host step to a
+deploy path that currently needs neither. No requirement in this issue
+calls for the bundle to be consumable outside this fleet's own daemon host,
+which is the only scenario where an npm package would earn its cost back.
+
+**Option 4 — vendored at `claude-coordinator` release time, promoted to
+primary.** Rejected as the *primary* path because it re-couples the two
+repos' release cadences — the coupling the split (epic #2002) exists to
+remove. A `coord/dashboard/webapp/**` merge would go live only on
+`claude-coordinator`'s next PyPI release, not within ~10 minutes of merging.
+Kept as the fallback, because that's a real, already-solved problem
+(bootstrapping a `--dist`-less host, or a fresh install) distinct from
+"how does a live daemon host stay current," and downgrading it doesn't cost
+anything the fleet needs today.
+
+**Why Option 1 is not "a fifth silent lane."** The issue's core objection —
+this fleet already has four deploy lanes that go stale with no signal
+(agent venv, `coord-serve`, local `cargo build`, `~/.coord-cli-venv`) — is
+real, but those four go stale because going live requires an *operator* to
+re-run an install step (`pip install --upgrade`, `cargo build`) and nothing
+polls to catch it if they don't. The webapp-dist lane is structurally
+different: it already has (a) an autonomous timer instead of an
+operator-triggered pull, (b) a pre-cutover health check that refuses to
+publish a broken build in the first place, (c) a heartbeat file
+`coord health`/`coord release verify` already read to distinguish "up to
+date" from "the trigger died silently," and (d) a release-verify lane
+(`webapp_bundle`) already wired into the fleet health surface. Extending it
+to a second repo carries all four properties across unchanged — it doesn't
+have to invent them the way a from-scratch Option 2/3 pipeline would.
+
+## Staleness across the split is a different question than staleness today
+
+Pre-split, `coord-web-dist-build.timer` and `~/.coord-venv` build off the
+*same* repo, so "is the live bundle SHA an ancestor of what the daemon was
+built from" is at least answerable in principle. Post-split, `coord-serve`
+(from `claude-coordinator`, versioned by PyPI release) and the webapp bundle
+(from `coord-web`, versioned by its own `main` SHA) are two independently
+released artifacts with **no shared version number** — and per the
+`webapp_bundle` design already in `release_verify.py`, that's intentional:
+grading the bundle against `--expected`/PyPI would "manufacture permanent,
+meaningless skew rather than report a real one." That reasoning holds even
+harder once the source repos are different.
+
+What that does *not* cover, and what genuinely is new here: a phone hitting
+`http://dellserver:7434` can land on a `coord-web` bundle that expects an
+API shape `coord-serve` hasn't shipped yet (or vice versa), because nothing
+before this ADR pins a compatibility floor between the two repos'
+independent cadences. This is a real risk the split introduces — it isn't
+solved by choosing Option 1 over 2/3/4, and it isn't this ADR's job to
+solve, but it should be named so UX-4/UX-7 pick it up rather than
+rediscover it: the daemon already reports its own version
+(`coord/dashboard/server.py`'s `version=__version__`); the cheapest fix is
+likely a minimum-compatible-API marker the webapp checks against that value
+at load and degrades visibly (banner, not a silent break) on mismatch,
+rather than trying to keep the two repos' releases in lockstep.
+
+Propagation lag itself (a phone briefly on a bundle one merge behind the
+daemon, or vice versa) is not new and not a defect — it's the same ~10-minute
+window the timer already runs at for the single-repo case (retuned from the
+original 1-minute cadence #1543 documents; see #2122 and
+`deploy/coord-web-dist-build.timer`'s header for why). It stays detectable
+the same way: the release directory is named after the
+`coord-web` SHA it was built from, and `webapp_build_heartbeat` proves the
+timer is still alive.
+
+## Consequences
+
+- `coord release verify`'s `webapp_bundle` lane keeps working post-split
+  with a path/repo-target change, not a redesign — satisfying this issue's
+  "whichever option wins should be assertable by it" requirement at close
+  to zero incremental cost.
+- The daemon host needs a second dedicated checkout (`coord-web`, alongside
+  whatever `claude-coordinator` checkout it already keeps for other lanes)
+  and a second instance of the build-timer/rollback pairing pointed at it.
+  That's real setup work, tracked under UX-4/UX-7, not a design question.
+- A `coord-web`↔`coord-serve` compatibility floor is an explicitly named
+  open follow-up, not solved here.
+- Options 2 and 3 remain available to revisit if `coord-web` ever needs a
+  distribution channel independent of this fleet's own daemon host — no
+  requirement in scope today calls for that.

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/docs/PHONE_WEBAPP.md

@@ -126,6 +126,12 @@ cd coord/dashboard/webapp && npm run build
 
 ---
 
+> **Repo split (#2004):** `coord/dashboard/webapp/**` is moving to its own
+> `coord-web` repo (epic #2002). The mechanism below is the answer for how a
+> built bundle reaches this daemon host both before and after that move —
+> see [`docs/ADR_COORD_WEB_DIST.md`](ADR_COORD_WEB_DIST.md) for the decision
+> and the rejected alternatives.
+
 ## Going live automatically (#1543): merged main, not release cadence
 
 **On dellserver in production, a merged `coord/dashboard/webapp/**` change

{code_coordinator-0.5.147 → code_coordinator-0.5.148}/tests/test_dashboard.py

@@ -11,7 +11,7 @@ import pytest
 from starlette.testclient import TestClient
 
 from coord.config import Config
-from coord.dashboard.server import build_app
+from coord.dashboard.server import build_app, dist_has_bundle
 from coord.models import Assignment, Board, Machine, Proposal, Repo
 from coord.state import save_board
 
@@ -1559,6 +1559,151 @@ class TestCLI:
             )
         assert captured.get("dist_path") == Path("/tmp/some-dist-dir")
 
+    @staticmethod
+    def _config_file(tmp_path: Path) -> Path:
+        config_file = tmp_path / "coordinator.yml"
+        config_file.write_text(
+            "repos:\n"
+            "  - name: api\n"
+            "    github: acme/api\n"
+            "    default_branch: main\n"
+            "machines:\n"
+            "  - name: laptop\n"
+            "    host: laptop.tailnet\n"
+            "    repos: [api]\n"
+            "    repo_paths:\n"
+            "      api: /tmp/api\n"
+        )
+        return config_file
+
+    def test_web_dist_env_var_honored(self, tmp_path: Path, coord_db) -> None:
+        """#2003: ``$COORD_WEB_DIST`` alone (no ``--dist`` flag) must thread
+        through to ``build_app(dist_path=...)`` -- the env-var half of the
+        seam a systemd unit / build-hook timer relies on, since it can't pass
+        a CLI flag."""
+        from click.testing import CliRunner
+        from coord.cli import main
+
+        config_file = self._config_file(tmp_path)
+        env_dist = tmp_path / "env-dist"
+
+        captured = {}
+
+        def _fake_build_app(config, *, token=None, session_attacher=None, fixture=None, dist_path=None):
+            captured["dist_path"] = dist_path
+            raise SystemExit(0)
+
+        runner = CliRunner()
+        with patch("coord.dashboard.server.build_app", _fake_build_app):
+            runner.invoke(
+                main,
+                ["web", "--config", str(config_file)],
+                env={"COORD_WEB_DIST": str(env_dist)},
+                catch_exceptions=True,
+            )
+        assert captured.get("dist_path") == env_dist
+
+    def test_web_dist_flag_overrides_env_var(self, tmp_path: Path, coord_db) -> None:
+        """#2003: precedence when both are set -- ``--dist`` wins over
+        ``$COORD_WEB_DIST`` (click's normal flag-over-envvar resolution,
+        pinned here since this is the exact seam a misconfigured deploy
+        would trip over silently)."""
+        from click.testing import CliRunner
+        from coord.cli import main
+
+        config_file = self._config_file(tmp_path)
+        env_dist = tmp_path / "env-dist"
+        flag_dist = tmp_path / "flag-dist"
+
+        captured = {}
+
+        def _fake_build_app(config, *, token=None, session_attacher=None, fixture=None, dist_path=None):
+            captured["dist_path"] = dist_path
+            raise SystemExit(0)
+
+        runner = CliRunner()
+        with patch("coord.dashboard.server.build_app", _fake_build_app):
+            runner.invoke(
+                main,
+                ["web", "--config", str(config_file), "--dist", str(flag_dist)],
+                env={"COORD_WEB_DIST": str(env_dist)},
+                catch_exceptions=True,
+            )
+        assert captured.get("dist_path") == flag_dist
+        assert captured.get("dist_path") != env_dist
+
+    def test_web_dist_missing_prints_loud_warning(self, tmp_path: Path, coord_db) -> None:
+        """#2003: the operationally important case -- ``--dist`` pointing at
+        a directory that doesn't exist must print a clear warning, not the
+        same success message a valid ``--dist`` gets. Before this fix `coord
+        web` printed "serving webapp bundle from {path}" unconditionally,
+        even though the server was silently falling back to the legacy
+        single-file dashboard -- exactly the invisible regression #2003
+        warns about."""
+        from click.testing import CliRunner
+        from coord.cli import main
+
+        config_file = self._config_file(tmp_path)
+        missing_dist = tmp_path / "does-not-exist"
+
+        runner = CliRunner()
+        # Let the real build_app run (cheap, no network); only bail out
+        # before uvicorn.run would block forever serving the app.
+        with patch("uvicorn.run", side_effect=SystemExit(0)):
+            result = runner.invoke(
+                main,
+                ["web", "--config", str(config_file), "--dist", str(missing_dist)],
+                catch_exceptions=True,
+            )
+        assert "warning" in result.output.lower()
+        assert str(missing_dist) in result.output
+        assert "legacy" in result.output.lower()
+        assert f"serving webapp bundle from {missing_dist}" not in result.output
+
+    def test_web_dist_empty_dir_prints_loud_warning(self, tmp_path: Path, coord_db) -> None:
+        """Same as above but the directory exists and is merely empty (no
+        index.html) -- an interrupted/failed build, not a typo'd path."""
+        from click.testing import CliRunner
+        from coord.cli import main
+
+        config_file = self._config_file(tmp_path)
+        empty_dist = tmp_path / "empty-dist"
+        empty_dist.mkdir()
+
+        runner = CliRunner()
+        with patch("uvicorn.run", side_effect=SystemExit(0)):
+            result = runner.invoke(
+                main,
+                ["web", "--config", str(config_file), "--dist", str(empty_dist)],
+                catch_exceptions=True,
+            )
+        assert "warning" in result.output.lower()
+        assert f"serving webapp bundle from {empty_dist}" not in result.output
+
+    def test_web_dist_valid_prints_success_not_warning(self, tmp_path: Path, coord_db) -> None:
+        """Contrast case: a valid ``--dist`` (real index.html present) keeps
+        printing the plain success message with no warning noise."""
+        from click.testing import CliRunner
+        from coord.cli import main
+
+        config_file = self._config_file(tmp_path)
+        valid_dist = tmp_path / "valid-dist"
+        valid_dist.mkdir()
+        (valid_dist / "index.html").write_text("<html></html>")
+
+        runner = CliRunner()
+        with patch("uvicorn.run", side_effect=SystemExit(0)):
+            result = runner.invoke(
+                main,
+                ["web", "--config", str(config_file), "--dist", str(valid_dist)],
+                catch_exceptions=True,
+            )
+        assert f"serving webapp bundle from {valid_dist}" in result.output
+        # No dist-related warning noise -- the unrelated "no bearer token"
+        # warning is expected (no --token passed) and out of scope here.
+        assert "no index.html" not in result.output.lower()
+        assert "falling back to the legacy" not in result.output.lower()
+
 
 class TestSSEEvents:
     """Tests for /events SSE endpoint (issue #214)."""
@@ -1804,3 +1949,69 @@ class TestDistPathOverride:
             r = client.get("/")
         assert r.status_code == 200
         assert "coord module default" in r.text
+
+    def test_dist_path_wins_over_bundled_webapp_dist(self, tmp_path: Path) -> None:
+        """#2003: when BOTH the bundled ``coord/dashboard/webapp/dist`` and an
+        explicit ``dist_path`` resolve to real bundles, the explicit override
+        wins -- pinning the precedence a `coord-web-dist-build.sh` release
+        depends on (it must not silently keep serving a stale packaged
+        dist/ that happens to also exist in the venv)."""
+        bundled = tmp_path / "bundled"
+        bundled.mkdir()
+        (bundled / "index.html").write_text("<html><title>stale bundled dist</title></html>")
+
+        override = self._make_dist(tmp_path, "<html><title>coord dist override</title></html>")
+
+        with patch("coord.dashboard.server.WEBAPP_DIST", bundled):
+            client = TestClient(build_app(_config(), dist_path=override))
+            r = client.get("/")
+        assert r.status_code == 200
+        assert "coord dist override" in r.text
+        assert "stale bundled dist" not in r.text
+
+    def test_missing_dist_path_falls_back_to_legacy_dashboard(self, tmp_path: Path) -> None:
+        """#2003: a ``--dist`` pointing at a directory that does not exist at
+        all must not error or serve a stale bundle -- it falls back to the
+        legacy single-file dashboard, same as the no-override default. This
+        pins the HTTP-layer half of the fallback; ``TestCLI`` below pins that
+        the CLI surfaces a loud warning for this case rather than the plain
+        success message it prints for a valid ``--dist``."""
+        missing = tmp_path / "does-not-exist"
+        client = TestClient(build_app(_config(), dist_path=missing))
+        r = client.get("/")
+        assert r.status_code == 200
+        assert "coord dashboard" in r.text
+        assert "coord dist override" not in r.text
+
+    def test_empty_dist_path_directory_falls_back_to_legacy_dashboard(self, tmp_path: Path) -> None:
+        """Same as above but the directory exists (e.g. an interrupted build
+        left an empty dir) rather than being wholly absent -- both must fail
+        the same way, not just the "doesn't exist" case."""
+        empty = tmp_path / "empty-dist"
+        empty.mkdir()
+        client = TestClient(build_app(_config(), dist_path=empty))
+        r = client.get("/")
+        assert r.status_code == 200
+        assert "coord dashboard" in r.text
+
+
+class TestDistHasBundle:
+    """#2003 (epic #2096): `dist_has_bundle` is the ONE predicate both
+    `index()` (this module) and `coord web`'s CLI (coord/commands/lifecycle.py)
+    call to decide whether a dist directory has a servable bundle -- pinning
+    it directly here guards against the two call sites drifting back apart
+    into independent re-derivations of the same check."""
+
+    def test_true_when_index_html_present(self, tmp_path: Path) -> None:
+        dist = tmp_path / "dist"
+        dist.mkdir()
+        (dist / "index.html").write_text("<html></html>")
+        assert dist_has_bundle(dist) is True
+
+    def test_false_when_directory_missing(self, tmp_path: Path) -> None:
+        assert dist_has_bundle(tmp_path / "does-not-exist") is False
+
+    def test_false_when_directory_empty(self, tmp_path: Path) -> None:
+        empty = tmp_path / "empty"
+        empty.mkdir()
+        assert dist_has_bundle(empty) is False