fix(compat): anchor version regex + add real-fetch and worker-wiring tests

- Anchor _VERSION_RE at both ends so a malformed tail (0.1.0rc1, 0.1.0foo,
  0.1.0.1) is rejected to None ('unknown, proceed') instead of silently
  parsing as stable 0.1.0 and satisfying MIN_BACKEND_CONTRACT.
- Test fetch_backend_version for real via httpx.MockTransport (success/URL,
  missing version, missing/null info, 404/503, non-JSON, connection error)
  plus end-to-end assert_backend_compatible through the real fetch.
- Test the regex anchors explicitly (leading/trailing junk rejected;
  whitespace + leading v permitted).
- Test AgentexWorker._register_agent wiring: guard runs before register_agent,
  incompatible backend blocks registration, no AGENTEX_BASE_URL skips both.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: NiteshDhanpal

src/agentex/lib/core/compat/version_guard.py

@@ -34,8 +34,15 @@
 
 SKIP_ENV = "AGENTEX_SKIP_VERSION_CHECK"
 
-# major.minor.patch, optional `-prerelease`; build metadata (after `+`) is ignored.
-_VERSION_RE = re.compile(r"^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?")
+# Full-string SemVer. Accepts: `1.2.3`, leading `v`, surrounding whitespace, `-prerelease`
+# (captured), `+build` (ignored). Anchored at both ends so a malformed tail (`0.1.0rc1`,
+# `0.1.0.1`) is rejected → None → "unknown, proceed", not silently coerced to stable `0.1.0`.
+_VERSION_RE = re.compile(
+    r"^\s*v?(\d+)\.(\d+)\.(\d+)"  # major.minor.patch
+    r"(?:-([0-9A-Za-z.-]+))?"  # optional -prerelease (captured)
+    r"(?:\+[0-9A-Za-z.-]+)?"  # optional +build metadata (ignored)
+    r"\s*$"
+)
 
 
 class IncompatibleBackendError(RuntimeError):

tests/lib/core/temporal/__init__.py

@@ -0,0 +1,70 @@
+"""AgentexWorker wires the backend version guard into worker startup.
+
+A Temporal worker runs as its own process and never goes through the ACP server
+lifespan, so the guard must run inside `_register_agent` — before `register_agent`,
+and only when `AGENTEX_BASE_URL` is set.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import Mock, AsyncMock
+
+import pytest
+
+from agentex.lib.core.temporal.workers import worker as worker_mod
+from agentex.lib.core.compat.version_guard import IncompatibleBackendError
+
+
+def _worker():
+    # explicit health_check_port so __init__ doesn't read EnvironmentVariables
+    return worker_mod.AgentexWorker(task_queue="test-queue", health_check_port=8080)
+
+
+def _patch_env(monkeypatch, base_url):
+    env = Mock()
+    env.AGENTEX_BASE_URL = base_url
+    fake_cls = Mock()
+    fake_cls.refresh.return_value = env
+    monkeypatch.setattr(worker_mod, "EnvironmentVariables", fake_cls)
+    return env
+
+
+async def test_guard_runs_before_register_agent(monkeypatch):
+    env = _patch_env(monkeypatch, "http://backend")
+    order: list[str] = []
+    guard = AsyncMock(side_effect=lambda *a, **k: order.append("guard"))
+    register = AsyncMock(side_effect=lambda *a, **k: order.append("register"))
+    monkeypatch.setattr(worker_mod, "assert_backend_compatible", guard)
+    monkeypatch.setattr(worker_mod, "register_agent", register)
+
+    await _worker()._register_agent()
+
+    guard.assert_awaited_once_with("http://backend")
+    register.assert_awaited_once_with(env)
+    assert order == ["guard", "register"]  # guard must precede registration
+
+
+async def test_incompatible_backend_blocks_registration(monkeypatch):
+    _patch_env(monkeypatch, "http://backend")
+    guard = AsyncMock(side_effect=IncompatibleBackendError("backend too old"))
+    register = AsyncMock()
+    monkeypatch.setattr(worker_mod, "assert_backend_compatible", guard)
+    monkeypatch.setattr(worker_mod, "register_agent", register)
+
+    with pytest.raises(IncompatibleBackendError):
+        await _worker()._register_agent()
+
+    register.assert_not_awaited()  # fail fast — never register against an unsupported backend
+
+
+async def test_no_base_url_skips_guard_and_registration(monkeypatch):
+    _patch_env(monkeypatch, None)
+    guard = AsyncMock()
+    register = AsyncMock()
+    monkeypatch.setattr(worker_mod, "assert_backend_compatible", guard)
+    monkeypatch.setattr(worker_mod, "register_agent", register)
+
+    await _worker()._register_agent()
+
+    guard.assert_not_awaited()
+    register.assert_not_awaited()

tests/lib/core/temporal/workers/__init__.py

@@ -4,6 +4,7 @@
 
 import asyncio
 
+import httpx
 import pytest
 
 from agentex.lib.core.compat import version_guard as vg
@@ -13,14 +14,49 @@ def _run(coro):
     return asyncio.run(coro)
 
 
+def _patch_transport(monkeypatch, handler):
+    """Make version_guard's httpx.AsyncClient route through an in-memory MockTransport,
+    so fetch_backend_version runs for real (request build, status check, JSON parse)
+    without touching the network. `handler(request) -> httpx.Response` (or raises)."""
+
+    real_client = httpx.AsyncClient  # capture before patching to avoid recursing into the factory
+
+    def factory(**kwargs):
+        kwargs.pop("transport", None)
+        return real_client(transport=httpx.MockTransport(handler), **kwargs)
+
+    monkeypatch.setattr(vg.httpx, "AsyncClient", factory)
+
+
 def test_parse_versions():
     assert vg._parse("0.2.1") == (0, 2, 1, None)
     assert vg._parse("v1.4.0") == (1, 4, 0, None)
     assert vg._parse("0.2.1-rc.1+build5") == (0, 2, 1, "rc.1")  # build metadata ignored
+    assert vg._parse("0.1.0+build5") == (0, 1, 0, None)  # build metadata only, still stable
     assert vg._parse("garbage") is None
     assert vg._parse(None) is None
 
 
+def test_parse_rejects_malformed_tails():
+    # Anchored regex: a junk tail after the triplet must NOT silently parse as stable 0.1.0;
+    # it has to fall through to None (→ unknown / unparseable path), not satisfy the floor.
+    for bad in ("0.1.0rc1", "0.1.0foo", "0.1.0.1", "0.1.0-", "1.2", "0.1.0-rc 1"):
+        assert vg._parse(bad) is None, bad
+
+
+def test_parse_anchored_both_ends():
+    # Leading anchor (^): anything before the triplet (other than whitespace / a `v`) is rejected.
+    for bad in ("foo0.1.0", ">=0.1.0", "x0.1.0", "=0.1.0", "0 0.1.0"):
+        assert vg._parse(bad) is None, bad
+    # Trailing anchor ($): anything after the version (other than whitespace) is rejected.
+    for bad in ("0.1.0 extra", "0.1.0;", "0.1.0/", "0.1.0+", "0.1.0 0.1.0"):
+        assert vg._parse(bad) is None, bad
+    # What the anchors DO permit: surrounding whitespace and an optional leading `v`.
+    assert vg._parse(" 0.1.0 ") == (0, 1, 0, None)
+    assert vg._parse("\tv1.2.3\n") == (1, 2, 3, None)
+    assert vg._parse(" 0.2.0-rc.1 ") == (0, 2, 0, "rc.1")
+
+
 def test_prerelease_precedence():
     k = lambda v: vg._precedence_key(vg._parse(v))  # noqa: E731
     assert k("0.1.0-rc.1") < k("0.1.0")       # prerelease precedes its stable release (SemVer §11)
@@ -81,3 +117,92 @@ async def fake(url, **kw):
 def test_no_base_url_is_noop():
     _run(vg.assert_backend_compatible(None))
     _run(vg.assert_backend_compatible(""))
+
+
+def test_truthy(monkeypatch):
+    for val in ("1", "true", "True", "YES", "on"):
+        monkeypatch.setenv("X_GUARD_FLAG", val)
+        assert vg._truthy("X_GUARD_FLAG")
+    for val in ("0", "false", "no", "off", ""):
+        monkeypatch.setenv("X_GUARD_FLAG", val)
+        assert not vg._truthy("X_GUARD_FLAG")
+    monkeypatch.delenv("X_GUARD_FLAG", raising=False)
+    assert not vg._truthy("X_GUARD_FLAG")  # unset → falsy
+
+
+# --- fetch_backend_version: exercised for real through MockTransport (not mocked out) ---
+
+
+def test_fetch_success_and_url_construction(monkeypatch):
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        seen["method"] = request.method
+        return httpx.Response(200, json={"openapi": "3.1.0", "info": {"version": "0.2.0"}})
+
+    _patch_transport(monkeypatch, handler)
+    assert _run(vg.fetch_backend_version("http://backend/")) == "0.2.0"
+    assert seen["url"] == "http://backend/openapi.json"  # trailing slash trimmed, path appended
+    assert seen["method"] == "GET"
+
+
+def test_fetch_missing_version_field(monkeypatch):
+    _patch_transport(monkeypatch, lambda r: httpx.Response(200, json={"info": {}}))
+    assert _run(vg.fetch_backend_version("http://backend")) is None
+
+
+def test_fetch_missing_info_object(monkeypatch):
+    # `info` absent entirely, and `info: null` — both must coalesce to None, not crash.
+    _patch_transport(monkeypatch, lambda r: httpx.Response(200, json={}))
+    assert _run(vg.fetch_backend_version("http://backend")) is None
+    _patch_transport(monkeypatch, lambda r: httpx.Response(200, json={"info": None}))
+    assert _run(vg.fetch_backend_version("http://backend")) is None
+
+
+def test_fetch_http_error_status(monkeypatch):
+    # raise_for_status() → caught → None (e.g. server has no /openapi.json)
+    _patch_transport(monkeypatch, lambda r: httpx.Response(404, text="not found"))
+    assert _run(vg.fetch_backend_version("http://backend")) is None
+    _patch_transport(monkeypatch, lambda r: httpx.Response(503, text="unavailable"))
+    assert _run(vg.fetch_backend_version("http://backend")) is None
+
+
+def test_fetch_non_json_body(monkeypatch):
+    _patch_transport(monkeypatch, lambda r: httpx.Response(200, text="<html>nope</html>"))
+    assert _run(vg.fetch_backend_version("http://backend")) is None
+
+
+def test_fetch_connection_error(monkeypatch):
+    def handler(request):
+        raise httpx.ConnectError("connection refused", request=request)
+
+    _patch_transport(monkeypatch, handler)
+    assert _run(vg.fetch_backend_version("http://backend")) is None
+
+
+# --- assert_backend_compatible end-to-end: real fetch through MockTransport, not mocked out ---
+
+
+def test_assert_end_to_end_old_backend_raises(monkeypatch):
+    monkeypatch.delenv(vg.SKIP_ENV, raising=False)
+    _patch_transport(monkeypatch, lambda r: httpx.Response(200, json={"info": {"version": "0.0.9"}}))
+    with pytest.raises(vg.IncompatibleBackendError):
+        _run(vg.assert_backend_compatible("http://backend", min_version="0.1.0", sdk_version="0.13.0"))
+
+
+def test_assert_end_to_end_new_backend_passes(monkeypatch):
+    monkeypatch.delenv(vg.SKIP_ENV, raising=False)
+    _patch_transport(monkeypatch, lambda r: httpx.Response(200, json={"info": {"version": "0.2.0"}}))
+    _run(vg.assert_backend_compatible("http://backend", min_version="0.1.0"))
+
+
+def test_assert_end_to_end_unreachable_backend_does_not_raise(monkeypatch):
+    # real fetch returns None on connection failure → guard proceeds (no crash on transient blip)
+    monkeypatch.delenv(vg.SKIP_ENV, raising=False)
+
+    def handler(request):
+        raise httpx.ConnectError("refused", request=request)
+
+    _patch_transport(monkeypatch, handler)
+    _run(vg.assert_backend_compatible("http://backend", min_version="9.9.9"))