code-coordinator 0.5.586__tar.gz → 0.5.587__tar.gz

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.586
+Version: 0.5.587
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.586
+Version: 0.5.587
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/code_coordinator.egg-info/SOURCES.txt

@@ -735,6 +735,7 @@ tests/test_mock_author.py
 tests/test_model_tiering.py
 tests/test_models.py
 tests/test_models_config_labels.py
+tests/test_models_pinned_1650.py
 tests/test_needs_attention.py
 tests/test_network.py
 tests/test_new_issue_chat.py

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/code_coordinator.egg-info/scm_file_list.json

@@ -762,6 +762,7 @@
     "tests/test_model_tiering.py",
     "tests/test_models.py",
     "tests/test_models_config_labels.py",
+    "tests/test_models_pinned_1650.py",
     "tests/test_needs_attention.py",
     "tests/test_network.py",
     "tests/test_new_issue_chat.py",

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.586",
+  "tag": "0.5.587",
   "distance": 0,
-  "node": "g0116991dbca373e8070feb4ac61ffb9d26cfe533",
+  "node": "g81a6f30503a2fdb64cbd57beb67d5d4bc78612ee",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-03"

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/coord/commands/dispatch.py

@@ -654,8 +654,13 @@ def approve(
             label_model=label_model,
             config=cfg,
             effective_provider_name=effective_provider_name,
+            assignment_type=p.type,
         )
         if p.model:
+            # #1650: a pinned type's route is the SAME one just resolved
+            # above (no `explicit_model` reaches this call site) — naming
+            # it here is a reporting concern, not a second routing decision.
+            _pinned_type = p.type if cfg.models.model_for_type(p.type) else None
             click.echo(
                 "     model: "
                 + describe_model_choice(
@@ -663,6 +668,7 @@ def approve(
                     explicit_reason="resolved at plan time" if used_plan_time_snapshot else None,
                     matched_label=matched_label,
                     shadowed_labels=shadowed_labels,
+                    pinned_type=_pinned_type,
                 )
             )
         else:

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/coord/commands/dispatch_workers.py

@@ -4753,11 +4753,17 @@ def _dispatch_headless(
         if not effective_plan_only
         else (None, None, [])
     )
+    # #1650: computed once — both the actual routing decision
+    # (`resolve_dispatch_model_alias` below) and the `Proposal.type` it's
+    # keyed against must agree, or the echoed "pinned for type=X" reason
+    # could name a type that isn't the one actually dispatched.
+    effective_assignment_type = "plan" if effective_plan_only else (dispatch_type or "work")
     resolved_model = resolve_dispatch_model_alias(
         explicit_model=model,
         label_model=label_model,
         config=cfg,
         effective_provider_name=effective_provider_name,
+        assignment_type=effective_assignment_type,
     )
 
     proposal = Proposal(
@@ -4769,7 +4775,7 @@ def _dispatch_headless(
         rationale="manual assignment via coord assign",
         briefing=briefing,
         model=resolved_model,
-        type="plan" if effective_plan_only else (dispatch_type or "work"),
+        type=effective_assignment_type,
         required_gates=resolved_gates,
         issue_labels=issue_labels,
         driven_by=driven_by,
@@ -4795,6 +4801,15 @@ def _dispatch_headless(
         # from an intentional default in this same line of output.
         from coord.config import describe_model_choice  # noqa: PLC0415
 
+        # #1650: only report the pin when it's actually what won — an
+        # explicit --model still overrides it (see
+        # `resolve_dispatch_model_alias`'s precedence), so don't claim
+        # "pinned" for a human's own override.
+        _pinned_type = (
+            effective_assignment_type
+            if not model and cfg.models.model_for_type(effective_assignment_type)
+            else None
+        )
         click.echo(
             "  model: "
             + describe_model_choice(
@@ -4802,6 +4817,7 @@ def _dispatch_headless(
                 explicit_reason="explicit --model" if model else None,
                 matched_label=matched_label,
                 shadowed_labels=shadowed_labels,
+                pinned_type=_pinned_type,
             )
         )
     else:

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/coord/config.py

@@ -755,6 +755,31 @@ class ModelsConfig:
     ``claude -p --model`` on the worker.  Aliases not present in the map
     pass through unchanged, so ``claude -p`` falls back to its CLI default
     (which today is whatever the installed claude-cli treats as latest).
+
+    `pinned` (#1650) maps an assignment ``type`` (``"review"``, ``"merge"``,
+    ...) to a model route that must never be silently degraded by the
+    escalation ladder, by ``labels``-derived routing, or by a usage-gate
+    reroute — the final review gates every merge and is never skippable,
+    so the model that performs it must never be the thing a cost-driven
+    ladder economises on. A pinned type's route wins outright: every
+    resolver in this module, and :func:`coord.dispatch.
+    resolve_dispatch_model_alias`, checks ``pinned`` FIRST and returns
+    immediately when it matches, so the ladder/labels/usage-gate are never
+    even consulted for that dispatch — see :meth:`model_for_type`.
+
+    A route is either a bare model alias (resolved against the implicit
+    ``claude`` provider's known aliases — ``default``/``escalation``/
+    ``labels.values()``/``versions`` keys, plus the baseline
+    ``haiku``/``sonnet``/``opus`` trio) or a ``provider/model`` pair (e.g.
+    ``claude/opus``) naming a provider registered in ``providers.
+    definitions``. Both forms are validated at config-parse time
+    (``_parse_models``) — an unknown provider or an unrecognised model
+    alias is a ``ConfigError`` at load, not a silent fall-through to the
+    ladder discovered at 2am.
+
+    Ships with a **default pin on `"review"`** (``opus``) rather than an
+    empty mapping — an operator who never reads #1650 still gets the safe
+    behaviour. An explicit ``pinned: {}`` in ``coordinator.yml`` opts out.
     """
 
     default: str = "sonnet"
@@ -763,6 +788,24 @@ class ModelsConfig:
     )
     labels: dict[str, str] = field(default_factory=dict)
     versions: dict[str, str] = field(default_factory=dict)
+    pinned: dict[str, str] = field(default_factory=lambda: {"review": "opus"})
+
+    def model_for_type(self, assignment_type: str | None) -> str | None:
+        """Return the pinned route for *assignment_type*, if configured.
+
+        #1650: this is the ONE question every resolver asks before
+        consulting the escalation ladder, ``labels``, or a usage-gate
+        reroute — callers short-circuit on a non-``None`` result and never
+        fall through to those mechanisms, so a pin can't be shadowed by
+        whatever any of them (including a not-yet-built usage-aware
+        reroute) would otherwise have computed. Returns ``None`` (never
+        ``default``) when *assignment_type* isn't pinned, or is ``None``
+        itself — mirroring the None-passthrough style of :meth:`resolve`/
+        :meth:`model_for_labels`.
+        """
+        if assignment_type is None:
+            return None
+        return self.pinned.get(assignment_type)
 
     def next_model(self, current: str) -> str:
         """Return the next model in the escalation ladder.
@@ -893,6 +936,7 @@ def describe_model_choice(
     explicit_reason: str | None = None,
     matched_label: str | None = None,
     shadowed_labels: list[str] | None = None,
+    pinned_type: str | None = None,
 ) -> str:
     """Format a one-line explanation of why *resolved_model* was chosen.
 
@@ -901,6 +945,13 @@ def describe_model_choice(
     picked up yet) read identically to an intentional default — the exact
     ambiguity that made the stale-label-cache bug expensive to notice.
 
+    *pinned_type*, when set (#1650), wins outright and reports
+    ``"(pinned for type=<pinned_type>)"`` — a :attr:`ModelsConfig.pinned`
+    match is a stronger, operator-declared signal than any label match or
+    explicit reason, so callers pass it only when
+    :meth:`ModelsConfig.model_for_type` actually matched for this
+    dispatch.
+
     *explicit_reason*, when set, wins outright (e.g. ``"explicit --model"``
     or ``"resolved at plan time"``) — the caller already knows the model
     didn't come from a fresh label match. Otherwise *matched_label* (from
@@ -913,6 +964,8 @@ def describe_model_choice(
     self-explaining at dispatch time instead of reading like the older,
     order-dependent bug.
     """
+    if pinned_type:
+        return f"{resolved_model} (pinned for type={pinned_type})"
     if explicit_reason:
         return f"{resolved_model} ({explicit_reason})"
     if matched_label:
@@ -2998,7 +3051,7 @@ def parse_mapping(raw: Any, *, path: Path | None = None) -> Config:
     concurrency = _parse_concurrency(raw.get("concurrency"))
     smoke_tests = _parse_smoke_tests(raw.get("smoke_tests"))
     acceptance = _parse_acceptance(raw.get("acceptance"))
-    models = _parse_models(raw.get("models"))
+    models = _parse_models(raw.get("models"), set(providers.definitions))
     pipeline = _parse_pipeline(raw.get("pipeline"))
     dispatch = _parse_dispatch(raw.get("dispatch"))
     usage_gate = _parse_usage_gate(raw.get("usage_gate"))
@@ -4114,7 +4167,7 @@ def _acceptance_entrypoint(entry: dict, label: str) -> str:
     return value
 
 
-def _parse_models(raw: Any) -> ModelsConfig:
+def _parse_models(raw: Any, known_providers: set[str] | None = None) -> ModelsConfig:
     if raw is None:
         return ModelsConfig()
     if not isinstance(raw, dict):
@@ -4154,9 +4207,92 @@ def _parse_models(raw: Any) -> ModelsConfig:
             )
         cfg.versions = dict(value)
 
+    # #1650: `pinned` is validated LAST — it references `cfg.default`/
+    # `cfg.escalation`/`cfg.labels`/`cfg.versions` (all parsed above) to
+    # build the known-alias vocabulary a bare (no-provider-prefix) route is
+    # checked against.
+    if "pinned" in raw:
+        value = raw["pinned"]
+        if not isinstance(value, dict) or not all(
+            isinstance(k, str) and k and isinstance(v, str) and v
+            for k, v in value.items()
+        ):
+            raise ConfigError(
+                "models.pinned must be a mapping of assignment type → model route"
+            )
+        cfg.pinned = dict(value)
+        for assignment_type, route in cfg.pinned.items():
+            _validate_pinned_route(
+                assignment_type, route, cfg, known_providers or {"claude"},
+            )
+    # Explicit `pinned: {}` is a deliberate opt-out — otherwise the dataclass
+    # default (`{"review": "opus"}`) already stands and needs no validation
+    # here (it's valid by construction: "opus" is in the baseline alias set
+    # checked below regardless of a custom `escalation`/`labels`/`versions`).
+
     return cfg
 
 
+#: #1650: the baseline Anthropic model aliases recognised regardless of what
+#: `models.escalation`/`models.labels`/`models.versions` a deployment
+#: configures — keeps the shipped default pin (`review: opus`) valid even
+#: for a coordinator.yml that never mentions "opus" anywhere else.
+_BASELINE_MODEL_ALIASES: frozenset[str] = frozenset({"haiku", "sonnet", "opus"})
+
+
+def _validate_pinned_route(
+    assignment_type: str, route: str, cfg: ModelsConfig, known_providers: set[str],
+) -> None:
+    """Validate one ``models.pinned[assignment_type]`` route at parse time.
+
+    #1650: a typo here must fail loudly at config load, not silently fall
+    through to the ladder/labels at dispatch time. A route is either a bare
+    model alias (checked against the known alias vocabulary for the
+    implicit ``claude`` provider — see :data:`_BASELINE_MODEL_ALIASES`) or a
+    ``provider/model`` pair, e.g. ``claude/opus`` — the provider half is
+    checked against *known_providers* (``providers.definitions``, which
+    always includes the implicit ``"claude"`` entry); the model half is only
+    checked when that provider is ``claude``/``claude-pty``-shaped (named
+    ``"claude"`` here, since ``_parse_providers`` hasn't run far enough by
+    this point to carry provider *types* — every registered claude-backed
+    provider is reachable by its own name, so this only validates the
+    common, un-aliased case). A non-claude provider's model half is a
+    backend-specific free string — not validated here, same as
+    ``ProviderDef.model`` isn't validated anywhere else in this module.
+    """
+    if "/" in route:
+        provider_name, _, model = route.partition("/")
+        if provider_name not in known_providers:
+            raise ConfigError(
+                f"models.pinned[{assignment_type!r}] references unknown "
+                f"provider {provider_name!r} (got route {route!r})"
+            )
+        if not model:
+            raise ConfigError(
+                f"models.pinned[{assignment_type!r}] is missing a model "
+                f"after the provider (got route {route!r})"
+            )
+        if provider_name != "claude":
+            return
+        model_alias = model
+    else:
+        model_alias = route
+
+    known_aliases = (
+        _BASELINE_MODEL_ALIASES
+        | {cfg.default}
+        | set(cfg.escalation)
+        | set(cfg.labels.values())
+        | set(cfg.versions.keys())
+    )
+    if model_alias not in known_aliases:
+        raise ConfigError(
+            f"models.pinned[{assignment_type!r}] references unknown model "
+            f"{model_alias!r} (got route {route!r}); known aliases: "
+            f"{sorted(known_aliases)!r}"
+        )
+
+
 def _parse_pipeline(raw: Any) -> PipelineConfig:
     if raw is None:
         return PipelineConfig()

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/coord/dispatch.py

@@ -442,19 +442,29 @@ def resolve_dispatch_model_alias(
     label_model: str | None,
     config: Config,
     effective_provider_name: str,
+    assignment_type: str | None = None,
 ) -> str | None:
     """Resolve the dispatch model *alias* (before ``models.resolve()``).
 
-    Precedence: *explicit_model* → the effective provider's own pinned
-    ``ProviderDef.model`` (for non-claude/claude-pty backends only) →
-    *label_model* → ``models.default``. The board/DB stores this alias for
-    legibility; the caller is responsible for the final
-    ``config.models.resolve()`` translation to an exact model id (typically
-    deferred to :func:`dispatch`/:func:`resolve_dispatch_model`, which run
-    at actual-wire-payload time — see the module docstring of each CLI
-    entry point that calls this function for why: re-resolving here would
-    bake an exact id into ``Proposal.model``/board bookkeeping instead of
-    the human-legible alias).
+    Precedence: *explicit_model* → ``models.pinned[assignment_type]``
+    (#1650) → the effective provider's own pinned ``ProviderDef.model``
+    (for non-claude/claude-pty backends only) → *label_model* →
+    ``models.default``. The board/DB stores this alias for legibility; the
+    caller is responsible for the final ``config.models.resolve()``
+    translation to an exact model id (typically deferred to
+    :func:`dispatch`/:func:`resolve_dispatch_model`, which run at
+    actual-wire-payload time — see the module docstring of each CLI entry
+    point that calls this function for why: re-resolving here would bake
+    an exact id into ``Proposal.model``/board bookkeeping instead of the
+    human-legible alias).
+
+    #1650: a type pinned via ``models.pinned`` wins over the provider pin
+    AND *label_model* — it ignores the escalation ladder, label-derived
+    routing, and a usage-gate reroute entirely, by never even reaching the
+    code that would compute those (see :meth:`coord.config.ModelsConfig.
+    model_for_type`). Only an *explicit_model* (a human being specific
+    right now, same precedent as the provider pin below) still overrides
+    it.
 
     #1798: *label_model* comes from ``models.labels``, which maps to
     Anthropic aliases (``tier:small -> haiku``) — a namespace that means
@@ -533,19 +543,26 @@ def resolve_dispatch_model_alias(
             name (spec > repo > ``providers.default``), as returned by
             :func:`coord.providers.resolve_provider_name` or
             :func:`coord.providers.guard_unattended_dispatch`.
+        assignment_type: The dispatch's assignment ``type`` (e.g.
+            ``"work"``, ``"review"``), consulted against ``models.pinned``
+            (#1650). ``None`` when the caller has no type to offer —
+            behaves exactly like an unpinned type.
 
     Returns:
         The model alias (NOT yet passed through ``config.models.resolve()``),
         or ``None`` to omit ``--model``.
     """
+    if explicit_model:
+        return explicit_model
+    pinned_model = config.models.model_for_type(assignment_type)
+    if pinned_model:
+        return pinned_model
     provider_def = config.providers.definitions.get(effective_provider_name)
     provider_pins_model = (
         provider_def is not None
         and provider_def.type not in ("claude", "claude-pty")
         and provider_def.model is not None
     )
-    if explicit_model:
-        return explicit_model
     if provider_pins_model:
         return None
     if label_model:
@@ -596,6 +613,7 @@ def resolve_dispatch_model(
         label_model=label_model,
         config=config,
         effective_provider_name=effective_provider_name,
+        assignment_type=proposal.type,
     )
     return config.models.resolve(alias)
 

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/coord/milestone_dispatch.py

@@ -1448,6 +1448,7 @@ def dispatch_entry(
         label_model=label_model,
         config=config,
         effective_provider_name=effective_provider_name,
+        assignment_type=proposal_type,
     )
     # #1454: surfaced on the outcome so `coord milestone dispatch`'s CLI
     # output states *why* this model was picked, same as `coord assign` /
@@ -1457,11 +1458,19 @@ def dispatch_entry(
     # earlier `coord plan`/`coord milestone plan` run.
     from coord.config import describe_model_choice  # noqa: PLC0415
 
+    # #1650: a pinned type's route is the SAME one `resolve_dispatch_model_
+    # alias` above just returned (no `explicit_model` reaches this call
+    # site) — naming it here is purely a reporting concern, not a second
+    # routing decision.
+    pinned_type = (
+        proposal_type if config.models.model_for_type(proposal_type) else None
+    )
     if resolved_model:
         model_reason = describe_model_choice(
             resolved_model=resolved_model,
             matched_label=matched_label,
             shadowed_labels=shadowed_labels,
+            pinned_type=pinned_type,
         )
     else:
         # #1706/#1798: resolved_model is None when the effective provider's

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/coord/review.py

@@ -3886,7 +3886,12 @@ def dispatch_review(
         # #1430: deliberately not consulting models.labels — the reviewer's
         # effort scales with diff size, not the original work issue's tier
         # label, and #911 already pins this deliberately.
-        review_model_alias = config.models.default
+        # #1650: `models.pinned["review"]` (default: "opus") wins over
+        # `models.default` outright — the final review gates every merge
+        # and must never be silently degraded by a cost-driven ladder or a
+        # usage-gate reroute, so this is checked ahead of (and instead of)
+        # `models.default`, never folded into it.
+        review_model_alias = config.models.model_for_type("review") or config.models.default
         review_model_wire = config.models.resolve(review_model_alias)
 
         # #821: capture branch HEAD SHA once; staleness detected post-review.
@@ -5003,7 +5008,10 @@ def dispatch_scoped_review(
     if not candidates:
         return None
 
-    review_model_alias = config.models.default
+    # #1650: see the #911/#1650 comment at the other `review_model_alias`
+    # assignment site (`dispatch_review` above) — `models.pinned["review"]`
+    # wins outright over `models.default` here too.
+    review_model_alias = config.models.model_for_type("review") or config.models.default
     review_model_wire = config.models.resolve(review_model_alias)
 
     _get_sha = branch_sha_fetcher or github_ops.get_branch_sha

{code_coordinator-0.5.586 → code_coordinator-0.5.587}/coordinator.example.yml

@@ -458,6 +458,21 @@ models:
   #   haiku:  claude-haiku-4-5
   #   sonnet: claude-sonnet-5
   #   opus:   claude-opus-4-8
+  #
+  # pinned (#1650): assignment type -> model route that must never be
+  # silently degraded by the escalation ladder, by `labels` above, or by a
+  # usage-gate reroute. A pinned type's route wins outright over all three
+  # — the final review gates every merge and must never be the thing a
+  # cost-driven ladder economises on. Defaults to `{review: opus}` when
+  # this key is absent entirely; an explicit `pinned: {}` opts out. A
+  # route is either a bare alias (checked against this block's own
+  # default/escalation/labels/versions, plus the haiku/sonnet/opus
+  # baseline) or a `provider/model` pair naming a `providers.definitions`
+  # entry — both are validated at config-load time, so a typo is a
+  # ConfigError at load, not a silent fall-through discovered at 2am.
+  # pinned:
+  #   review: opus
+  #   merge: claude/sonnet
 
 # providers: worker-command backend registry (#322 / #323).
 #