Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

Environments: the status is building while a rebuild runs; a task is gated on the active version (#336)

github-actions[bot]068dcc8c4155
diff --git a/gateway/app.py b/gateway/app.py
index 4c203061..5167ff3a 100644
--- a/gateway/app.py
+++ b/gateway/app.py
@@ -15413,7 +15413,7 @@ async def _environment_for_turn(org: str, env_id: str) -> dict | None:
if not v:
raise uhp_error(404, "environment_not_found", "No environment with that id.", "environment")
v = await _environment_refresh(v)
- if str(v.get("status") or "") != "ready" or not str(v.get("active_version") or ""):
+ if not str(v.get("active_version") or ""): # a rebuild in progress keeps the active version serving
raise uhp_error(409, "environment_not_ready",
"The environment has no built version yet: build it, then run the task.", "environment",
{"status": v.get("status") or "empty"})
@@ -15422,6 +15422,21 @@ async def _environment_for_turn(org: str, env_id: str) -> dict | None:
"version": int(v.get("active_version")), "path": f"/env/{slug}"}
+def _env_status(active, latest_rec: dict | None) -> str:
+ """The environment's status from what the runner holds: `building` while a build runs, whichever
+ version is active (a task keeps reading the active one meanwhile; the page shows the build);
+ `ready` when a version is active; `failed` only when the latest build failed and none is active.
+ Measured 2026-09-29: with `ready` winning over a running rebuild, the console never showed a
+ build of an environment that already had a version."""
+ if latest_rec and latest_rec.get("status") == "building":
+ return "building"
+ if active:
+ return "ready"
+ if latest_rec and latest_rec.get("status") == "failed":
+ return "failed"
+ return "empty"
+
+
async def _environment_refresh(v: dict) -> dict:
"""The record, brought up to date with what the runner holds: the source's size, the versions,
the active one and the latest build's status. Persisted when anything moved, so the list (which
@@ -15434,14 +15449,7 @@ async def _environment_refresh(v: dict) -> dict:
src, vers, active = live.get("source") or {}, live.get("versions") or [], live.get("active")
latest = max([int(x.get("version") or 0) for x in vers] or [0])
latest_rec = next((x for x in vers if int(x.get("version") or 0) == latest), None) if latest else None
- if active:
- status = "ready"
- elif latest_rec and latest_rec.get("status") == "building":
- status = "building"
- elif latest_rec and latest_rec.get("status") == "failed":
- status = "failed"
- else:
- status = "empty"
+ status = _env_status(active, latest_rec)
packages = v.get("packages") or "[]"
if active and str(active) != str(v.get("active_version") or ""):
b = await _env_runner("GET", f"/environments/{eid}/build", eid, params={"version": int(active)})
diff --git a/gateway/tests/test_environments.py b/gateway/tests/test_environments.py
index abc72994..7d059563 100644
--- a/gateway/tests/test_environments.py
+++ b/gateway/tests/test_environments.py
@@ -218,3 +218,14 @@ def test_the_package_check_is_the_registrys_answer_and_refuses_a_manager_it_cann
assert r.status_code == 400 and r.json()["error"]["code"] == "environment_invalid"
r = api.get("/v1/environments/packages/check?manager=pip&spec=")
assert r.status_code == 400
+
+
+def test_the_status_says_building_while_a_rebuild_runs_and_ready_wins_over_an_old_failure():
+ """A rebuild of an environment that already has a version is `building` (the page shows the
+ build; the active version keeps serving); `failed` only when nothing is active at all."""
+ assert app._env_status(None, None) == "empty"
+ assert app._env_status(None, {"status": "building"}) == "building"
+ assert app._env_status(1, {"status": "building"}) == "building"
+ assert app._env_status(1, {"status": "ready"}) == "ready"
+ assert app._env_status(1, {"status": "failed"}) == "ready"
+ assert app._env_status(None, {"status": "failed"}) == "failed"
diff --git a/protocol/CHANGELOG.md b/protocol/CHANGELOG.md
index b39b2789..3bf9918d 100644
--- a/protocol/CHANGELOG.md
+++ b/protocol/CHANGELOG.md
@@ -23,8 +23,9 @@ class, 84 of 84, on `post2`.
can show progress ([Environments §4](versions/2026-09-28/environments.md#4-builds-and-versions)).
An optional `GET /v1/environments/packages/check` answers what the manager's registry says about a
spec before any build (`EnvironmentPackageCheck`), so a client can refuse a typo where it is
-typed. Suite `2026.9.28.post3`: EN-09 exercises the check on a server that offers it; reference
-server 0.26.9.
+typed. The environment's `status` is `building` while a build runs, whichever version is active;
+a task keeps reading the active version meanwhile. Suite `2026.9.28.post3`: EN-09 exercises the
+check on a server that offers it; reference server 0.26.10.
- **Environments** ([Environments](versions/2026-09-28/environments.md)), the Environments
sub-protocol, optional at every class behind the `environments` capability. An environment is a
diff --git a/protocol/versions/2026-09-28/environments.md b/protocol/versions/2026-09-28/environments.md
index 7c2cbf00..c88d1f4d 100644
--- a/protocol/versions/2026-09-28/environments.md
+++ b/protocol/versions/2026-09-28/environments.md
@@ -79,7 +79,7 @@ Three rules make it one thing rather than a shared folder:
| `slug` | string | server | The path segment sessions see, derived from the name at creation. It never changes: a session's instructions name it |
| `description` | string | client | |
| `entry` | string | client | How the project is run, in the owner's words. Repeated to the agent verbatim ([§6](#6-what-a-session-sees)) |
-| `status` | string | server | `empty` (nothing built), `building`, `ready` (a version is active), `failed` (the latest build failed and none is active) |
+| `status` | string | server | `empty` (nothing built), `building` (a build is running, whichever version is active: a task keeps reading the active one), `ready` (a version is active), `failed` (the latest build failed and none is active) |
| `mount` | string | server | Where a session finds it, read-only. `/env/<slug>` on the reference server; a server MAY choose another root, and MUST keep it constant for the environment's lifetime |
| `version` | integer or null | server | The active build, the one sessions read |
| `latestVersion` | integer or null | server | The newest build, active or not |
@@ -178,8 +178,10 @@ read-only and stays so.
reason as `error`. While it builds, the record says which step is running as `stage` (on the
reference server: `copying files`, `python packages`, `node packages`, `system packages`,
`setup.sh`, `finishing`) and carries the log so far, so a client can show progress rather than a
-spinner; a server MUST write the record as steps end, not only at the end of the build. One build
-runs at a time per environment (`environment_busy`). When a build
+spinner; a server MUST write the record as steps end, not only at the end of the build. The
+environment's `status` is `building` meanwhile, even when a version is active, and a task on it
+keeps reading the active version. One build runs at a time per environment (`environment_busy`).
+When a build
succeeds it becomes the active version: the next session to start reads it. A session that started
earlier keeps the version it started with for the rest of its turn; a server SHOULD let it keep
that version for later turns too, and MUST say which version a turn read ([§6](#6-what-a-session-sees)).