feat: per-tier routing activation (v0c)

RoutingPolicy gains tier_modes: a tier entry may be a string
(model, mode inherits global) or {model, mode}. The explicit
tier mode overrides the global mode in both directions, so plan
can be active while goal/default stay shadow, and one tier can
be rolled back to off without touching the others. An invalid
tier mode drops that tier entirely (fail-closed: a typo must
never accidentally activate a tier, and never kills other
tiers). Tier-off tasks return worker_default and are not
audited as policy/shadow, so they never inflate shadow sample
counts. Explicit task and worker-CLI models still win over any
tier mode.

Tests: test_routing_tier.py (5 tests).

cloud/models.py

@@ -178,21 +178,38 @@ def _clean_tiers(raw):
 class RoutingPolicy:
     """A parsed, versioned routing policy (or an empty one).
 
-    ``mode`` is one of ``off`` / ``shadow`` / ``active``. ``tiers`` maps
-    a tier name to a model name; a tier absent from the map falls back
-    to the worker default. ``fallback_models`` is parsed and validated
-    but deliberately NOT applied by v0: the worker's explicit
-    ``--fallback-models`` remains the only source that can enable a real
-    fallback retry, so a policy file alone can never start burning a
-    second attempt's quota.
+    ``mode`` is one of ``off`` / ``shadow`` / ``active`` and is the
+    default for every tier. ``tiers`` maps a tier name to a model
+    name; a tier absent from the map falls back to the worker
+    default. ``tier_modes`` (v0c, per-tier activation) maps a tier
+    name to an explicit mode that overrides the global ``mode`` in
+    both directions: a tier can be ``active`` while the global mode
+    is ``shadow``/``off`` (activate plan first), and a tier can be
+    ``off`` while the global mode is ``active`` (roll back one tier
+    without touching the others). A tier entry whose mode is not a
+    valid mode is dropped entirely by the parser (fail-closed: a
+    typo must never accidentally activate a tier).
+    ``fallback_models`` is parsed and validated but deliberately
+    NOT applied by v0: the worker's explicit ``--fallback-models``
+    remains the only source that can enable a real fallback retry,
+    so a policy file alone can never start burning a second
+    attempt's quota.
     """
 
     def __init__(self, version=None, mode="shadow", tiers=None,
-                 fallback_models=None):
+                 fallback_models=None, tier_modes=None):
         self.version = version if isinstance(version, str) \
             and version.strip() else None
         self.mode = mode if mode in ROUTING_MODES else "off"
         self.tiers = dict(tiers or {})
+        self.tier_modes = {}
+        for tier, tier_mode in (tier_modes or {}).items():
+            if tier in self.tiers and tier_mode in ROUTING_MODES:
+                self.tier_modes[tier] = tier_mode
+
+    def tier_mode(self, tier):
+        """Effective mode for one tier: explicit tier mode, else global."""
+        return self.tier_modes.get(tier, self.mode)
         self.fallback_models = []
         for item in fallback_models or []:
             model = _clean_model_name(item)
@@ -215,6 +232,24 @@ def parse_routing_policy(data):
     if mode not in ROUTING_MODES:
         return None
     tiers = _clean_tiers(data.get("tiers"))
+    if not tiers:
+        return None
+    # Per-tier modes (v0c): a tier entry may be a string (model,
+    # mode inherits global) or a dict {"model": ..., "mode": ...}.
+    # An invalid tier mode drops the whole tier entry (fail-closed),
+    # it never falls back to the global mode where a typo could
+    # accidentally activate, and never kills the other tiers.
+    raw_tiers = data.get("tiers") if isinstance(data.get("tiers"),
+                                                dict) else {}
+    tier_modes = {}
+    for tier, entry in raw_tiers.items():
+        if not isinstance(entry, dict) or "mode" not in entry:
+            continue
+        tier_mode = entry.get("mode")
+        if tier_mode in ROUTING_MODES:
+            tier_modes[tier] = tier_mode
+        else:
+            tiers.pop(tier, None)
     if not tiers:
         return None
     fallback_models = data.get("fallback_models")
@@ -222,7 +257,8 @@ def parse_routing_policy(data):
                                                      list):
         return None
     return RoutingPolicy(version=data.get("version"), mode=mode,
-                         tiers=tiers, fallback_models=fallback_models)
+                         tiers=tiers, fallback_models=fallback_models,
+                         tier_modes=tier_modes)
 
 
 def load_routing_policy(env=None):
@@ -305,7 +341,10 @@ def decide_routing(task, worker_model, policy=None,
     1. task-level ``model`` (explicit) -- never overridden;
     2. worker CLI ``--model`` (explicit) -- a pinned deployment is never
        silently changed by a policy file;
-    3. active policy tier model -- only when the task named no model;
+    3. policy tier model in the tier's effective mode (v0c: explicit
+       tier mode, else the global mode) -- only when the task named
+       no model; ``active`` applies the tier model, ``shadow``
+       suggests it, ``off`` falls back to the worker default;
     4. worker default chain (config file / ``DEFAULT_MODEL``).
 
     Shadow mode returns the worker default as ``chosen_model`` and the
@@ -335,11 +374,11 @@ def decide_routing(task, worker_model, policy=None,
             suggested_model=None, source="worker_explicit",
             policy_version=None, applied=True,
             reason="worker CLI model explicit", signals=signals)
-    if policy is None or policy.mode == "off":
+    if policy is None:
         return RoutingDecision(
             task_id=task.get("id"), tier=tier, chosen_model=worker_model,
             suggested_model=None, source="worker_default",
-            policy_version=getattr(policy, "version", None),
+            policy_version=None,
             applied=True, reason="routing off or no policy",
             signals=signals)
     tier_model = policy.tiers.get(tier)
@@ -349,14 +388,25 @@ def decide_routing(task, worker_model, policy=None,
             suggested_model=None, source="worker_default",
             policy_version=policy.version, applied=True,
             reason="%s tier has no policy model" % tier, signals=signals)
-    if policy.mode == "shadow":
+    # Per-tier effective mode (v0c): explicit tier mode overrides
+    # the global mode in both directions. A tier in "off" is not
+    # routed at all (no policy/shadow audit downstream, so it never
+    # inflates a shadow sample count).
+    effective_mode = policy.tier_mode(tier)
+    if effective_mode == "off":
+        return RoutingDecision(
+            task_id=task.get("id"), tier=tier, chosen_model=worker_model,
+            suggested_model=None, source="worker_default",
+            policy_version=policy.version, applied=True,
+            reason="%s tier mode is off" % tier, signals=signals)
+    if effective_mode == "shadow":
         return RoutingDecision(
             task_id=task.get("id"), tier=tier, chosen_model=worker_model,
             suggested_model=tier_model, source="shadow",
             policy_version=policy.version, applied=False,
             reason="%s tier suggests %s (shadow, not applied)"
             % (tier, tier_model), signals=signals)
-    # mode == "active"
+    # effective_mode == "active"
     return RoutingDecision(
         task_id=task.get("id"), tier=tier, chosen_model=tier_model,
         suggested_model=None, source="policy",