code-coordinator 0.5.92__tar.gz → 0.5.94__tar.gz

{code_coordinator-0.5.92 → code_coordinator-0.5.94}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.92
+Version: 0.5.94
 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.92 → code_coordinator-0.5.94}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.92
+Version: 0.5.94
 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.92 → code_coordinator-0.5.94}/code_coordinator.egg-info/SOURCES.txt

@@ -529,6 +529,7 @@ tests/test_config.py
 tests/test_config_acceptance.py
 tests/test_config_audit.py
 tests/test_config_pricing.py
+tests/test_config_snapshot_noncanonical_2208.py
 tests/test_config_usage_gate.py
 tests/test_conflict_fix.py
 tests/test_conflict_fix_semantic.py
@@ -676,6 +677,7 @@ tests/test_reconcile_merges.py
 tests/test_reconcile_usage_limit_done.py
 tests/test_refine_chat.py
 tests/test_release_cordon_2101.py
+tests/test_release_cordon_daemon_leads_2176.py
 tests/test_release_cordon_deadlock_2240.py
 tests/test_release_propagate.py
 tests/test_release_unified_1242.py

{code_coordinator-0.5.92 → code_coordinator-0.5.94}/code_coordinator.egg-info/scm_file_list.json

@@ -559,6 +559,7 @@
     "tests/test_config_acceptance.py",
     "tests/test_config_audit.py",
     "tests/test_config_pricing.py",
+    "tests/test_config_snapshot_noncanonical_2208.py",
     "tests/test_config_usage_gate.py",
     "tests/test_conflict_fix.py",
     "tests/test_conflict_fix_semantic.py",
@@ -706,6 +707,7 @@
     "tests/test_reconcile_usage_limit_done.py",
     "tests/test_refine_chat.py",
     "tests/test_release_cordon_2101.py",
+    "tests/test_release_cordon_daemon_leads_2176.py",
     "tests/test_release_cordon_deadlock_2240.py",
     "tests/test_release_propagate.py",
     "tests/test_release_unified_1242.py",

{code_coordinator-0.5.92 → code_coordinator-0.5.94}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.92",
+  "tag": "0.5.94",
   "distance": 0,
-  "node": "g7d880a1fd7fca3a73143f80edb90e5e9ebffef63",
+  "node": "gc872293016c9a4132c83fff7881956b707aacbf7",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-15"

{code_coordinator-0.5.92 → code_coordinator-0.5.94}/coord/commands/_common.py

@@ -27,7 +27,13 @@ from typing import TYPE_CHECKING
 
 import click
 
-from coord.config import Config, ConfigError, load, resolve_config_path
+from coord.config import (
+    Config,
+    ConfigError,
+    is_canonical_config_path,
+    load,
+    resolve_config_path,
+)
 
 if TYPE_CHECKING:  # pragma: no cover — typing only
     from collections.abc import Iterator
@@ -100,7 +106,55 @@ _CONFIG_OPTION = click.option(
 )
 
 
-def _save_config_snapshot(config: Config) -> None:
+def _note_withheld_snapshot(config: Config, config_path: Path) -> None:
+    """Tell the operator that the #2208 guard just withheld a snapshot — but
+    only when withholding it actually changed the outcome.
+
+    Silence is what turned the original incident into an hour of
+    misdiagnosis: the fleet's ``machines`` table said ``ci-runner`` and
+    nothing anywhere said why. So when a non-canonical ``--config`` would
+    have *replaced a populated table with a different fleet* — the exact
+    shape of that incident — say so on stderr.
+
+    Everything else stays quiet, and that restraint is load-bearing rather
+    than cosmetic. ``--config <tmpfile>`` is the normal way to run coord
+    against a scratch config: CI stubs, the config *validator* in
+    ``scripts/azure-workers/coordinator-machine.py``, and every one of this
+    repo's ~110 CLI test modules. Emitting a note on each of those would
+    have made the guard a per-invocation nag, and — because Click's
+    ``CliRunner`` folds stderr into ``result.output`` — would have corrupted
+    the machine-readable stdout of commands like ``coord plans --json`` and
+    ``coord scorecard --json`` for anyone parsing combined output.
+
+    A skip with nothing to clobber (empty table, or a table that already
+    matches) withheld nothing observable, so it warrants no words.
+    """
+    try:
+        from coord.db import get_connection
+        conn = get_connection()
+        existing = [
+            str(row[0])
+            for row in conn.execute("SELECT name FROM machines ORDER BY name")
+        ]
+    except Exception:  # noqa: BLE001 — advisory only; never break the command
+        return
+    if not existing:
+        # Nothing to protect: no snapshot has ever landed here (a fresh
+        # host, or a CI runner whose DB only exists for this one command).
+        return
+    if existing == sorted(m.name for m in config.machines):
+        # The override names the same fleet — the write would have been a
+        # no-op, so the skip cost the operator nothing.
+        return
+    click.echo(
+        f"note: --config points at a non-canonical path ({config_path}); "
+        f"leaving the shared machines/pipeline snapshot untouched (#2208). "
+        f"Fleet machines on record: {', '.join(existing)}.",
+        err=True,
+    )
+
+
+def _save_config_snapshot(config: Config, config_path: Path | None = None) -> None:
     """Persist machine + pipeline metadata to the DB so dashboards can read it.
 
     Writes:
@@ -111,6 +165,13 @@ def _save_config_snapshot(config: Config) -> None:
 
     The pipeline keys let the TUI Pipeline panel pick up coordinator.yml
     settings without having to parse YAML itself.
+
+    *config_path* is the file *config* was actually loaded from. When given
+    and it is not the canonical resolution (see
+    ``coord.config.is_canonical_config_path``), the write is skipped
+    entirely — see the #2208 guard below. Callers that omit it (mainly
+    direct unit tests exercising the write itself) get the pre-#2208
+    behavior: always write.
     """
     # #584: a thin client (board_service configured) must not create/write a
     # local DB — the daemon/host owns the config snapshot.  On the host
@@ -118,6 +179,14 @@ def _save_config_snapshot(config: Config) -> None:
     from coord.client import resolve_board_service
     if resolve_board_service() is not None:
         return
+    # #2208: an explicit `--config <file>` pointed away from the fleet's real
+    # config (a scratch fixture, a CI-only stub) must not be treated as a
+    # request to redefine the shared `machines` table — that table is global
+    # state every client's `/board` and the TUI read, not something a single
+    # throwaway invocation should own.
+    if config_path is not None and not is_canonical_config_path(config_path):
+        _note_withheld_snapshot(config, config_path)
+        return
     conn = None
     try:
         from coord.db import get_connection
@@ -270,7 +339,7 @@ def _load_config(path: Path | None) -> Config:
     except ConfigError as e:
         click.echo(f"error: {e}", err=True)
         sys.exit(2)
-    _save_config_snapshot(cfg)
+    _save_config_snapshot(cfg, path)
     return cfg
 
 

{code_coordinator-0.5.92 → code_coordinator-0.5.94}/coord/commands/release.py

@@ -694,11 +694,25 @@ def release_propagate(  # noqa: PLR0912, PLR0915 — a pipeline; the decisions a
     )
     current = rp.hosts_already_current(_lane_versions_by_host(before), record.target_version)
 
+    # #2176: resolved here, ahead of cordoning, so the cordon plan can honour
+    # the same daemon-leads invariant the roll itself is bound by (see below).
+    # Purely a derivation from data already in hand (`machine_health`) — this
+    # does not move the "unorderable fleet" REFUSAL, which stays below the
+    # deferral branch on purpose (see its own comment).
+    daemon_name = _daemon_machine_name(config, daemon_host_override, machine_health)
+
     # ── 3b. cordon the hosts that are behind, so they DRAIN (#2101) ──────
     #
     # Before the deferral return below, on purpose: cordoning is the thing
     # that turns "no window" into "a window in a few minutes". A run that
     # defers without cordoning has changed nothing about why it deferred.
+    #
+    # #2176: a non-daemon host with no busy signal of its own is exempted
+    # while the daemon host is itself busy and behind — see `plan_cordons`'s
+    # `daemon_host` handling. It cannot roll ahead of a busy daemon host
+    # regardless of its own drain state (the daemon-leads invariant below),
+    # so cordoning it protects nothing and just spends fleet capacity for an
+    # unbounded wait.
     record.cordons = _apply_cordons(
         hosts=hosts,
         report=before,
@@ -712,6 +726,7 @@ def release_propagate(  # noqa: PLR0912, PLR0915 — a pipeline; the decisions a
         state_dir=state_dir,
         max_deferrals=cordon_max_deferrals,
         release_cooldown=cordon_cooldown,
+        daemon_host=daemon_name,
     )
 
     if fully_busy and not force:
@@ -722,12 +737,12 @@ def release_propagate(  # noqa: PLR0912, PLR0915 — a pipeline; the decisions a
         # meets a fleet that is actually draining.
         _finish(rp.STATUS_DEFERRED, 0)
 
-    # #2101: resolved AFTER the deferral above, deliberately. This refusal is
-    # about the ORDER a roll happens in; a run that is going to roll nothing
-    # has no order to get wrong, and turning "the fleet is busy" into a
-    # `failed` record (exit 1, systemd marks the unit failed) would teach an
-    # operator to ignore the one signal that matters.
-    daemon_name = _daemon_machine_name(config, daemon_host_override, machine_health)
+    # #2101: this refusal is checked AFTER the deferral above, deliberately.
+    # This refusal is about the ORDER a roll happens in; a run that is going
+    # to roll nothing has no order to get wrong, and turning "the fleet is
+    # busy" into a `failed` record (exit 1, systemd marks the unit failed)
+    # would teach an operator to ignore the one signal that matters.
+    # (`daemon_name` itself was resolved earlier, before cordoning — #2176.)
     if daemon_name is None and len(hosts) > 1:
         # #2052 fault 2: this used to warn and roll in coordinator.yml order.
         # It then briefly put the daemon host BEHIND both its callers during a
@@ -1082,6 +1097,7 @@ def _apply_cordons(  # noqa: PLR0912 — one linear apply-the-plan pass
     state_dir: Path | None = None,
     max_deferrals: int | None = None,
     release_cooldown: float | None = None,
+    daemon_host: str | None = None,
 ) -> dict:
     """Plan and apply this run's cordons. Returns the journal fragment.
 
@@ -1090,6 +1106,13 @@ def _apply_cordons(  # noqa: PLR0912 — one linear apply-the-plan pass
     Failing the whole propagation because the cordon could not be renewed
     would make #2101's fix strictly worse than not having it.
 
+    *daemon_host* (#2176) lets :func:`~coord.release_cordon.plan_cordons`
+    exempt a non-daemon host with no busy signal of its own from cordoning
+    while the daemon host is itself busy and behind — see that function's
+    docstring for the reasoning. ``None`` (an unorderable fleet) disables
+    the exemption and falls back to cordoning every behind host, same as
+    before #2176.
+
     #2240: *state_dir* is where the propagation journal lives, and the journal
     is where "how many runs in a row has this cordon now deferred?" is stored
     — the process holding the answer in memory is restarted by the roll it is
@@ -1162,10 +1185,13 @@ def _apply_cordons(  # noqa: PLR0912 — one linear apply-the-plan pass
             if release_cooldown is None
             else release_cooldown
         ),
+        daemon_host=daemon_host,
     )
     for line in plan.render():
         click.echo(line)
     outcome.cooling_seconds = plan.cooling_seconds
+    outcome.collateral_spared = list(plan.collateral_spared)
+    outcome.blocked_behind = plan.blocked_behind
     if plan.released is not None:
         outcome.released = plan.released.to_dict()
         # stderr as well as stdout: on the timer host this line IS the

{code_coordinator-0.5.92 → code_coordinator-0.5.94}/coord/config.py

@@ -51,6 +51,27 @@ def resolve_config_path() -> Path:
             return candidate
     return USER_CONFIG_PATH
 
+
+def is_canonical_config_path(path: Path) -> bool:
+    """Whether *path* is what :func:`resolve_config_path` resolves to *right now*.
+
+    #2208: a coord command run with an explicit ``--config <file>`` pointed
+    somewhere other than the fleet's real config — a scratch fixture, a
+    CI-only stub someone wrote specifically so ``coord.config.load()`` has
+    something to parse — is not a request to redefine the fleet. This gates
+    the shared machines/pipeline DB snapshot (``_save_config_snapshot`` in
+    ``coord/commands/_common.py``): only a *path* that matches the ordinary
+    resolution order ($COORD_CONFIG → ``~/.coord/coordinator.yml`` →
+    ``./coordinator.yml``) counts as canonical and is allowed to overwrite
+    that shared table. An explicit ``--config`` that happens to name the
+    same file the default resolution would have picked still counts as
+    canonical — this only catches a genuine *override*.
+    """
+    candidate = Path(path).expanduser().resolve()
+    canonical = resolve_config_path().expanduser().resolve()
+    return candidate == canonical
+
+
 # Safety-by-default: repos without explicit worker_permissions get this deny-list.
 DEFAULT_DENY_COMMANDS: list[str] = [
     "Bash(gh *)",

{code_coordinator-0.5.92 → code_coordinator-0.5.94}/coord/release_cordon.py

@@ -142,6 +142,35 @@ and #2082 is the cost of tolerating that. The threshold is a knob
 (``coord release propagate --cordon-after N``) precisely so a future cadence
 change does not need a code change. Trap F.
 
+CORDON-EVERY-BEHIND-HOST DOES NOT COVER A HOST THAT CANNOT ROLL EITHER WAY
+----------------------------------------------------------------------------
+Observed 2026-08-13 00:18 UTC: one busy signal, on dellserver, and the fleet
+cordoned all three machines anyway. elitebook and precision reported
+``online • idle`` throughout and stayed cordoned — launch-blocked — for
+34+ minutes, unable to accept the very review dispatch #2240 needed.
+
+The cordon-every-behind-host rule above is correct for a host whose OWN
+draining is what a run is waiting on: skip it and it never drains, and a run
+that defers without cordoning defers again in 20 minutes for the same
+reason. It does not cover a host that has no busy signal against it AND is
+blocked from rolling by the daemon-leads invariant (see
+:mod:`coord.release_propagate`'s LANE ORDER section) rather than by its own
+work — nothing may roll ahead of a busy daemon host, so such a host cannot
+roll regardless of how drained it gets. Cordoning it protects nothing: its
+drained state cannot be consumed until the daemon host rolls first, which
+may be unbounded (any drive on the daemon host reproduces this, not just a
+wedged one).
+
+:func:`plan_cordons`'s *daemon_host* parameter is the fix: while the daemon
+host is itself busy and behind, only it (and any host with its own busy
+signal) is cordoned. Everyone else stays uncordoned and dispatchable —
+released immediately if a previous run already cordoned them — until the
+daemon host becomes rollable, at which point ordinary drain-everyone-behind
+resumes. :attr:`CordonPlan.collateral_spared` /
+:attr:`CordonPlan.blocked_behind` name exactly who was spared and why, so
+the next puzzle like this one is one line of output, not a 40-minute read of
+`/board`.
+
 PURITY
 ------
 Nothing here reads the clock, the filesystem, the network or the DB — same
@@ -618,6 +647,17 @@ class CordonPlan:
     #: recorded rather than silent, because "no cordons planned" and "cordons
     #: suppressed on purpose" are the same output otherwise.
     cooling_seconds: float = 0.0
+    #: #2176: behind hosts this run deliberately did NOT cordon (and, if
+    #: already cordoned, released) because they have no busy signal of their
+    #: own and cannot roll ahead of `blocked_behind` anyway. Reported
+    #: separately from `uncordon` (which is "proven current") so the journal
+    #: and CLI output can name them as collateral rather than as a drain that
+    #: completed.
+    collateral_spared: tuple[str, ...] = ()
+    #: #2176: the daemon host these hosts are spared on account of — set
+    #: exactly when `collateral_spared` is non-empty. The single fact that
+    #: would have turned a 40-minute puzzle into one line of output.
+    blocked_behind: str | None = None
 
     @property
     def empty(self) -> bool:
@@ -627,6 +667,7 @@ class CordonPlan:
             or self.escalations
             or self.expired
             or self.released
+            or self.collateral_spared
         )
 
     def to_dict(self) -> dict:
@@ -638,6 +679,8 @@ class CordonPlan:
             "unknown": list(self.unknown),
             "released": self.released.to_dict() if self.released else None,
             "cooling_seconds": self.cooling_seconds,
+            "collateral_spared": list(self.collateral_spared),
+            "blocked_behind": self.blocked_behind,
         }
 
     def render(self) -> list[str]:
@@ -645,6 +688,14 @@ class CordonPlan:
         lines: list[str] = []
         for item in self.cordon:
             lines.append(f"  ⊘ cordon {item.machine}: {item.describe()}")
+        if self.collateral_spared:
+            lines.append(
+                "  · "
+                + ", ".join(sorted(self.collateral_spared))
+                + f": left uncordoned — blocked behind daemon host "
+                f"{self.blocked_behind} either way, cordoning would not help "
+                "(#2176)"
+            )
         for name in self.uncordon:
             lines.append(f"  ✓ uncordon {name}: up to date, work may resume")
         for name in self.expired:
@@ -748,12 +799,15 @@ def plan_cordons(
     pressure: DeferralPressure | None = None,
     max_deferrals: int = DEFAULT_MAX_DEFERRALS,
     release_cooldown: float = DEFAULT_RELEASE_COOLDOWN_SECONDS,
+    daemon_host: str | None = None,
 ) -> CordonPlan:
     """Decide this run's cordon writes. Pure.
 
     *existing* is the store as read (expired records included — this function
     is what notices they lapsed). *busy_reasons* maps a host to why it is not
-    yet drained, purely so an escalation can say what is holding it.
+    yet drained, purely so an escalation can say what is holding it — and
+    (#2176) so this function can tell a genuinely busy host from an idle one
+    when deciding who is collateral.
 
     ``enabled=False`` (``coord release propagate --no-cordon``) plans no new
     cordons but STILL clears the ones this owner already set: turning the
@@ -772,6 +826,21 @@ def plan_cordons(
     Proven-current hosts are uncordoned in every one of these branches: that
     is never the wrong move, and skipping it during a cooldown would leave a
     rolled host cordoned for the length of the cooldown.
+
+    *daemon_host* (#2176) is the machine `coord release propagate` will roll
+    first (see `coord.release_propagate`'s LANE ORDER section) — the
+    daemon-leads invariant means no OTHER host's python lane may roll ahead
+    of it while it is itself busy and behind. A behind host with no busy
+    signal of its own is therefore collateral, not protected, by a cordon
+    while that holds: it cannot roll either way, so draining it buys nothing
+    and just spends fleet capacity for a wait that is unbounded from its own
+    perspective (#2067 made quiescence per-host; this closes the cordon's
+    matching gap). Such a host is left uncordoned — and released immediately
+    if a previous run already cordoned it — until the daemon host is
+    rollable (quiescent, or already on the target), at which point ordinary
+    drain-everyone-behind resumes exactly as before #2176. A host that is
+    itself busy is cordoned regardless: its own drain is still the thing
+    being waited on, whatever the daemon host is doing.
     """
     records = _as_records(existing)
     live = {name: c for name, c in records.items() if c.active(now)}
@@ -782,11 +851,30 @@ def plan_cordons(
     if not enabled:
         return CordonPlan(uncordon=tuple(sorted(live)), expired=expired)
 
-    # Uncordon: PROVEN current, and nothing else. A host whose version could
-    # not be read keeps whatever cordon it has until that cordon EXPIRES —
-    # clearing on "we couldn't read the version" would open the fleet up
-    # mid-roll on the strength of one failed HTTP call.
-    to_uncordon = tuple(sorted(name for name in live if name in drift.current))
+    # ── #2176: who is collateral to a busy, behind daemon host ────────────
+    daemon_blocked = bool(
+        daemon_host
+        and (busy_reasons or {}).get(daemon_host)
+        and daemon_host not in drift.current
+    )
+    collateral = frozenset(
+        host
+        for host in drift.behind
+        if daemon_blocked and host != daemon_host and not (busy_reasons or {}).get(host)
+    )
+    blocked_behind = daemon_host if collateral else None
+
+    # Uncordon: PROVEN current, plus (#2176) any collateral host a previous
+    # run already cordoned — "spared" means dispatchable now, not "merely not
+    # renewed". A host whose version could not be read otherwise keeps
+    # whatever cordon it has until that cordon EXPIRES — clearing on "we
+    # couldn't read the version" would open the fleet up mid-roll on the
+    # strength of one failed HTTP call.
+    to_uncordon = tuple(
+        sorted(
+            {name for name in live if name in drift.current} | (collateral & set(live))
+        )
+    )
 
     # ── #2240: the deadlock bound ────────────────────────────────────────
     pressure = pressure or DeferralPressure()
@@ -797,6 +885,8 @@ def plan_cordons(
             expired=expired,
             cooling_seconds=cooling,
             unknown=tuple(sorted(drift.undecided & set(live))),
+            collateral_spared=tuple(sorted(collateral)),
+            blocked_behind=blocked_behind,
         )
     if max_deferrals > 0 and pressure.consecutive >= max_deferrals:
         return CordonPlan(
@@ -809,11 +899,13 @@ def plan_cordons(
                 cooldown_seconds=release_cooldown,
                 target_version=target_version,
             ),
+            collateral_spared=tuple(sorted(collateral)),
+            blocked_behind=blocked_behind,
         )
 
     to_cordon: list[Cordon] = []
     escalations: list[DrainEscalation] = []
-    for host in sorted(drift.behind):
+    for host in sorted(drift.behind - collateral):
         previous = live.get(host)
         created = previous.created_at if previous and previous.created_at else now
         to_cordon.append(
@@ -844,6 +936,8 @@ def plan_cordons(
         escalations=tuple(escalations),
         expired=expired,
         unknown=tuple(sorted(drift.undecided & set(live))),
+        collateral_spared=tuple(sorted(collateral)),
+        blocked_behind=blocked_behind,
     )
 
 
@@ -883,6 +977,13 @@ class CordonOutcome:
     #: out of the newest record instead of every caller of
     #: :func:`describe_deferral_pressure` assuming the default.
     max_deferrals: int = DEFAULT_MAX_DEFERRALS
+    #: #2176: behind hosts this run spared (or actively released) because
+    #: they have no busy signal of their own and cannot roll ahead of a busy,
+    #: behind daemon host anyway. Mirrors `CordonPlan.collateral_spared`.
+    collateral_spared: list[str] = field(default_factory=list)
+    #: #2176: the daemon host `collateral_spared` was spared on account of.
+    #: Mirrors `CordonPlan.blocked_behind`.
+    blocked_behind: str | None = None
 
     def to_dict(self) -> dict:
         return {
@@ -896,4 +997,6 @@ class CordonOutcome:
             "cooling_seconds": self.cooling_seconds,
             "pressure": dict(self.pressure),
             "max_deferrals": self.max_deferrals,
+            "collateral_spared": list(self.collateral_spared),
+            "blocked_behind": self.blocked_behind,
         }

{code_coordinator-0.5.92 → code_coordinator-0.5.94}/coord/release_propagate.py

@@ -1247,6 +1247,14 @@ def render_record(record: PropagationRecord | Mapping[str, Any]) -> list[str]:
         )
     if cordons.get("uncordoned"):
         lines.append("    uncordoned: " + ", ".join(cordons["uncordoned"]))
+    # #2176: name the collateral hosts AND the single host they're collateral
+    # to — the fact that would have turned a 40-minute puzzle into one line.
+    if cordons.get("collateral_spared"):
+        lines.append(
+            "    spared (blocked behind daemon host "
+            f"{cordons.get('blocked_behind')} anyway): "
+            + ", ".join(cordons["collateral_spared"])
+        )
     if cordons.get("expired"):
         lines.append(
             "    cordons that lapsed on their own: " + ", ".join(cordons["expired"])

{code_coordinator-0.5.92 → code_coordinator-0.5.94}/tests/test_config.py

@@ -498,6 +498,54 @@ def test_load_with_no_arg_resolves_default(tmp_path, monkeypatch) -> None:
     assert [r.name for r in cfg.repos] == ["api"]
 
 
+# ── is_canonical_config_path (#2208) ─────────────────────────────────────────
+
+
+def test_is_canonical_config_path_true_for_the_resolved_default(tmp_path, monkeypatch) -> None:
+    from coord import config as cfgmod
+
+    monkeypatch.delenv("COORD_CONFIG", raising=False)
+    home_cfg = tmp_path / "home.yml"
+    home_cfg.write_text("x")
+    monkeypatch.setattr(cfgmod, "USER_CONFIG_PATH", home_cfg)
+    monkeypatch.setattr(cfgmod, "DEFAULT_CONFIG_PATH", tmp_path / "absent-cwd.yml")
+
+    assert cfgmod.is_canonical_config_path(home_cfg) is True
+    # An equivalent (non-normalized) spelling of the same file still counts.
+    assert cfgmod.is_canonical_config_path(tmp_path / "." / "home.yml") is True
+
+
+def test_is_canonical_config_path_false_for_a_scratch_override(tmp_path, monkeypatch) -> None:
+    """#2208: a throwaway --config pointed elsewhere is NOT canonical, even
+    though coord.config.load() parses it fine."""
+    from coord import config as cfgmod
+
+    monkeypatch.delenv("COORD_CONFIG", raising=False)
+    home_cfg = tmp_path / "home.yml"
+    home_cfg.write_text("x")
+    monkeypatch.setattr(cfgmod, "USER_CONFIG_PATH", home_cfg)
+    monkeypatch.setattr(cfgmod, "DEFAULT_CONFIG_PATH", tmp_path / "absent-cwd.yml")
+
+    scratch = tmp_path / "mini2.yml"
+    scratch.write_text("machines:\n  - name: ci-runner\n    host: ci-runner\n")
+
+    assert cfgmod.is_canonical_config_path(scratch) is False
+
+
+def test_is_canonical_config_path_respects_coord_config_env(tmp_path, monkeypatch) -> None:
+    """When $COORD_CONFIG is set, THAT is the canonical path for this
+    environment — matching it counts as canonical, same as any other
+    ordinary (non-override) resolution."""
+    from coord import config as cfgmod
+
+    env_file = tmp_path / "env.yml"
+    env_file.write_text("x")
+    monkeypatch.setenv("COORD_CONFIG", str(env_file))
+
+    assert cfgmod.is_canonical_config_path(env_file) is True
+    assert cfgmod.is_canonical_config_path(tmp_path / "other.yml") is False
+
+
 # ── PipelineConfig helpers ──────────────────────────────────────────────────