feat(run): preflight Cloudflare AI Gateway seats for required env vars (#394)

Preflight every child-launch path (direct worker, grok invalid-final fallback,
orchestrator) for cloudflare-ai-gateway/ routes: roster doctor and dispatch fail
before launching the child when CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_GATEWAY_ID are
missing, classified as provider configuration (not a generic adapter error) in
worker results, run.json, and the human summary. Names only, never values.

Closes #394

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

src/brigade/aboyeur.py

@@ -725,6 +725,15 @@ def _run_orchestrator(
             ok=False,
             detail="codex-cloud seats are workers only; pick a local CLI for the orchestrator",
         )
+    cloudflare_detail = agents.cloudflare_ai_gateway_preflight_detail(orchestrator.model)
+    if cloudflare_detail is not None:
+        return agents.AgentResult(
+            text="",
+            ok=False,
+            detail=cloudflare_detail,
+            failure_phase="preflight",
+            failure_kind="provider-config",
+        )
     kwargs: dict[str, object] = {
         "timeout": timeout_for(orchestrator, roster),
         "cwd": cwd,
@@ -1951,6 +1960,8 @@ def _run_payload(
         payload["error"] = error
         if failure_phase is not None or failure_kind is not None:
             payload["failure_phase"] = failure_phase or "unknown"
+            if failure_kind is not None:
+                payload["failure_kind"] = failure_kind
             failure_payload: dict[str, object] = {
                 "phase": failure_phase or "unknown",
                 "kind": failure_kind or "unknown",
@@ -2333,6 +2344,12 @@ def _payload(**kwargs: Any) -> dict[str, object]:
             if output_dir is not None:
                 finished_at = datetime.now(timezone.utc)
                 _write_json(output_dir / "plan-attempts.json", {"attempts": plan_attempts or []})
+                failure_phase = "planning"
+                if isinstance(final_attempt, dict):
+                    attempt_phase = final_attempt.get("failure_phase")
+                    attempt_kind = final_attempt.get("failure_kind")
+                    if attempt_phase == "preflight" and attempt_kind == "provider-config":
+                        failure_phase = "preflight"
                 _write_json(
                     output_dir / "run.json",
                     _payload(
@@ -2346,7 +2363,7 @@ def _payload(**kwargs: Any) -> dict[str, object]:
                         finished_at=finished_at,
                         output_dir=output_dir,
                         error=str(exc),
-                        failure_phase="planning",
+                        failure_phase=failure_phase,
                         failure_kind=failure_kind,
                         failure_seat=roster.orchestrator,
                         code_graph=code_graph,

src/brigade/agents.py

@@ -12,6 +12,7 @@
 import os
 import re
 import unicodedata
+from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Callable, List
@@ -21,6 +22,8 @@
 
 _OLLAMA_PREFIX = "ollama:"
 _CODEX_CLOUD_PREFIX = "codex-cloud:"
+_CLOUDFLARE_AI_GATEWAY_PREFIX = "cloudflare-ai-gateway/"
+_CLOUDFLARE_AI_GATEWAY_REQUIRED_ENV = ("CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_GATEWAY_ID")
 _NONRECOVERABLE_GROK_OUTPUT_FAILURES = frozenset(
     {
         "provider-error",
@@ -578,6 +581,50 @@ def secret_ref_targets(env: dict[str, str]) -> set[str]:
     return {key[: -len("_REF")] for key in env if key.endswith("_REF") and key != "_REF"}
 
 
+def is_cloudflare_ai_gateway_route(model: str | None) -> bool:
+    """Return True if the model route is a Cloudflare AI Gateway route.
+
+    The first path segment must be exactly ``cloudflare-ai-gateway``, not a
+    substring such as ``cloudflare-ai-gateway-other``.
+    """
+
+    if not model:
+        return False
+    if not model.startswith(_CLOUDFLARE_AI_GATEWAY_PREFIX):
+        return False
+    return len(model) > len(_CLOUDFLARE_AI_GATEWAY_PREFIX)
+
+
+def missing_cloudflare_ai_gateway_env_vars(
+    env: Mapping[str, str] | None = None,
+) -> list[str]:
+    """Return the required Cloudflare AI Gateway env vars that are missing.
+
+    Reads only variable names and presence; never reads or prints values.
+    Empty strings count as missing.
+    ``env`` defaults to ``os.environ``.
+    """
+
+    if env is None:
+        env = os.environ
+    return [name for name in _CLOUDFLARE_AI_GATEWAY_REQUIRED_ENV if not env.get(name)]
+
+
+def cloudflare_ai_gateway_preflight_detail(model: str | None) -> str | None:
+    """Return a provider-config detail if the Cloudflare route lacks env.
+
+    Empty string values are treated as missing. Returns None when the route is
+    not a Cloudflare AI Gateway route or when all required env vars are present.
+    """
+
+    if not is_cloudflare_ai_gateway_route(model):
+        return None
+    missing = missing_cloudflare_ai_gateway_env_vars()
+    if not missing:
+        return None
+    return f"Cloudflare AI Gateway seat missing required env vars: {', '.join(missing)}; set them before running"
+
+
 _MIN_SCRUB_VALUE_LENGTH = 8
 _COMBINING_MARK_CATEGORIES = frozenset({"Mn", "Mc", "Me"})
 

src/brigade/roster_cmd.py

@@ -195,6 +195,22 @@ def doctor(target: Path, *, roster_path: Path | None = None) -> int:
                         f"{agent.cli} does not support model pinning; drop model= or switch cli",
                     )
                 )
+            # Endpoint-mode agents are intentionally exempt: their model is a
+            # remote HTTP model name, not a local CLI route that needs Cloudflare
+            # env vars (the cli=None branch above already continued past this).
+            if agents.is_cloudflare_ai_gateway_route(agent.model):
+                missing = agents.missing_cloudflare_ai_gateway_env_vars()
+                label = f"agent: {name} cloudflare gateway"
+                if missing:
+                    checks.append(
+                        (
+                            doctor_mod.FAIL,
+                            label,
+                            f"requires env vars: {', '.join(missing)}; set them before running",
+                        )
+                    )
+                else:
+                    checks.append((doctor_mod.OK, label, "required env vars are set"))
         if agent.reasoning is not None:
             if agents.supports_reasoning(agent.cli):
                 checks.append((doctor_mod.OK, f"agent: {name} reasoning", f"{agent.reasoning} via {agent.cli}"))

src/brigade/run_transport.py

@@ -72,6 +72,26 @@ def _is_direct_grok_invalid_final(
     )
 
 
+def _cloudflare_preflight_failure(agent: Agent, assignment: Assignment) -> WorkerResult | None:
+    """Return a preflight failure if the agent's Cloudflare route lacks env.
+
+    Empty string values are treated as missing.
+    """
+
+    detail = agents.cloudflare_ai_gateway_preflight_detail(agent.model)
+    if detail is None:
+        return None
+    return WorkerResult(
+        worker=assignment.worker,
+        task=assignment.task,
+        text="",
+        ok=False,
+        detail=detail,
+        failure_phase="preflight",
+        failure_kind="provider-config",
+    )
+
+
 def _worker_attempt(
     *,
     kind: str,
@@ -280,6 +300,9 @@ def run_one(assignment: Assignment, prior_results: list[WorkerResult]) -> Worker
                     else f"{agent.cli} is not allowed by limits.allow_models"
                 ),
             )
+        preflight = _cloudflare_preflight_failure(agent, assignment)
+        if preflight is not None:
+            return preflight
         prompt = build_prompt(
             agent,
             assignment,
@@ -549,6 +572,21 @@ def finish(
             return finish(missing_fallback, agent, attempts)
 
         fallback_agent = roster.agents[fallback_name]
+        fallback_cloudflare_detail = agents.cloudflare_ai_gateway_preflight_detail(fallback_agent.model)
+        if fallback_cloudflare_detail is not None:
+            # Route through finish() so the accumulated grok attempt history and
+            # elapsed duration are preserved in the persisted WorkerResult.
+            return finish(
+                agents.AgentResult(
+                    text="",
+                    ok=False,
+                    detail=fallback_cloudflare_detail,
+                    failure_phase="preflight",
+                    failure_kind="provider-config",
+                ),
+                fallback_agent,
+                attempts,
+            )
         fallback_prompt = build_prompt(
             fallback_agent,
             assignment,

tests/test_aboyeur.py

@@ -3154,6 +3154,63 @@ def fake_run_agent(cli_ref, prompt, timeout=600.0, cwd=None, read_only=False):
     }
 
 
+def test_orchestrator_cloudflare_preflight_fails_before_plan_and_reaches_run_json(monkeypatch, tmp_path, capsys):
+    _CF_MODEL_ROUTE = "cloudflare-ai-gateway/openai/gpt-5.3-codex"
+    _FAKE_CF_ACCOUNT = "fake-account-id-for-test"
+    _FAKE_CF_GATEWAY = "fake-gateway-id-for-test"
+
+    roster = Roster(
+        orchestrator="chef",
+        agents={
+            "chef": Agent(
+                name="chef",
+                cli="codex",
+                role="plan",
+                model=_CF_MODEL_ROUTE,
+            ),
+            "coder": Agent(name="coder", cli="codex", role="worker"),
+        },
+        max_workers=1,
+    )
+
+    def should_not_run(*args, **kwargs):  # noqa: ARG001
+        raise AssertionError("agents.run_agent must not be called when Cloudflare orchestrator env is missing")
+
+    monkeypatch.setattr(aboyeur.agents, "run_agent", should_not_run)
+    monkeypatch.delenv("CLOUDFLARE_ACCOUNT_ID", raising=False)
+    monkeypatch.delenv("CLOUDFLARE_GATEWAY_ID", raising=False)
+
+    output_dir = tmp_path / "run"
+    rc = aboyeur.run(
+        "build feature",
+        roster,
+        output_dir=output_dir,
+        code_graph_enabled=False,
+        route_enabled=False,
+    )
+
+    assert rc == 2
+    err = capsys.readouterr().err
+    assert "orchestrator failed during plan" in err
+    assert "Cloudflare AI Gateway" in err
+    run_meta = json.loads((output_dir / "run.json").read_text())
+    assert run_meta["status"] == "failed"
+    assert run_meta["failure_phase"] == "preflight"
+    assert run_meta["failure_kind"] == "provider-config"
+    assert run_meta["failure"] == {
+        "phase": "preflight",
+        "kind": "provider-config",
+        "detail": (
+            "orchestrator failed during plan: "
+            "Cloudflare AI Gateway seat missing required env vars: "
+            "CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_GATEWAY_ID; set them before running"
+        ),
+        "seat": "chef",
+    }
+    assert _FAKE_CF_ACCOUNT not in str(run_meta)
+    assert _FAKE_CF_GATEWAY not in str(run_meta)
+
+
 def test_synthesis_failure_writes_artifact(monkeypatch, tmp_path, capsys):
     calls = []
 

tests/test_agents.py

@@ -1677,3 +1677,55 @@ def test_run_agent_env_ref_empty_value_is_typed_failure(monkeypatch):
     assert not result.ok
     assert result.failure_kind == "env-ref-missing"
     assert "is not set or is empty" in result.detail
+
+
+_CF_MODEL_ROUTE = "cloudflare-ai-gateway/openai/gpt-5.3-codex"
+
+
+@pytest.mark.parametrize(
+    ("route", "expected"),
+    [
+        (_CF_MODEL_ROUTE, True),
+        ("cloudflare-ai-gateway-other/openai/gpt-5.3-codex", False),
+        ("openai-cloudflare-ai-gateway/gpt-5.3-codex", False),
+        ("foo/cloudflare-ai-gateway/openai/gpt-5.3-codex", False),
+        (None, False),
+        ("", False),
+    ],
+)
+def test_is_cloudflare_ai_gateway_route(route, expected):
+    assert agents.is_cloudflare_ai_gateway_route(route) is expected
+
+
+def test_missing_cloudflare_ai_gateway_env_vars_both_missing():
+    assert agents.missing_cloudflare_ai_gateway_env_vars({}) == [
+        "CLOUDFLARE_ACCOUNT_ID",
+        "CLOUDFLARE_GATEWAY_ID",
+    ]
+
+
+@pytest.mark.parametrize(
+    ("env", "expected_missing"),
+    [
+        ({"CLOUDFLARE_ACCOUNT_ID": "fake-account-id-for-test"}, ["CLOUDFLARE_GATEWAY_ID"]),
+        ({"CLOUDFLARE_GATEWAY_ID": "fake-gateway-id-for-test"}, ["CLOUDFLARE_ACCOUNT_ID"]),
+        (
+            {
+                "CLOUDFLARE_ACCOUNT_ID": "fake-account-id-for-test",
+                "CLOUDFLARE_GATEWAY_ID": "fake-gateway-id-for-test",
+            },
+            [],
+        ),
+    ],
+)
+def test_missing_cloudflare_ai_gateway_env_vars_partial(env, expected_missing):
+    assert agents.missing_cloudflare_ai_gateway_env_vars(env) == expected_missing
+
+
+def test_missing_cloudflare_ai_gateway_env_vars_empty_string_counts_as_missing():
+    assert agents.missing_cloudflare_ai_gateway_env_vars(
+        {
+            "CLOUDFLARE_ACCOUNT_ID": "",
+            "CLOUDFLARE_GATEWAY_ID": "fake-gateway-id-for-test",
+        }
+    ) == ["CLOUDFLARE_ACCOUNT_ID"]

tests/test_roster_cmd.py

@@ -1,5 +1,7 @@
 from pathlib import Path
 
+import pytest
+
 from brigade import agents
 from brigade import cli
 from brigade import model_inventory
@@ -416,6 +418,68 @@ def test_roster_doctor_fails_pin_on_ollama_ref(monkeypatch, tmp_target, capsys):
     assert "ollama names its model in the cli ref" in out
 
 
+_CF_MODEL_ROUTE = "cloudflare-ai-gateway/openai/gpt-5.3-codex"
+_FAKE_CF_ACCOUNT = "fake-account-id-for-test"
+_FAKE_CF_GATEWAY = "fake-gateway-id-for-test"
+
+
+def _write_cloudflare_gateway_roster(tmp_target) -> None:
+    _write_roster(
+        tmp_target,
+        'orchestrator = "chef"\n'
+        '[agents.chef]\ncli = "codex"\nmodel = "gpt-5.5"\nrole = "plan"\n'
+        f'[agents.cf_worker]\ncli = "codex"\nmodel = "{_CF_MODEL_ROUTE}"\nrole = "worker"\n',
+    )
+
+
+def _clear_cloudflare_gateway_env(monkeypatch) -> None:
+    monkeypatch.delenv("CLOUDFLARE_ACCOUNT_ID", raising=False)
+    monkeypatch.delenv("CLOUDFLARE_GATEWAY_ID", raising=False)
+
+
+def test_roster_doctor_ok_for_cloudflare_gateway_when_env_present(monkeypatch, tmp_target, capsys):
+    _write_cloudflare_gateway_roster(tmp_target)
+    _clear_cloudflare_gateway_env(monkeypatch)
+    monkeypatch.setattr(agents.proc, "which", lambda cmd: "/x/" + cmd)
+    monkeypatch.setenv("CLOUDFLARE_ACCOUNT_ID", _FAKE_CF_ACCOUNT)
+    monkeypatch.setenv("CLOUDFLARE_GATEWAY_ID", _FAKE_CF_GATEWAY)
+
+    rc = roster_cmd.doctor(tmp_target)
+    out = capsys.readouterr().out
+
+    assert rc == 0
+    assert "[ok]   agent: cf_worker cloudflare gateway" in out
+    assert "required env vars are set" in out
+    assert _FAKE_CF_ACCOUNT not in out
+    assert _FAKE_CF_GATEWAY not in out
+
+
+@pytest.mark.parametrize(
+    ("env", "missing_vars"),
+    [
+        ({}, ("CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_GATEWAY_ID")),
+        ({"CLOUDFLARE_ACCOUNT_ID": _FAKE_CF_ACCOUNT}, ("CLOUDFLARE_GATEWAY_ID",)),
+        ({"CLOUDFLARE_GATEWAY_ID": _FAKE_CF_GATEWAY}, ("CLOUDFLARE_ACCOUNT_ID",)),
+    ],
+)
+def test_roster_doctor_fails_cloudflare_gateway_when_env_missing(monkeypatch, tmp_target, capsys, env, missing_vars):
+    _write_cloudflare_gateway_roster(tmp_target)
+    _clear_cloudflare_gateway_env(monkeypatch)
+    monkeypatch.setattr(agents.proc, "which", lambda cmd: "/x/" + cmd)
+    for name, value in env.items():
+        monkeypatch.setenv(name, value)
+
+    rc = roster_cmd.doctor(tmp_target)
+    out = capsys.readouterr().out
+
+    assert rc == 1
+    assert "[fail] agent: cf_worker cloudflare gateway" in out
+    for var in missing_vars:
+        assert var in out
+    assert _FAKE_CF_ACCOUNT not in out
+    assert _FAKE_CF_GATEWAY not in out
+
+
 def test_roster_doctor_endpoint_agent_skips_pin_check(tmp_target, capsys):
     _write_roster(
         tmp_target,