feat: Enhance model routing and deployment flexibility

- Introduced `vllm_version` to allow per-model inference stack pinning, enabling models to opt for nightly builds when necessary.
- Updated image building logic to handle model-specific vLLM versions, ensuring compatibility with various architectures.
- Added `model_endpoint` to `AgentManifest` for explicit model binding, allowing agents to route to specific models instead of relying solely on profiles.
- Enhanced `ModelRouter` to resolve specific catalogue models, improving routing accuracy and flexibility.
- Updated UI components in the Fishbowl Lab to support new model selection features, ensuring only deployable models are presented.
- Improved tests to validate new model selection and routing behaviors, ensuring robustness and adherence to expected functionality.

docs/adr/0022-per-agent-explicit-model-binding.md

@@ -0,0 +1,88 @@
+# ADR-0022: Per-Agent Explicit Model Binding (`model_endpoint`)
+
+## Status
+
+Accepted
+
+## Context
+
+ADR-0010 gave per-agent model selection through four **logical tiers**
+(`tiny`/`fast`/`balanced`/`strong`), and `config/models.yaml` binds each tier to one
+concrete catalogue model. That is the right default, but it has two limits:
+
+1. **A cast can express at most four distinct models** — one per tier. Two agents on
+   the same tier always share a model.
+2. **The unbound specialist models are unreachable.** Several catalogue entries have
+   `profile=None` (Nemotron Cascade 14B, Nemotron 30B, MiniCPM-o) precisely so they do
+   *not* displace a tier default — but then no manifest could ever cast them.
+
+Both bite the hackathon strategy directly: the unfair advantage is running *different
+sponsor models in one cast* (Judge → Nemotron, a worker → MiniCPM) to qualify for
+multiple tracks from a single submission. And the Fishbowl Lab needed to let a user pick
+concrete Modal-hosted models per cast member — with the pick actually driving the run
+(the Lab's model controls were previously cosmetic: `on_summon` ignored
+`collect_world_config` and always built the scenario's default cast).
+
+## Decision
+
+Add an optional, additive per-agent override that names a **specific catalogue model**,
+leaving the tier system as the default and fallback.
+
+- **Manifest.** `AgentManifest` gains `model_endpoint: str | None = None` — a
+  `modal/catalogue.py` endpoint slug. `None` → route by `model_profile` (unchanged).
+- **Routing.** `ManifestAgent` routes by a **route key** —
+  `self._route_key = model_endpoint or model_profile` — and calls
+  `router.for_profile(self._route_key)`. The `ModelRouter` already accepts any key;
+  `_spec_for` now resolves a non-tier key against the catalogue (`_catalogue_spec`:
+  `modal_catalogue.binding_for(key)` for the live model string / endpoint URL / api key,
+  with decoding inherited from the model's tier — an unbound specialist → `balanced`).
+  An unknown non-tier key degrades to the `fast` tier rather than crashing. Offline this
+  path is never reached: `_build` serves the deterministic stub for any key, with the key
+  folded into the stub's `variant` so a different pick still varies (reproducible) output.
+- **Composed runs.** `Registry.from_world(world)` builds an in-memory registry from a
+  validated `WorldConfig`, so a UI- (or LLM-) composed run flows through the same
+  `build_scenario` / `build_router` / `governor_for` path as a config-file run.
+- **Fishbowl Lab.** The cast section is a `@gr.render` over the scenario: one model
+  `gr.Dropdown` per non-judge player (the Judge picks in §04), its choices sourced *only*
+  from `modal_catalogue.entries()`. Picks accumulate in a `cast_models` state;
+  `collect_world_config` maps each onto the agent's `model_endpoint` (re-checking the key
+  against the catalogue), and `Summon` runs the composed world. Only catalogue-hosted
+  models are offerable, and the selection is load-bearing.
+
+## Consequences
+
+- A cast can pin **any** catalogue model per agent, including the unbound specialists —
+  enabling genuine multi-sponsor-model casts from one engine, one submission.
+- The tier abstraction (ADR-0010) is untouched: it remains the default, the decoding
+  source, the offline-variant tag, and the fallback. `model_endpoint` is purely additive,
+  so every existing manifest, scenario, and test is byte-identical (defaults to `None`).
+- The Lab's model picker is now functional, not cosmetic: the model you choose is the
+  model that speaks (offline → the deterministic stub, demo still reproducible). A bad
+  compose degrades to the scenario's default cast, so Summon never breaks the demo.
+- A run cannot point at an undeployed model: the UI offers only catalogue entries, and
+  `collect_world_config` re-validates the key, dropping anything out-of-band or stale.
+- Offline determinism is preserved end-to-end (the route key, not just the tier, seeds
+  the stub).
+
+## Alternatives considered
+
+- **Per-tier rebinding** (let the run choose which catalogue model backs each of the four
+  tiers): zero engine change, but still capped at four distinct models and still cannot
+  reach the unbound specialists. Rejected as too weak for the multi-sponsor goal.
+- **Widening `ModelProfile` to an arbitrary `str`**: would dissolve the tier contract that
+  drives decoding defaults, the `MODEL_<TIER>` env overrides, and the offline variant.
+  Rejected in favour of a separate, additive field that keeps both concepts crisp.
+
+## Code
+
+- `src/core/manifest.py` — `AgentManifest.model_endpoint`
+- `src/agents/base.py` — `ManifestAgent._route_key`
+- `src/models/router.py` — `ModelRouter._spec_for` / `_catalogue_spec`
+- `src/core/registry.py` — `Registry.from_world`
+- `src/ui/fishbowl/lab.py` — `model_choices`, `_cast_defaults`, `_judge_manifest`, the
+  cast `gr.render`, `collect_world_config`
+- `src/ui/fishbowl/app.py` — `_compose_session`, the `Summon` wiring
+
+See also: ADR-0010 (logical-profile routing), ADR-0011 (declarative validatable config),
+ADR-0015 (LiteLLM gateway to Modal models), ADR-0019 (single model catalogue), ADR-0021
+(Fishbowl Gradio presenter).

docs/architecture/fishbowl-ui.md

@@ -47,14 +47,22 @@ play-head, so concurrent visitors never share a world.
 ### The Lab — compose a run
 
 `lab.py` (`build_lab`) is the full interactive composer (ADR-0021, decision 4): a
-scenario grid, premise / seed / world text fields, a narrator `gr.Dropdown`, an
-**editable cast `gr.Dataframe`** (per-agent model→profile map + temperature override),
-a judge `gr.Group`, a tools `gr.CheckboxGroup`, and budget `gr.Number`/`gr.Slider`
-controls. "Surprise me" rerolls a cast; "Summon" collects the inputs into a per-run
-`WorldConfig`, runs it through `validate_world()` (ADR-0011), builds the `Conductor`,
-and switches to The Show. The Lab's abstract model choices map onto the four engine
-profiles (`tiny`/`fast`/`balanced`/`strong`, ADR-0010); per-agent temperature is a
-per-run override, since temperature is otherwise per-*profile* in `config/models.yaml`.
+scenario grid, premise / seed / world text fields, a narrator `gr.Dropdown`, a
+**per-cast model picker**, a judge `gr.Group`, a tools `gr.CheckboxGroup`, and budget
+`gr.Number`/`gr.Slider` controls.
+
+The cast picker is a `@gr.render` over the scenario: one row per player (name + a model
+`gr.Dropdown`), re-rendered as the cast changes.  Crucially, **every dropdown offers only
+the models actually hosted on Modal** — its choices come from `modal_catalogue.entries()`
+(the catalogue is the single source of truth and loads offline), so you can't cast a model
+that isn't deployable.  Each pick writes the chosen endpoint slug into a `cast_models`
+`gr.State` (`{agent_name: endpoint_key}`); the Judge gets its own catalogue dropdown in
+§04.  "Surprise me" rerolls a cast; **"Summon" makes the choice real**: `collect_world_config`
+maps each selection onto the agent's `model_endpoint` (ADR-0022), runs the per-run
+`WorldConfig` through `validate_world()` (ADR-0011), and `Registry.from_world()` builds a
+`Conductor` on the exact same engine path as a config-file run — so the model you pick is
+the model that speaks (offline → the deterministic stub, demo still reproducible).  A bad
+compose degrades to the scenario's default cast, so Summon never breaks the demo.
 
 ### The Show — watch it unfold
 

docs/architecture/manifest-spec.md

@@ -25,6 +25,7 @@ class AgentManifest(BaseModel):
 
     # Model
     model_profile: ModelProfile      # tiny | fast | balanced | strong
+    model_endpoint: str | None       # optional: pin ONE catalogue model, overriding the tier
 
     # Memory
     memory: MemoryConfig             # window, use_salience, salience_top_k, reflection_threshold
@@ -98,6 +99,15 @@ Logical model tier.  Resolved to a concrete model name at runtime:
 
 The pattern: workers use `fast` or `tiny`; the judge and reflector use `balanced` or `strong`.
 
+### `model_endpoint`
+Optional escape hatch from tiers to a **specific served model**: a `modal/catalogue.py`
+endpoint slug (e.g. `minicpm-4-1-8b`) the router binds this agent to, overriding
+`model_profile`.  `None` (default) → route by tier.  Lets a cast mix concrete sponsor
+models (one mind on MiniCPM, the Judge on Nemotron Cascade), including the *unbound
+specialist* models no tier defaults to.  Offline it folds into the deterministic stub like
+any tier, so demos stay reproducible.  This is what the Fishbowl Lab's per-cast model picker
+writes.  See [model-routing.md](model-routing.md) and ADR-0022.
+
 ### `memory.window`
 Number of recent visible events to include in every prompt (recency-window mode).
 Default: 8.  Reduce to 4–5 for very small models.

docs/architecture/model-routing.md

@@ -17,13 +17,38 @@ names a model.
 ## How a turn resolves a model
 
 ```
-manifest.model_profile  ──►  ModelRouter.for_profile(profile)  ──►  ModelProvider
-        (e.g. "tiny")              (cached per profile)            (concrete model)
+manifest.model_endpoint or model_profile  ──►  ModelRouter.for_profile(key)  ──►  ModelProvider
+        (the agent's "route key")                 (cached per key)              (concrete model)
 ```
 
-`ManifestAgent._complete()` calls `router.for_profile(self.manifest.model_profile)`
-every turn and records the provider's `last_usage` so the conductor can meter
-tokens — and, on the live path, real cost — into the Governor.
+`ManifestAgent` computes a **route key** — `self._route_key`, the explicit
+`model_endpoint` when set, else the `model_profile` tier — and calls
+`router.for_profile(self._route_key)` every turn, recording the provider's
+`last_usage` so the conductor can meter tokens (and, live, real cost) into the
+Governor.  The router accepts either kind of key: a tier resolves to the profile
+default, a catalogue endpoint slug to that specific model's binding.
+
+## Pinning a specific model (`model_endpoint`)
+
+Tiers are the default, but a manifest can pin one mind to a **specific catalogue
+model** by setting `model_endpoint` to an endpoint slug from `modal/catalogue.py`
+(e.g. `minicpm-4-1-8b`).  This overrides the tier and is how a cast mixes concrete
+sponsor models — one worker on MiniCPM, the Judge on Nemotron Cascade — including the
+*unbound specialist* models that no tier defaults to.  See ADR-0022.
+
+```
+ModelRouter._spec_for(key)
+  key in specs                → that ProfileSpec (the four tiers from models.yaml)
+  key is a catalogue endpoint → _catalogue_spec(key): binding_for(key) + the model's
+                                tier decoding (unbound specialist → balanced defaults)
+  unknown non-tier key        → degrade to the fast tier (never crash)
+```
+
+Offline this path is never reached — `_build` serves the deterministic stub for any
+key, with the key folded into the stub's `variant`, so picking a different model still
+varies the (reproducible) output.  The **Fishbowl Lab** writes `model_endpoint` from
+its per-cast model picker, so the model you choose in the UI is the model that runs
+(see [fishbowl-ui.md](fishbowl-ui.md)).
 
 ## Transport: the LiteLLM gateway (live path)
 
@@ -118,7 +143,9 @@ everything on the big model.
 
 ## Code
 
-- `src/models/router.py` — `ModelRouter`, `ProfileSpec`, `_PROFILE_DECODING`
+- `src/models/router.py` — `ModelRouter`, `ProfileSpec`, `_PROFILE_DECODING`, `_catalogue_spec()` (endpoint key → binding)
+- `src/agents/base.py` — `ManifestAgent._route_key` (endpoint-or-tier)
+- `src/core/registry.py` — `Registry.from_world()` (a UI/LLM-composed run on the same path)
 - `src/models/litellm_provider.py` — `LiteLLMProvider` (live transport, real cost)
 - `src/models/modal_catalogue.py` — engine view of the catalogue (key → binding)
 - `src/core/manifest.py` — `resolve_model()` (env → catalogue default)

docs/schema/agent-manifest.md

@@ -28,6 +28,8 @@ schedule:
 
 # Model (resolved to a concrete small model by the ModelRouter)
 model_profile: fast            # tiny ≤4B | fast ≤7B | balanced ≤13B | strong ≤32B
+model_endpoint: null           # optional: pin ONE specific catalogue model (modal/catalogue.py
+                               # endpoint slug, e.g. minicpm-4-1-8b), overriding the tier above
 
 # Memory (a view over the ledger, not separate state)
 memory:
@@ -52,6 +54,12 @@ output_extra_fields: []        # extra payload fields the model is asked for, e.
   reactive, periodic, or both.  Cadence is per-agent; scenarios don't schedule.
 - **`model_profile`** never names a model; the router (config/env) does.  Mix
   tiers freely across a cast.
+- **`model_endpoint`** is the escape hatch from tiers to a *specific* served model:
+  a `modal/catalogue.py` endpoint slug the router resolves to that model's live
+  binding (overriding `model_profile`).  `null` → route by tier.  This is how a cast
+  pins concrete sponsor models — one mind on MiniCPM, the Judge on Nemotron — and what
+  the Fishbowl Lab's per-cast model picker writes.  Offline it folds into the
+  deterministic stub like any tier, so demos stay reproducible.  See ADR-0022.
 - **`handler`** stays `null` for the common case (the generic `ManifestAgent`).
   Set it to a key registered via `@register_handler` for agents that call tools or
   need custom prompt logic; the YAML still supplies all declarative fields.

modal/docs/deploying.md

@@ -81,9 +81,17 @@ changes needed:
 | `reasoning_parser` / `tool_call_parser` / `enable_auto_tool_choice` | OpenAI tool/reasoning features. |
 | `multimodal` / `mm_limits` | Image/audio/video inputs and per-prompt caps.               |
 | `trust_remote_code`     | Required by MiniCPM / Nemotron custom modeling code.           |
+| `vllm_version`          | Per-model inference-stack pin (escape hatch); `None` = the default `VLLM_VERSION`, `"nightly"` = latest nightly wheel, else a pinned version. |
 | `extra_vllm_args`       | Raw `vllm serve` flags appended verbatim (escape hatch).       |
 | `extra_pip` / `env`     | Extra image deps / container env (escape hatch).               |
 
+> **Per-model vLLM version.** The image pins `VLLM_VERSION` (see `service.py`) for
+> reproducible deploys. A single model can override it via `vllm_version` when the
+> pinned release can't serve its architecture — this is scoped to that model's image,
+> so one model's bump never touches another provider's app. The Gemma 4 entries set
+> `vllm_version="nightly"` (plus `transformers>=5.10.2` and `VLLM_USE_FLASHINFER_SAMPLER=0`)
+> because the `gemma4_unified` architecture is unservable on the pinned release.
+
 ### Add a model
 
 Append one `ModelConfig` to the appropriate provider list in `catalogue.py` (tag

modal/service.py

@@ -86,12 +86,16 @@ _BASE_ENV = {
 def build_image(cfg: ModelConfig) -> modal.Image:
     """Build the container image for a model. Layers are cached and shared, so
     text models that only differ in env reuse the same base layers."""
-    image = (
-        modal.Image.from_registry(CUDA_IMAGE, add_python=PYTHON_VERSION)
-        .entrypoint([])  # drop the CUDA image's default entrypoint
-        .uv_pip_install(f"vllm=={VLLM_VERSION}")
-        .env(_BASE_ENV)
-    )
+    image = modal.Image.from_registry(CUDA_IMAGE, add_python=PYTHON_VERSION).entrypoint(
+        []
+    )  # drop the CUDA image's default entrypoint
+    # vLLM version is per-model (defaults to the pinned VLLM_VERSION). A model can
+    # opt into a nightly wheel when the pinned release can't serve its architecture.
+    if cfg.vllm_version == "nightly":
+        image = image.uv_pip_install("vllm", pre=True, extra_index_url="https://wheels.vllm.ai/nightly")
+    else:
+        image = image.uv_pip_install(f"vllm=={cfg.vllm_version or VLLM_VERSION}")
+    image = image.env(_BASE_ENV)
     if cfg.extra_pip:
         image = image.uv_pip_install(*cfg.extra_pip)
     if cfg.env:

src/agents/base.py

@@ -16,6 +16,7 @@ Backward compatibility: Phase-0/1 agents extend Agent directly and are
 unaffected.  The conductor checks ``getattr(agent, "manifest", None)`` to
 decide whether manifest-based routing applies.
 """
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
@@ -42,6 +43,7 @@ _REFLECTION_KIND = "agent.reflected"
 
 # ── minimal interface ─────────────────────────────────────────────────────────
 
+
 class Agent(ABC):
     name: str
 
@@ -58,6 +60,7 @@ class Agent(ABC):
 
 # ── manifest-driven base ──────────────────────────────────────────────────────
 
+
 class ManifestAgent(Agent):
     """Base class for manifest-driven agents.
 
@@ -141,6 +144,16 @@ class ManifestAgent(Agent):
 
     # ── model routing ─────────────────────────────────────────────────────────
 
+    @property
+    def _route_key(self) -> str:
+        """Router key for this agent: the explicit ``model_endpoint`` catalogue key
+        when set (a specific served model), else the logical ``model_profile`` tier.
+
+        The router accepts either — a catalogue key resolves to that model's live
+        binding, a tier to the profile default — so an agent can be pinned to one
+        concrete Modal model without the engine naming a model anywhere (ADR-0022)."""
+        return self.manifest.model_endpoint or self.manifest.model_profile
+
     def _resolve_payload(
         self,
         role: str,
@@ -157,7 +170,7 @@ class ManifestAgent(Agent):
         instruction and run the tolerant parser as before.  Token/cost usage is
         recorded from the provider in both paths.
         """
-        provider = self.router.for_profile(self.manifest.model_profile)
+        provider = self.router.for_profile(self._route_key)
         if hasattr(provider, "complete_structured"):
             model = build_output_model(allowed, extra_fields)
             try:
@@ -176,7 +189,7 @@ class ManifestAgent(Agent):
 
     def _complete(self, role: str, prompt: str) -> str:
         """Route to the provider for this agent's profile and record token usage."""
-        provider = self.router.for_profile(self.manifest.model_profile)
+        provider = self.router.for_profile(self._route_key)
         raw = provider.complete(role, prompt)
         self.last_usage = dict(provider.last_usage)
         return raw
@@ -206,7 +219,7 @@ class ManifestAgent(Agent):
             f"RECENT MEMORY (events you witnessed)\n{memory}\n\n"
             "TASK\nSynthesise the above into ONE short, high-level belief about yourself or the "
             "world. It will replace raw memories in your future context.\n\n"
-            'OUTPUT FORMAT\nReply with a single JSON object and nothing else: '
+            "OUTPUT FORMAT\nReply with a single JSON object and nothing else: "
             '{"kind": "agent.reflected", "text": "<one-sentence belief>"}'
         )
         raw = self._complete(self.manifest.name + "-reflect", prompt)

src/core/manifest.py

@@ -104,6 +104,16 @@ class AgentManifest(BaseModel):
     """Logical profile: resolved to a concrete model name by the provider.
     tiny=<=4B, fast=<=7B, balanced=<=13B, strong=<=32B."""
 
+    model_endpoint: str | None = None
+    """Optional catalogue key (``modal/catalogue.py`` endpoint slug, e.g.
+    ``"minicpm-4-1-8b"``) binding this agent to one *specific* served model,
+    overriding the tier default in ``model_profile``.  None → route by profile.
+
+    This is how a cast mixes concrete sponsor models — one mind on MiniCPM, the
+    Judge on Nemotron — while ``model_profile`` stays the decoding/offline fallback.
+    The router resolves the key against the live catalogue (ADR-0022); offline it
+    folds into the deterministic stub like any profile, so demos stay reproducible."""
+
     # Memory
     memory: MemoryConfig = Field(default_factory=MemoryConfig)
 

src/core/registry.py

@@ -22,7 +22,14 @@ from pathlib import Path
 import yaml
 
 from src.agents.base import Agent, ManifestAgent
-from src.core.config import GovernorConfig, ModelsConfig, ScenarioConfig, validate_agent, validate_scenario
+from src.core.config import (
+    GovernorConfig,
+    ModelsConfig,
+    ScenarioConfig,
+    WorldConfig,
+    validate_agent,
+    validate_scenario,
+)
 from src.core.governor import Governor
 from src.core.manifest import AgentManifest
 from src.models.router import ModelRouter, ProfileSpec
@@ -156,6 +163,21 @@ class Registry:
 
         return cls(agents=agents, scenarios=scenarios, models=models)
 
+    @classmethod
+    def from_world(cls, world: WorldConfig) -> "Registry":
+        """Build an in-memory registry from a composed, validated :class:`WorldConfig`.
+
+        The in-memory mirror of :meth:`from_dir`: agents, scenarios, and model
+        bindings come straight off the world object instead of ``config/``.  So a
+        run composed by the Lab (or an LLM) flows through the exact same
+        ``build_scenario`` / ``build_router`` / ``governor_for`` path as a
+        config-file run — emit a world, validate it, run it.  See ADR-0011 / ADR-0022."""
+        return cls(
+            agents={a.name: a for a in world.agents},
+            scenarios={s.name: s for s in world.scenarios},
+            models=world.models,
+        )
+
     # ── building ───────────────────────────────────────────────────────────────
 
     def build_router(self) -> ModelRouter:

src/models/router.py

@@ -101,13 +101,49 @@ class ModelRouter:
     def _spec_for(self, profile: str) -> ProfileSpec:
         if profile in self.specs:
             return self.specs[profile]
-        decoding = _PROFILE_DECODING.get(profile, _PROFILE_DECODING["fast"])
+        # A key that is not one of the four tiers names a *specific* catalogue model
+        # (an agent's ``model_endpoint``): resolve it to that model's live binding so
+        # a cast can pin concrete Modal models (ADR-0022).  Only reached on the live
+        # path — offline, ``_build`` serves the stub before this runs.
+        if profile not in _PROFILE_DECODING:
+            spec = self._catalogue_spec(profile)
+            if spec is not None:
+                return spec
+            # Unknown non-tier key with no catalogue match → degrade to the fast tier
+            # rather than crash ``resolve_model`` on a key it does not recognise.
+            profile = "fast"
+        decoding = _PROFILE_DECODING[profile]
         return ProfileSpec(
             model=resolve_model(profile),  # type: ignore[arg-type]
             temperature=float(decoding["temperature"]),
             max_tokens=int(decoding["max_tokens"]),
         )
 
+    def _catalogue_spec(self, key: str) -> ProfileSpec | None:
+        """Build a :class:`ProfileSpec` from a catalogue endpoint *key*, or None.
+
+        The model string / endpoint URL / api key come from the catalogue + env
+        (``modal_catalogue.binding_for``); decoding inherits the model's tier default
+        (an unbound specialist model → the balanced tier).  Returns None when the key
+        is not in the catalogue, so the caller can fall back gracefully."""
+        try:
+            from src.models import modal_catalogue
+
+            entry = modal_catalogue.entry_by_key(key)
+            if entry is None:
+                return None
+            binding = modal_catalogue.binding_for(key)
+        except Exception:  # pragma: no cover - defensive: catalogue unavailable
+            return None
+        decoding = _PROFILE_DECODING.get(entry.get("profile") or "balanced", _PROFILE_DECODING["balanced"])
+        return ProfileSpec(
+            model=binding["model"],
+            base_url=binding["base_url"] or None,
+            api_key=binding["api_key"] or None,
+            temperature=float(decoding["temperature"]),
+            max_tokens=int(decoding["max_tokens"]),
+        )
+
     # ── factory ─────────────────────────────────────────────────────────────
 
     @classmethod

src/ui/fishbowl/app.py

@@ -527,6 +527,16 @@ def _wire(
     summon_btn = _h(lab_handles, "summon", "summon_btn", "launch", "start")
     scenario_in = _h(lab_handles, "scenario", "scenario_select", "scenario_dropdown")
     seed_in = _h(lab_handles, "seed", "seed_in", "world_seed")
+    # Composer inputs — the per-cast Modal model picks (cast_models) and the run knobs;
+    # all looked up defensively so the shell still runs if the Lab omits a widget.
+    premise_in = _h(lab_handles, "premise")
+    cast_models_in = _h(lab_handles, "cast_models")
+    judge_model_in = _h(lab_handles, "judge_model")
+    judge_policy_in = _h(lab_handles, "judge_policy")
+    judge_strictness_in = _h(lab_handles, "judge_strictness")
+    tools_in = _h(lab_handles, "tools")
+    tokens_in = _h(lab_handles, "tokens")
+    max_rounds_in = _h(lab_handles, "max_rounds")
 
     def _scenario_title(value) -> str:
         """Resolve a Lab scenario selection (title or internal name) to a title key."""
@@ -537,11 +547,67 @@ def _wire(
                 return title
         return _DEFAULT_TITLE
 
-    # ── Summon: build a fresh session, reset, jump to the Show, render head ──────
-    def on_summon(scenario_value, seed_value, layout, mind_reader):
+    def _compose_session(name, **knobs):
+        """Build a session for a Lab-composed run: the selected Modal models drive the
+        cast (ADR-0022).  The composed WorldConfig flows through ``Registry.from_world``
+        onto the exact same engine path as a config-file run.  Any compose/validate error
+        degrades to the scenario's default cast so Summon always yields a runnable show
+        (and with no credentials the deterministic stub drives it, demo reproducible)."""
+        from src.core.registry import Registry
+        from src.ui.fishbowl.lab import collect_world_config
+
+        try:
+            world = collect_world_config(
+                scenario=name,
+                premise=knobs.get("premise") or "",
+                seed=knobs.get("seed") or "",
+                cast_models=knobs.get("cast_models") if isinstance(knobs.get("cast_models"), dict) else {},
+                judge_policy=knobs.get("judge_policy") or "Majority Vote",
+                judge_model=knobs.get("judge_model") or "",
+                judge_strictness=knobs.get("judge_strictness")
+                if isinstance(knobs.get("judge_strictness"), (int, float))
+                else 50,
+                tools=knobs.get("tools") if isinstance(knobs.get("tools"), list) else [],
+                tokens=knobs.get("tokens") if isinstance(knobs.get("tokens"), (int, float)) else None,
+                max_rounds=knobs.get("max_rounds") if isinstance(knobs.get("max_rounds"), (int, float)) else None,
+            )
+            return FishbowlSession(name, registry=Registry.from_world(world), tools=_tools)
+        except Exception:
+            return _new_session(name)  # bad compose → default cast; Summon never breaks
+
+    # ── Summon: build a fresh session from the composed run, reset, jump to the Show ──
+    def on_summon(
+        scenario_value,
+        seed_value,
+        premise,
+        cast_models,
+        judge_model,
+        judge_policy,
+        judge_strictness,
+        tools,
+        tokens,
+        max_rounds,
+        layout,
+        mind_reader,
+    ):
         title = _scenario_title(scenario_value)
         name = SCENARIOS.get(title, "")
-        session = _new_session(name) if name else None
+        session = (
+            _compose_session(
+                name,
+                premise=premise,
+                seed=seed_value,
+                cast_models=cast_models,
+                judge_model=judge_model,
+                judge_policy=judge_policy,
+                judge_strictness=judge_strictness,
+                tools=tools,
+                tokens=tokens,
+                max_rounds=max_rounds,
+            )
+            if name
+            else None
+        )
         if session is not None:
             session.reset((seed_value or "").strip())
             k = session.head
@@ -555,6 +621,14 @@ def _wire(
         summon_inputs = [
             scenario_in if scenario_in is not None else scenario_state,
             seed_in if seed_in is not None else blank_state,  # empty seed when no widget
+            premise_in if premise_in is not None else blank_state,
+            cast_models_in if cast_models_in is not None else blank_state,
+            judge_model_in if judge_model_in is not None else blank_state,
+            judge_policy_in if judge_policy_in is not None else blank_state,
+            judge_strictness_in if judge_strictness_in is not None else blank_state,
+            tools_in if tools_in is not None else blank_state,
+            tokens_in if tokens_in is not None else blank_state,
+            max_rounds_in if max_rounds_in is not None else blank_state,
             layout_state,
             mind_reader_state,
         ]
@@ -568,30 +642,33 @@ def _wire(
     # Without this, switching to a new world (e.g. the spy game) leaves the premise,
     # seed, cast table, and narrator showing the previous scenario — and Summon would
     # genesis with the wrong seed.  Refreshing them makes "compose a spy game" one click.
+    # The cast picker re-seeds itself (it is a gr.render over the scenario), so it is not
+    # in this list; we re-seed the static fields plus the Judge's default Modal model.
     _scenario_fields = [
         (_h(lab_handles, "premise"), "premise"),
         (seed_in, "seed"),
         (_h(lab_handles, "world"), "world"),
-        (_h(lab_handles, "cast"), "cast"),
         (_h(lab_handles, "narrator"), "narrator"),
+        (_h(lab_handles, "judge_model"), "judge_model"),
     ]
     _present_fields = [(handle, key) for handle, key in _scenario_fields if handle is not None]
 
     if scenario_in is not None and _present_fields:
 
         def on_scenario_change(scenario_value):
-            from src.ui.fishbowl.lab import _cast_rows_for
+            from src.ui.fishbowl.lab import _default_model_key, _judge_manifest
 
             cfg = _registry.scenarios.get(SCENARIOS.get(_scenario_title(scenario_value), ""))
             if cfg is None:
                 return tuple(gr.update() for _ in _present_fields)
             seeds = list(cfg.example_seeds) or [cfg.default_seed]
+            judge = _judge_manifest(cfg)
             updates = {
                 "premise": gr.update(value=cfg.goal),
                 "seed": gr.update(choices=seeds, value=cfg.default_seed),
                 "world": gr.update(value=cfg.genesis_text or ""),
-                "cast": gr.update(value=_cast_rows_for(cfg)),
                 "narrator": gr.update(value=scenario_voice(cfg.name)),
+                "judge_model": gr.update(value=_default_model_key(judge) if judge else None),
             }
             return tuple(updates[key] for _handle, key in _present_fields)
 

src/ui/fishbowl/lab.py

@@ -23,7 +23,9 @@ from __future__ import annotations
 import gradio as gr
 
 from src.core.config import ScenarioConfig, validate_scenario, validate_world
+from src.core.manifest import AgentManifest
 from src.core.registry import default_registry
+from src.models import modal_catalogue
 from src.ui.fishbowl.adapter import VOICES, scenario_voice
 
 # ── design vocabulary (mirrors ui/raw/lab.jsx) ──────────────────────────────────
@@ -37,9 +39,6 @@ JUDGE_POLICIES: list[str] = [
     "Judge's Whim",
 ]
 
-# Logical model profiles the engine understands (manifest.ModelProfile).
-MODEL_PROFILES: list[str] = ["tiny", "fast", "balanced", "strong"]
-
 # MCP tool grants the cast may reach for (friendly label, stored id).  Mirrors
 # ui/raw/lab.jsx:MCP_TOOLS; the value is what we store on the run.
 TOOL_CHOICES: list[tuple[str, str]] = [
@@ -51,9 +50,6 @@ TOOL_CHOICES: list[tuple[str, str]] = [
     ("tts.speak · give it a voice", "tts.speak"),
 ]
 
-# Cast Dataframe columns (editable in the Lab).
-CAST_COLUMNS: list[str] = ["name", "archetype", "model_profile", "temp"]
-
 # The scenario we lead with — the hackathon's north-star world.
 _PREFERRED_SCENARIO = "thousand-token-wood"
 
@@ -77,25 +73,62 @@ def _scenario_by_title(title: str) -> ScenarioConfig | None:
     return None
 
 
-def _cast_rows_for(scenario: ScenarioConfig) -> list[list]:
-    """Seed editable cast rows from a scenario's cast manifests.
+def model_choices() -> list[tuple[str, str]]:
+    """Dropdown choices for the Modal-hosted catalogue: ``(friendly label, endpoint key)``.
+
+    The single source of truth is ``modal/catalogue.py`` (read through the engine's
+    ``modal_catalogue`` view), so the Lab can *only* offer models that are actually
+    deployable — and the list loads offline (the catalogue is a plain stdlib file), so
+    the picker is populated even with no API key.  Empty list → a stripped deployment
+    with no catalogue, in which case the cast falls back to the deterministic stub."""
+    choices: list[tuple[str, str]] = []
+    for entry in modal_catalogue.entries():
+        served = entry["served_model_id"].split("/")[-1]
+        params = f"{entry['params_b']:g}B" if entry.get("params_b") else "?"
+        tier = entry["profile"] or "specialist"
+        provider = entry["provider"].title()
+        choices.append((f"{served} · {params} · {tier} · {provider}", entry["key"]))
+    return choices
+
+
+def _default_model_key(manifest: AgentManifest) -> str | None:
+    """Catalogue key a cast row defaults to: the manifest's explicit ``model_endpoint``,
+    else the catalogue's default model for its tier, else the first catalogue model (or
+    None when the catalogue is empty)."""
+    if manifest.model_endpoint:
+        return manifest.model_endpoint
+    tiered = modal_catalogue.default_key_for_profile(manifest.model_profile)
+    if tiered:
+        return tiered
+    entries = modal_catalogue.entries()
+    return entries[0]["key"] if entries else None
+
+
+def _judge_manifest(scenario: ScenarioConfig) -> AgentManifest | None:
+    """The scenario's judge agent (first ``role == "judge"`` in the cast), or None."""
+    registry = default_registry()
+    for agent_name in scenario.cast:
+        manifest = registry.agents.get(agent_name)
+        if manifest is not None and manifest.role == "judge":
+            return manifest
+    return None
+
 
-    Each row is ``[name, archetype, model_profile, temp]``.  The archetype and
-    model_profile come straight from the agent manifest; temp defaults to 0.8 (the
-    model default) so the column is meaningful but editable.
-    """
+def _cast_defaults(scenario: ScenarioConfig) -> dict[str, str]:
+    """Default model selection for a scenario's *non-judge* cast (name → endpoint key).
+
+    The Judge is bound under §04, so it is excluded here.  Used to seed (and re-seed on
+    scenario change) the ``cast_models`` state the picker writes into."""
     registry = default_registry()
-    rows: list[list] = []
+    defaults: dict[str, str] = {}
     for agent_name in scenario.cast:
         manifest = registry.agents.get(agent_name)
-        if manifest is None:
-            # A scenario referencing an unknown agent shouldn't happen (validate_world
-            # guards it) but degrade gracefully rather than crash the form.
-            rows.append([agent_name, f"the {agent_name}", "fast", 0.8])
+        if manifest is None or manifest.role == "judge":
             continue
-        archetype = manifest.archetype or f"the {manifest.role}"
-        rows.append([manifest.name, archetype, manifest.model_profile, 0.8])
-    return rows
+        key = _default_model_key(manifest)
+        if key:
+            defaults[agent_name] = key
+    return defaults
 
 
 def _voice_choices() -> list[tuple[str, str]]:
@@ -113,8 +146,9 @@ def build_lab() -> dict[str, gr.components.Component]:
     Wires no callbacks and imports no sibling render/show module — the app shell
     (Unit 9) binds ``summon_btn`` to the session.  Returns a dict of every handle a
     caller needs to read the composed run (keys: ``scenario, premise, seed, world,
-    narrator, cast, judge_policy, judge_model, judge_strictness, tools, tokens,
-    max_rounds, seed_num, cadence, summon_btn, surprise_btn``).
+    narrator, cast_models, judge_policy, judge_model, judge_strictness, tools, tokens,
+    max_rounds, seed_num, cadence, summon_btn, surprise_btn``).  ``cast_models`` is a
+    ``gr.State`` holding ``{agent_name: catalogue_endpoint_key}`` for the non-judge cast.
     """
     scenarios = _ordered_scenarios()
     first = scenarios[0]
@@ -160,25 +194,64 @@ def build_lab() -> dict[str, gr.components.Component]:
             lines=2,
         )
 
-    # 03 — The Cast (editable Dataframe)
+    # 03 — The Cast: one Modal-hosted model per mind.  The picker offers ONLY models in
+    # the catalogue (modal/catalogue.py), and the choice drives the run (ADR-0022).  A
+    # gr.render keeps one row per player as the scenario (and its cast size) changes; each
+    # row's dropdown writes the chosen endpoint key into the cast_models state below.
+    cast_models = gr.State(_cast_defaults(first))
+    handles["cast_models"] = cast_models
+    catalogue = model_choices()
     with gr.Group():
         gr.Markdown(
-            "**03 · The Cast** — bind any mind to any model "
-            "(profile: tiny / fast / balanced / strong); watch the expensive one play"
-        )
-        handles["cast"] = gr.Dataframe(
-            value=_cast_rows_for(first),
-            headers=CAST_COLUMNS,
-            datatype=["str", "str", "str", "number"],
-            column_count=len(CAST_COLUMNS),
-            # The grid re-seeds (name/archetype/model) when the scenario changes; it shows
-            # the player roster — a scenario's judge/host is configured under §04, mirroring
-            # the prototype's 4-player spy cast (ui/raw/data.js).
-            row_count=len(first.cast),
-            interactive=True,
-            label="Cast",
+            "**03 · The Cast** — bind each mind to a model **hosted on Modal** "
+            "(the only models you can pick); the Judge is set in §04"
         )
 
+        @gr.render(inputs=[handles["scenario"]])
+        def _render_cast(scenario_value, _choices=catalogue):
+            scenario = _scenario_by_title(scenario_value) or default_registry().scenarios.get(scenario_value)
+            if scenario is None:
+                gr.Markdown("_No scenario selected._")
+                return
+            registry = default_registry()
+            shown = 0
+            for agent_name in scenario.cast:
+                manifest = registry.agents.get(agent_name)
+                if manifest is None or manifest.role == "judge":
+                    continue  # the Judge is configured under §04
+                shown += 1
+                with gr.Row():
+                    gr.Markdown(
+                        f"**{manifest.name}**<br/>"
+                        f"<span style='opacity:.7'>{manifest.archetype or f'the {manifest.role}'}</span>"
+                    )
+                    picker = gr.Dropdown(
+                        choices=_choices,
+                        value=_default_model_key(manifest),
+                        label="model · Modal",
+                        interactive=bool(_choices),
+                        scale=2,
+                    )
+
+                # Capture the agent name per row; the dropdown writes its key into the
+                # shared cast_models dict the Summon handler reads.
+                def _set_model(key, state, _name=manifest.name):
+                    return {**(state or {}), _name: key}
+
+                picker.change(_set_model, inputs=[picker, cast_models], outputs=[cast_models])
+            if not shown:
+                gr.Markdown("_This scenario has no selectable players._")
+            elif not _choices:
+                gr.Markdown("_No Modal models in the catalogue — the cast runs the deterministic stub._")
+
+    # Switching scenarios re-seeds the model picks to the new cast's defaults so a stale
+    # override from the previous world never leaks into the run.
+    def _reset_cast_models(scenario_value):
+        scn = _scenario_by_title(scenario_value) or default_registry().scenarios.get(scenario_value)
+        return _cast_defaults(scn) if scn else {}
+
+    handles["scenario"].change(_reset_cast_models, inputs=[handles["scenario"]], outputs=[cast_models])
+
     # 04 — The Judge + 05 — Tools (side by side)
     with gr.Row():
         with gr.Group():
@@ -189,9 +262,10 @@ def build_lab() -> dict[str, gr.components.Component]:
                 label="Policy preset",
             )
             handles["judge_model"] = gr.Dropdown(
-                choices=MODEL_PROFILES,
-                value="strong",
-                label="Bound model profile",
+                choices=catalogue,
+                value=_default_model_key(_judge_manifest(first)) if _judge_manifest(first) else None,
+                label="Judge model · Modal",
+                interactive=bool(catalogue),
             )
             handles["judge_strictness"] = gr.Slider(
                 minimum=0,
@@ -244,7 +318,7 @@ def collect_world_config(
     scenario: str,
     premise: str,
     seed: str,
-    cast_rows: list,
+    cast_models: dict[str, str] | None,
     judge_policy: str,
     judge_model: str,
     judge_strictness: float,
@@ -255,25 +329,29 @@ def collect_world_config(
     """Assemble + validate a per-run world from the Lab's form values.
 
     Returns the validated :class:`WorldConfig` (raising ``pydantic.ValidationError``
-    on an incoherent run).  This is the bridge Unit 9 uses to build a Conductor from a
-    composed run.
-
-    The base scenario (selected by its display *title*) supplies the cast roster and
-    the agent manifests; the edited ``cast_rows`` (``[name, archetype, model_profile,
-    temp]``) override each agent's ``model_profile`` and ``archetype`` non-destructively
-    via :meth:`pydantic.BaseModel.model_copy`.  The premise overrides the scenario goal,
-    ``seed`` becomes its ``default_seed``, and the budget knobs feed the governor.
-
-    The judge knobs (``judge_policy`` / ``judge_model`` / ``judge_strictness``) and the
-    ``tools`` grant are accepted and shape-checked, but the deeper synthesis (turning a
-    policy preset into a judge AgentManifest, wiring tool grants onto worker manifests) is
-    deferred to the engine and TODO'd below — every dict this builds is still passed
-    through ``validate_scenario`` / ``validate_world`` before return, so the contract
-    ("emit, validate, run") holds. See ADR-0011.
-
-    TODO(unit-9): map ``judge_policy`` / ``judge_model`` to a concrete judge AgentManifest
-    and wire the selected ``tools`` onto each worker's manifest ``tools`` grant once the
-    judge/tool contracts land in the live path.
+    on an incoherent run).  This is the bridge the app shell uses to build a Conductor
+    from a composed run via :meth:`Registry.from_world`.
+
+    The base scenario (selected by its display *title* or internal name) supplies the
+    cast roster and agent manifests.  Model selection binds each mind to a *specific*
+    Modal-hosted model: ``cast_models`` maps ``{agent_name: catalogue_endpoint_key}`` for
+    the players and ``judge_model`` is the Judge's endpoint key (§04).  Each becomes that
+    agent's ``model_endpoint`` (ADR-0022) — non-destructively via ``model_copy``, so the
+    shared registry is untouched.  Only keys that exist in ``modal_catalogue`` are honoured
+    (the picker offers nothing else; we re-check so a stale key can't reach the run); an
+    agent with no/blank/unknown selection keeps its manifest tier.  The premise overrides
+    the scenario goal, ``seed`` becomes its ``default_seed``, and the budget knobs feed the
+    governor.
+
+    The judge knobs (``judge_policy`` / ``judge_strictness``) and the ``tools`` grant are
+    accepted and shape-checked, but the deeper synthesis (policy preset → judge behaviour,
+    tool grants onto worker manifests) is deferred and TODO'd below — every dict this builds
+    still passes through ``validate_scenario`` / ``validate_world`` before return, so the
+    contract ("emit, validate, run") holds.  See ADR-0011 / ADR-0022.
+
+    TODO: map ``judge_policy`` / ``judge_strictness`` to concrete judge behaviour and wire
+    the selected ``tools`` onto each worker's manifest ``tools`` grant once those contracts
+    land in the live path.
     """
     registry = default_registry()
     base = _scenario_by_title(scenario)
@@ -283,28 +361,27 @@ def collect_world_config(
     if base is None:
         raise ValueError(f"unknown scenario {scenario!r} (have: {sorted(registry.scenarios)})")
 
-    # Edits per cast row → manifest overrides, keyed by name.  Non-destructive: we
-    # model_copy each manifest rather than mutating the cached registry instance.
-    edits: dict[str, dict] = {}
-    for row in cast_rows or []:
-        if not row or row[0] in (None, ""):
-            continue
-        name = str(row[0]).strip()
-        patch: dict = {}
-        if len(row) > 1 and row[1] not in (None, ""):
-            patch["archetype"] = str(row[1])
-        if len(row) > 2 and str(row[2]).strip() in MODEL_PROFILES:
-            patch["model_profile"] = str(row[2]).strip()
-        edits[name] = patch
+    # Only catalogue-hosted models may be cast: the picker offers nothing else, and we
+    # re-check here so an out-of-band or stale key can never reach the run.
+    valid_keys = {e["key"] for e in modal_catalogue.entries()}
+    selections = dict(cast_models or {})
+    judge_key = (judge_model or "").strip()
 
-    # Build the per-run cast: every manifest the scenario references, with overrides.
+    # Build the per-run cast: every manifest the scenario references, with its chosen
+    # Modal model pinned via model_endpoint.  Non-destructive: model_copy, never mutate
+    # the cached registry instance.
     agents = []
     cast_names: list[str] = []
     for agent_name in base.cast:
         manifest = registry.agents.get(agent_name)
         if manifest is None:
             raise ValueError(f"scenario {base.name!r} references undefined agent {agent_name!r}")
-        manifest = manifest.model_copy(update=edits.get(agent_name, {}))
+        # The Judge's model comes from §04; every other mind from the cast picker.
+        chosen = judge_key if manifest.role == "judge" else selections.get(agent_name)
+        patch: dict = {}
+        if chosen and chosen in valid_keys:
+            patch["model_endpoint"] = chosen
+        manifest = manifest.model_copy(update=patch)
         agents.append(manifest.model_dump(mode="python"))
         cast_names.append(manifest.name)
 

tests/test_fishbowl_lab.py

@@ -3,7 +3,8 @@
 Cover both surfaces: ``build_lab`` returns the expected handles inside a Blocks, and
 ``collect_world_config`` assembles a real scenario's data into a validated WorldConfig
 (round-tripping through ``validate_world`` / ``validate_scenario``) without mutating the
-shared registry.
+shared registry.  Model selection is constrained to the Modal catalogue and pins each
+agent's ``model_endpoint`` (ADR-0022).
 """
 
 from __future__ import annotations
@@ -13,6 +14,7 @@ import pytest
 
 from src.core.config import WorldConfig
 from src.core.registry import default_registry
+from src.models import modal_catalogue
 from src.ui.fishbowl import lab
 
 EXPECTED_HANDLE_KEYS = {
@@ -21,7 +23,7 @@ EXPECTED_HANDLE_KEYS = {
     "seed",
     "world",
     "narrator",
-    "cast",
+    "cast_models",
     "judge_policy",
     "judge_model",
     "judge_strictness",
@@ -34,6 +36,9 @@ EXPECTED_HANDLE_KEYS = {
     "surprise_btn",
 }
 
+# A couple of real catalogue keys to cast (the catalogue loads offline — a plain file).
+_CATALOGUE_KEYS = [e["key"] for e in modal_catalogue.entries()]
+
 
 def test_build_lab_returns_expected_handles():
     with gr.Blocks():
@@ -45,44 +50,55 @@ def test_build_lab_returns_expected_handles():
     assert isinstance(handles["seed"], gr.Dropdown)
     assert handles["seed"].allow_custom_value is True
     assert isinstance(handles["narrator"], gr.Dropdown)
-    assert isinstance(handles["cast"], gr.Dataframe)
-    assert handles["cast"].interactive is True
+    # The cast picker is a gr.render writing into this state (one dropdown per player).
+    assert isinstance(handles["cast_models"], gr.State)
     assert isinstance(handles["tools"], gr.CheckboxGroup)
     assert isinstance(handles["judge_strictness"], gr.Slider)
     assert isinstance(handles["summon_btn"], gr.Button)
     assert isinstance(handles["surprise_btn"], gr.Button)
 
 
-def test_build_lab_radio_lists_real_scenarios():
-    registry = default_registry()
-    real_titles = {s.title or s.name for s in registry.scenarios.values()}
+def test_judge_model_dropdown_offers_only_catalogue_models():
     with gr.Blocks():
         handles = lab.build_lab()
-    radio_choices = {c[0] for c in handles["scenario"].choices}
-    assert radio_choices == real_titles
+    assert isinstance(handles["judge_model"], gr.Dropdown)
+    values = {c[1] for c in handles["judge_model"].choices}
+    assert values <= set(_CATALOGUE_KEYS)
+    assert values, "judge model dropdown should list the catalogue"
 
 
-def test_build_lab_cast_seeded_from_scenario():
-    with gr.Blocks():
-        handles = lab.build_lab()
-    rows = handles["cast"].value["data"]
-    assert rows, "cast should be seeded with at least one row"
-    profiles = {row[2] for row in rows}
-    assert profiles <= set(lab.MODEL_PROFILES)
+def test_model_choices_are_all_catalogue_keys():
+    choices = lab.model_choices()
+    # Every selectable value is a real catalogue endpoint key — nothing else is offerable.
+    assert {key for _label, key in choices} == set(_CATALOGUE_KEYS)
+    # Labels are human-readable and name the served model.
+    assert all(" · " in label for label, _ in choices)
+
+
+def test_cast_defaults_cover_non_judge_cast_with_catalogue_keys():
+    registry = default_registry()
+    scenario = registry.scenarios["thousand-token-wood"]
+    defaults = lab._cast_defaults(scenario)
+    judge_names = {n for n in scenario.cast if (registry.agents.get(n) and registry.agents[n].role == "judge")}
+    non_judge = [n for n in scenario.cast if n not in judge_names]
+    assert set(defaults) == set(non_judge)  # judge excluded (set under §04)
+    assert all(v in _CATALOGUE_KEYS for v in defaults.values())
 
 
-def test_collect_world_config_validates_real_scenario():
+def test_collect_world_config_pins_selected_models_as_endpoints():
     registry = default_registry()
     scenario = registry.scenarios["thousand-token-wood"]
-    cast_rows = lab._cast_rows_for(scenario)
+    worker = next(n for n in scenario.cast if registry.agents[n].role != "judge")
+    judge = next(n for n in scenario.cast if registry.agents[n].role == "judge")
+    worker_key, judge_key = _CATALOGUE_KEYS[0], _CATALOGUE_KEYS[-1]
 
     world = lab.collect_world_config(
         scenario=scenario.title,
         premise="A new whimsical premise for the wood.",
         seed=scenario.default_seed,
-        cast_rows=cast_rows,
+        cast_models={worker: worker_key},
         judge_policy="Majority Vote",
-        judge_model="strong",
+        judge_model=judge_key,
         judge_strictness=60,
         tools=["dice.roll", "vote.tally"],
         tokens=120_000,
@@ -90,46 +106,42 @@ def test_collect_world_config_validates_real_scenario():
     )
 
     assert isinstance(world, WorldConfig)
-    assert len(world.scenarios) == 1
+    by_name = {a.name: a for a in world.agents}
+    assert by_name[worker].model_endpoint == worker_key
+    assert by_name[judge].model_endpoint == judge_key  # §04 binds the judge
+    # registry untouched (non-destructive model_copy)
+    assert registry.agents[worker].model_endpoint is None
+    assert registry.agents[judge].model_endpoint is None
+
     out = world.scenarios[0]
     assert out.name == scenario.name
     assert out.goal == "A new whimsical premise for the wood."
     assert out.cast == list(scenario.cast)
-    # cross-reference check: every cast name resolves to a defined agent
-    assert {a.name for a in world.agents} >= set(out.cast)
     assert out.governor is not None
     assert out.governor.max_turns == 25
     assert out.governor.max_total_tokens == 120_000
 
 
-def test_collect_world_config_applies_cast_edits_nondestructively():
+def test_collect_world_config_ignores_unknown_or_blank_model_keys():
     registry = default_registry()
     scenario = registry.scenarios["thousand-token-wood"]
-    first_agent = scenario.cast[0]
-    original_profile = registry.agents[first_agent].model_profile
-
-    rows = lab._cast_rows_for(scenario)
-    # flip the first agent's profile in the edited rows
-    new_profile = "strong" if original_profile != "strong" else "tiny"
-    rows[0][2] = new_profile
+    worker = next(n for n in scenario.cast if registry.agents[n].role != "judge")
 
     world = lab.collect_world_config(
         scenario=scenario.name,  # also accept name, not just title
         premise="",
         seed="",
-        cast_rows=rows,
+        cast_models={worker: "not-a-real-endpoint"},  # bogus key → ignored
         judge_policy="Judge's Whim",
-        judge_model="balanced",
+        judge_model="",  # blank → judge keeps its tier
         judge_strictness=10,
         tools=[],
         tokens=None,
         max_rounds=None,
     )
 
-    edited = next(a for a in world.agents if a.name == first_agent)
-    assert edited.model_profile == new_profile
-    # registry untouched
-    assert registry.agents[first_agent].model_profile == original_profile
+    by_name = {a.name: a for a in world.agents}
+    assert by_name[worker].model_endpoint is None  # stale/unknown key dropped
     # blank premise/seed fall back to the scenario's own
     assert world.scenarios[0].goal == scenario.goal
     assert world.scenarios[0].default_seed == scenario.default_seed
@@ -141,9 +153,9 @@ def test_collect_world_config_unknown_scenario_raises():
             scenario="not-a-real-world",
             premise="",
             seed="",
-            cast_rows=[],
+            cast_models={},
             judge_policy="Majority Vote",
-            judge_model="fast",
+            judge_model="",
             judge_strictness=50,
             tools=[],
             tokens=None,

tests/test_manifest_agent.py

@@ -71,6 +71,25 @@ class TestManifestAgentEmits:
         agent.act("r", 1, StageProjection(), ())
         assert router.for_profile("tiny").variant == "stub:tiny"
 
+    def test_model_endpoint_overrides_profile(self):
+        # An explicit catalogue endpoint pins a specific model: _route_key prefers it
+        # over the tier, and the agent routes there (ADR-0022).
+        class _Pinned(ManifestAgent):
+            manifest = AgentManifest(
+                name="scene-whisperer",
+                role="worker",
+                persona="You speak on a specific model.",
+                may_emit=["world.observed"],
+                model_profile="tiny",
+                model_endpoint="minicpm-4-1-8b",
+            )
+
+        agent = _Pinned(router := _router())
+        assert agent._route_key == "minicpm-4-1-8b"
+        agent.act("r", 1, StageProjection(), ())
+        # the routed (cached) provider is the endpoint's stub, not the tiny tier's
+        assert router.for_profile("minicpm-4-1-8b").variant == "stub:minicpm-4-1-8b"
+
 
 class TestManifestAgentSalience:
     def test_salience_path_runs(self):

tests/test_registry.py

@@ -56,6 +56,43 @@ class TestDefaultRegistry:
             reg.build_scenario("no-such-scenario")
 
 
+class TestFromWorld:
+    """A composed WorldConfig (e.g. from the Lab) builds a registry on the same path."""
+
+    def _world(self):
+        from src.core.config import validate_world
+
+        reg = default_registry()
+        base = reg.scenarios["thousand-token-wood"]
+        # Pin one agent to a specific catalogue model, the rest by tier.
+        agents = []
+        for name in base.cast:
+            m = reg.agents[name]
+            if name == "pocket-actor":
+                m = m.model_copy(update={"model_endpoint": "minicpm-4-1-8b"})
+            agents.append(m.model_dump(mode="python"))
+        return validate_world(
+            {
+                "agents": agents,
+                "scenarios": [base.model_dump(mode="python")],
+            }
+        )
+
+    def test_builds_scenario_and_router_from_world(self):
+        reg = Registry.from_world(self._world())
+        assert set(reg.agents) >= {"scene-whisperer", "pocket-actor", "echo"}
+        sc = reg.build_scenario("thousand-token-wood")
+        assert len(sc.agents) == 4
+        pocket = next(a for a in sc.agents if a.name == "pocket-actor")
+        assert pocket.manifest.model_endpoint == "minicpm-4-1-8b"
+        assert pocket._route_key == "minicpm-4-1-8b"
+
+    def test_governor_threaded_from_world(self):
+        reg = Registry.from_world(self._world())
+        gov = reg.governor_for("thousand-token-wood")
+        assert gov.max_turns == 60  # carried from the scenario's governor
+
+
 class TestHandlerBinding:
     def test_handler_class_used_when_named(self):
         @register_handler("test-handler")

tests/test_router.py

@@ -71,6 +71,45 @@ class TestModelRouterOnline:
         assert provider.max_tokens == 320  # _PROFILE_DECODING["balanced"]
 
 
+class TestModelRouterCatalogueEndpoint:
+    """A non-tier router key names a specific catalogue model (manifest.model_endpoint)."""
+
+    def test_offline_endpoint_key_serves_distinct_stub(self):
+        # A concrete catalogue key routes like any profile offline: the deterministic
+        # stub, with the key folded into its variant so the choice still varies output.
+        router = ModelRouter(offline=True)
+        provider = router.for_profile("minicpm-4-1-8b")
+        assert isinstance(provider, DeterministicTinyModel)
+        assert "minicpm-4-1-8b" in provider.variant
+        assert provider.variant != router.for_profile("gemma-4-12b").variant
+
+    def test_online_endpoint_key_resolves_to_catalogue_binding(self, monkeypatch):
+        monkeypatch.setenv("MODAL_WORKSPACE", "demo-ws")
+        monkeypatch.setenv("MODAL_LLM_KEY", "EMPTY")
+        monkeypatch.delenv("MODEL_BALANCED", raising=False)
+        router = ModelRouter(offline=False)
+        provider = router.for_profile("gemma-4-12b")
+        assert isinstance(provider, LiteLLMProvider)
+        assert provider.model == "openai/google/gemma-4-12B"
+        assert "gemma-4-12b" in provider.api_base
+        assert provider.max_tokens == 320  # balanced tier decoding
+
+    def test_unbound_specialist_uses_balanced_decoding(self, monkeypatch):
+        # nemotron-cascade-14b-thinking has profile=None → balanced decoding defaults.
+        monkeypatch.setenv("MODAL_WORKSPACE", "demo-ws")
+        router = ModelRouter(offline=False)
+        provider = router.for_profile("nemotron-cascade-14b-thinking")
+        assert isinstance(provider, LiteLLMProvider)
+        assert provider.max_tokens == 320
+
+    def test_unknown_key_degrades_to_fast_tier(self, monkeypatch):
+        monkeypatch.setenv("MODEL_FAST", "fallback-model")
+        router = ModelRouter(offline=False)
+        provider = router.for_profile("not-a-real-endpoint")
+        assert provider.model == "fallback-model"
+        assert provider.max_tokens == 220  # fast tier decoding
+
+
 class TestFromEnv:
     def test_offline_without_binding(self, monkeypatch):
         # No Modal binding (and no stray cloud key) → deterministic offline stub.