code-coordinator 0.5.196__tar.gz → 0.5.197__tar.gz

{code_coordinator-0.5.196 → code_coordinator-0.5.197}/PKG-INFO

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

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

@@ -608,6 +608,7 @@ 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_cordon_stuck_2490.py
 tests/test_release_propagate.py
 tests/test_release_unified_1242.py
 tests/test_release_verify.py

{code_coordinator-0.5.196 → code_coordinator-0.5.197}/code_coordinator.egg-info/scm_file_list.json

@@ -670,6 +670,7 @@
     "tests/test_release_cordon_2101.py",
     "tests/test_release_cordon_daemon_leads_2176.py",
     "tests/test_release_cordon_deadlock_2240.py",
+    "tests/test_release_cordon_stuck_2490.py",
     "tests/test_release_propagate.py",
     "tests/test_release_unified_1242.py",
     "tests/test_release_verify.py",

{code_coordinator-0.5.196 → code_coordinator-0.5.197}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.196",
+  "tag": "0.5.197",
   "distance": 0,
-  "node": "g049ba86f1fa5713231873ab0a75ea2fa2c2fe27f",
+  "node": "gac6cd7be56630a9693710286586d56b6c59bc767",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-21"

{code_coordinator-0.5.196 → code_coordinator-0.5.197}/coord/commands/release.py

@@ -1354,6 +1354,7 @@ def _apply_cordons(  # noqa: PLR0912 — one linear apply-the-plan pass
     outcome.cooling_seconds = plan.cooling_seconds
     outcome.collateral_spared = list(plan.collateral_spared)
     outcome.blocked_behind = plan.blocked_behind
+    outcome.stuck_in_cooldown = list(plan.stuck_in_cooldown)
     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
@@ -2148,8 +2149,18 @@ def release_cordon(
             )
         )
         return
+    # #2490: hosts the newest propagate run flagged as behind, idle, and
+    # left uncordoned only because the #2240 cooldown is suppressing new
+    # cordons. These are exactly the machines an operator would otherwise
+    # have to notice by hand (`coord status` showing `online • idle` on a
+    # host that's actually stuck on an old version) — surface them even when
+    # `active` is empty, since a stuck host is by definition NOT cordoned.
+    stuck_hosts, stuck_target = _stuck_hosts_from_journal()
     if not active:
-        click.echo("no machines are cordoned — the fleet is free to take work")
+        if stuck_hosts:
+            _echo_stuck_hosts(stuck_hosts, stuck_target)
+        else:
+            click.echo("no machines are cordoned — the fleet is free to take work")
         return
     for name, record in sorted(active.items()):
         remaining = max(0.0, record.expires_at - now) / 60.0
@@ -2180,6 +2191,8 @@ def release_cordon(
             f"`coord release propagate` releases it by itself after "
             f"{rc.DEFAULT_MAX_DEFERRALS}."
         )
+    if stuck_hosts:
+        _echo_stuck_hosts(stuck_hosts, stuck_target)
     click.echo(
         f"\nclear one with `coord release cordon --clear <machine>` "
         f"(default lifetime {rc.DEFAULT_TTL_SECONDS / 60:.0f}m — a cordon "
@@ -2197,6 +2210,59 @@ def _read_propagation_records() -> list[dict]:
         return []
 
 
+def _stuck_hosts_from_journal() -> tuple[list[str], str | None]:
+    """Hosts the NEWEST propagate run flagged as stuck-in-cooldown (#2490).
+
+    ``CordonPlan.stuck_in_cooldown`` (mirrored onto ``CordonOutcome`` and
+    journalled under a run's ``cordons`` key) names behind, idle hosts a run
+    left uncordoned only because the #2240 deadlock-release cooldown is
+    still active — the gap the issue is about: nothing gave such a host a
+    signal or a path back to rolling for up to the cooldown's full length.
+
+    Only the single newest record counts, deliberately: this is a
+    point-in-time reading ("as of the last tick"), and a host named in an
+    older record may since have gone busy, rolled, or had its cooldown
+    lift — reporting it from a stale record would be a false alarm, which is
+    exactly the kind of noise this fleet already has too much of. No
+    journal (a thin client, or a host that has never run propagate)
+    degrades to nothing rather than raising — mirrors every other reader of
+    this journal in this module.
+    """
+    try:
+        records = _read_propagation_records()
+    except Exception:  # noqa: BLE001 — never load-bearing
+        return [], None
+    if not records:
+        return [], None
+    newest = records[-1]
+    if not isinstance(newest, dict):
+        return [], None
+    cordons = newest.get("cordons")
+    if not isinstance(cordons, dict):
+        return [], None
+    stuck = cordons.get("stuck_in_cooldown") or []
+    if not isinstance(stuck, list):
+        return [], None
+    target = newest.get("target_version")
+    return [str(h) for h in stuck], (str(target) if target else None)
+
+
+def _echo_stuck_hosts(stuck_hosts: list[str], stuck_target: str | None) -> None:
+    """The #2490 notice both branches of ``release_cordon`` share.
+
+    One line per host, each naming its own override command — the format
+    the issue itself asks for: "precision: 18m behind v0.5.192, idle, cordon
+    suppressed by cooldown (#2240) — consider `coord agent update --machine
+    precision`."
+    """
+    version = f"v{stuck_target}" if stuck_target else "the release"
+    click.echo(f"\n! STUCK (#2490): behind {version}, idle, cordon suppressed "
+               "by the #2240 deadlock-release cooldown — no automatic path "
+               "back to rolling until it lifts on its own:")
+    for host in sorted(stuck_hosts):
+        click.echo(f"  ! {host}: consider `coord agent update --machine {host}`")
+
+
 @release_group.command(
     "rollback",
     help=(

{code_coordinator-0.5.196 → code_coordinator-0.5.197}/coord/commands/status.py

@@ -55,6 +55,30 @@ def _cordon_stall_suffix(cordons: dict) -> str:
     return f" ({described})" if described else ""
 
 
+def _stuck_in_cooldown_hosts() -> dict[str, str | None]:
+    """Machine name -> target version, for hosts stuck-in-cooldown (#2490).
+
+    Thin wrapper around :func:`coord.commands.release._stuck_hosts_from_journal`
+    — same journal, same "newest record only" reading, reused rather than
+    reimplemented. A host in this dict is behind the target version, was
+    idle as of the last `coord release propagate` tick, and is NOT cordoned
+    (the #2240 cooldown is suppressing it) — which is exactly why it shows
+    up everywhere else in this command as a flatly ordinary `online • idle`.
+    That silence is the whole finding of #2490: a human noticed only because
+    they happened to be watching `coord status` themselves.
+
+    Degrades to ``{}`` on any error (no journal, an unreadable one, a thin
+    client) — never load-bearing, same contract as `_cordon_stall_suffix`.
+    """
+    from coord.commands.release import _stuck_hosts_from_journal  # noqa: PLC0415
+
+    try:
+        hosts, target = _stuck_hosts_from_journal()
+    except Exception:  # noqa: BLE001 — a status render must never fail on this
+        return {}
+    return {h: target for h in hosts}
+
+
 def _live_advisory_entries(
     entries: list[dict],
     cfg: "Config",
@@ -187,6 +211,9 @@ def status(config_path: Path, machine_filter: str | None, no_reconcile: bool, ti
     # same, which is why the 70-minute stall was invisible.
     cordon_stall = _cordon_stall_suffix(cordons)
     quiet_windows = effective_quiet_hours(cfg.machines)
+    # #2490: hosts the last propagate run flagged as behind + idle + stuck
+    # behind an active #2240 cooldown — see `_stuck_in_cooldown_hosts`.
+    stuck_in_cooldown = _stuck_in_cooldown_hosts()
 
     statuses = check_all(machines, timeout=timeout)
     agent_completed: dict[str, dict] = {}
@@ -314,6 +341,22 @@ def status(config_path: Path, machine_filter: str | None, no_reconcile: bool, ti
             for repo_name, reason in degraded.items():
                 click.echo(f"    ⚠ degraded: {repo_name} — {reason}")
 
+        # #2490: this host is behind the release, was idle last tick, and
+        # nothing is cordoning it because a #2240 deadlock-release cooldown
+        # is suppressing all new cordons fleet-wide. Without this line the
+        # machine above reads as a plain `online • idle` — indistinguishable
+        # from a machine with nothing to do, which is exactly how the
+        # 2026-08-20 incident went unnoticed for the length of the cooldown.
+        if m.name in stuck_in_cooldown:
+            stuck_target = stuck_in_cooldown[m.name]
+            stuck_version = f"v{stuck_target}" if stuck_target else "the release"
+            click.echo(
+                f"    ⚠ STUCK: behind {stuck_version} and idle, but cordoning "
+                "is suppressed by an active #2240 deadlock-release cooldown "
+                "(#2490) — no automatic path back to rolling until it lifts; "
+                f"consider `coord agent update --machine {m.name}`"
+            )
+
         if status_result and status_result.ok and status_result.data:
             for entry in status_result.data.get("active", []):
                 progress = entry.get("progress")

{code_coordinator-0.5.196 → code_coordinator-0.5.197}/coord/release_cordon.py

@@ -658,6 +658,17 @@ class CordonPlan:
     #: 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
+    #: #2490: hosts that are BEHIND *target_version*, have no busy signal of
+    #: their own this run (idle), and are not being cordoned only because an
+    #: unexpired deadlock-release cooldown is suppressing all new cordons —
+    #: set exactly when ``cooling_seconds > 0``. This is the gap the issue
+    #: names: a host in this state has no automatic path back to rolling for
+    #: up to the cooldown's full length, and nothing surfaced that it was
+    #: sitting there idle, behind, and unflagged. Reported separately from
+    #: ``collateral_spared`` (blocked behind a busy daemon host — a different
+    #: reason a behind host stays uncordoned) so each surface can name the
+    #: actual cause instead of collapsing both into "not cordoned".
+    stuck_in_cooldown: tuple[str, ...] = ()
 
     @property
     def empty(self) -> bool:
@@ -668,6 +679,7 @@ class CordonPlan:
             or self.expired
             or self.released
             or self.collateral_spared
+            or self.stuck_in_cooldown
         )
 
     def to_dict(self) -> dict:
@@ -681,6 +693,7 @@ class CordonPlan:
             "cooling_seconds": self.cooling_seconds,
             "collateral_spared": list(self.collateral_spared),
             "blocked_behind": self.blocked_behind,
+            "stuck_in_cooldown": list(self.stuck_in_cooldown),
         }
 
     def render(self) -> list[str]:
@@ -718,6 +731,13 @@ class CordonPlan:
                 "release (#2240) is still letting the fleet work; nothing was "
                 "cordoned this run"
             )
+        for host in self.stuck_in_cooldown:
+            lines.append(
+                f"  ! STUCK: {host} is behind and idle, but cordoning is "
+                "suppressed by the deadlock-release cooldown above (#2490) — "
+                f"it has no automatic path back to rolling until the cooldown "
+                f"lifts. Consider `coord agent update --machine {host}`."
+            )
         for esc in self.escalations:
             lines.append(f"  ! {esc.message}")
         return lines
@@ -880,6 +900,21 @@ def plan_cordons(
     pressure = pressure or DeferralPressure()
     cooling = pressure.cooling_for(now, release_cooldown)
     if cooling > 0:
+        # #2490: a behind host with no busy signal of its own has nothing
+        # left holding it back except this cooldown — it is idle, it is
+        # behind, and it will sit exactly like that until the cooldown
+        # lifts (up to `release_cooldown` seconds) with no cordon and,
+        # before this, no signal anywhere that it needs attention.
+        # `collateral` hosts are excluded: those are uncordoned for an
+        # unrelated reason (blocked behind a busy daemon host) that already
+        # has its own name (`collateral_spared`/`blocked_behind`).
+        stuck = tuple(
+            sorted(
+                host
+                for host in (drift.behind - collateral)
+                if not (busy_reasons or {}).get(host)
+            )
+        )
         return CordonPlan(
             uncordon=to_uncordon,
             expired=expired,
@@ -887,6 +922,7 @@ def plan_cordons(
             unknown=tuple(sorted(drift.undecided & set(live))),
             collateral_spared=tuple(sorted(collateral)),
             blocked_behind=blocked_behind,
+            stuck_in_cooldown=stuck,
         )
     if max_deferrals > 0 and pressure.consecutive >= max_deferrals:
         return CordonPlan(
@@ -984,6 +1020,12 @@ class CordonOutcome:
     #: #2176: the daemon host `collateral_spared` was spared on account of.
     #: Mirrors `CordonPlan.blocked_behind`.
     blocked_behind: str | None = None
+    #: #2490: mirrors `CordonPlan.stuck_in_cooldown` — behind, idle hosts this
+    #: run left uncordoned only because the #2240 deadlock cooldown is still
+    #: active. Journalled (not just printed) so a read-only surface like
+    #: `coord status` can flag them without recomputing `plan_cordons` itself
+    #: — see `coord.commands.status._stuck_in_cooldown_hosts`.
+    stuck_in_cooldown: list[str] = field(default_factory=list)
 
     def to_dict(self) -> dict:
         return {
@@ -999,4 +1041,5 @@ class CordonOutcome:
             "max_deferrals": self.max_deferrals,
             "collateral_spared": list(self.collateral_spared),
             "blocked_behind": self.blocked_behind,
+            "stuck_in_cooldown": list(self.stuck_in_cooldown),
         }

{code_coordinator-0.5.196 → code_coordinator-0.5.197}/coord/release_propagate.py

@@ -1294,6 +1294,14 @@ def render_record(record: PropagationRecord | Mapping[str, Any]) -> list[str]:
             "    cordons held off (post-release cooldown, #2240): "
             f"{float(cordons['cooling_seconds']) / 60.0:.0f}m left"
         )
+    # #2490: name the hosts that were behind and idle but left uncordoned
+    # purely because of the cooldown above — the gap that let `precision`
+    # sit stuck for 30 minutes with no automatic path back to rolling.
+    if cordons.get("stuck_in_cooldown"):
+        lines.append(
+            "    ! STUCK (idle, behind, cooldown-suppressed, #2490): "
+            + ", ".join(cordons["stuck_in_cooldown"])
+        )
     for esc in cordons.get("escalated") or []:
         lines.append(f"    ! {esc.get('message') or esc}")
     for err in cordons.get("errors") or []:

code_coordinator-0.5.197/tests/test_release_cordon_stuck_2490.py

@@ -0,0 +1,272 @@
+"""A host stuck behind during a #2240 deadlock-release cooldown has no
+automatic path back to rolling — and, until this fix, no signal anywhere
+either (#2490).
+
+Incident, 2026-08-20: `precision` needed v0.5.192, kept cycling
+busy→fail→idle→busy on the drive queue (the exact churn pattern that trips
+`max_deferrals`), self-released its cordon, and sat on the broken version —
+uncordoned, receiving normal dispatch, failing every attempt, genuinely idle
+at several points — for the length of the 30-minute cooldown. Nothing
+surfaced it: `coord status` showed a flatly ordinary `online • idle`, and
+`coord release propagate` refused to even attempt cordoning it ("nothing was
+cordoned this run"). An operator noticed only because a human happened to be
+watching `coord status`.
+
+Every test here fails against the pre-fix code: `CordonPlan` had no
+`stuck_in_cooldown` field, `CordonOutcome` did not journal one, and neither
+`coord release cordon` nor `coord status` read anything back out of the
+journal for this case — a behind, idle host during an active cooldown
+produced no cordon and no signal at all, anywhere.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from coord import release_cordon as rc
+from coord import release_propagate as rp
+from coord.cli import main
+from coord.commands import release as release_cmd
+
+
+@pytest.fixture()
+def tmp_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    (tmp_path / ".coord").mkdir()
+    return tmp_path
+
+
+def _stub_state_dir(monkeypatch, tmp_path):
+    d = tmp_path / "state"
+    d.mkdir(exist_ok=True)
+    monkeypatch.setattr(release_cmd, "_state_dir", lambda: d)
+    return d
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# `plan_cordons`: the pure acceptance criterion the issue names directly —
+# "construct a DeferralPressure that has just triggered a deadlock release
+# (cooldown active), a host that is behind the target version AND idle, and
+# assert that something ... flags it."
+# ══════════════════════════════════════════════════════════════════════════
+
+
+def test_a_behind_idle_host_is_flagged_during_the_cooldown() -> None:
+    plan = rc.plan_cordons(
+        target_version="0.5.192",
+        host_versions={"precision": "0.5.191"},
+        existing={},
+        now=1200.0,
+        pressure=rc.DeferralPressure(consecutive=0, last_release_at=1000.0),
+        busy_reasons={},
+    )
+    assert plan.cooling_seconds > 0, "the cooldown must still be active for this test"
+    assert plan.cordon == (), "the cooldown must still be suppressing new cordons"
+    assert plan.stuck_in_cooldown == ("precision",)
+    assert any("STUCK" in line and "precision" in line for line in plan.render())
+
+
+def test_a_busy_behind_host_is_not_flagged_stuck() -> None:
+    """A host that IS busy is not sitting idle for lack of a cordon — it has
+    its own work in flight, which is the ordinary "cordon deferred" case,
+    not the #2490 gap."""
+    plan = rc.plan_cordons(
+        target_version="0.5.192",
+        host_versions={"precision": "0.5.191"},
+        existing={},
+        now=1200.0,
+        pressure=rc.DeferralPressure(consecutive=0, last_release_at=1000.0),
+        busy_reasons={"precision": "dispatched: issue #2481"},
+    )
+    assert plan.stuck_in_cooldown == ()
+
+
+def test_a_current_host_is_never_flagged_stuck() -> None:
+    plan = rc.plan_cordons(
+        target_version="0.5.192",
+        host_versions={"precision": "0.5.192"},
+        existing={},
+        now=1200.0,
+        pressure=rc.DeferralPressure(consecutive=0, last_release_at=1000.0),
+        busy_reasons={},
+    )
+    assert plan.stuck_in_cooldown == ()
+
+
+def test_a_collateral_host_is_not_double_reported(monkeypatch=None) -> None:
+    """A host spared because it's blocked behind a busy daemon host already
+    has its own name for the reason (`collateral_spared`/`blocked_behind`) —
+    it must not also show up as `stuck_in_cooldown`, which would give an
+    operator two different explanations for the same machine."""
+    plan = rc.plan_cordons(
+        target_version="0.5.192",
+        host_versions={"daemon": "0.5.191", "elitebook": "0.5.191"},
+        existing={},
+        now=1200.0,
+        pressure=rc.DeferralPressure(consecutive=0, last_release_at=1000.0),
+        busy_reasons={"daemon": "dispatched: issue #1"},
+        daemon_host="daemon",
+    )
+    assert plan.collateral_spared == ("elitebook",)
+    assert "elitebook" not in plan.stuck_in_cooldown
+    # the daemon host itself IS busy, so it is not idle either
+    assert "daemon" not in plan.stuck_in_cooldown
+
+
+def test_outside_a_cooldown_nothing_is_flagged_stuck() -> None:
+    """Ordinary drain: the host gets cordoned outright, so there is nothing
+    to flag — `stuck_in_cooldown` is specifically the cooldown-suppressed
+    case."""
+    plan = rc.plan_cordons(
+        target_version="0.5.192",
+        host_versions={"precision": "0.5.191"},
+        existing={},
+        now=100.0,
+        pressure=rc.DeferralPressure(),
+        busy_reasons={},
+    )
+    assert plan.stuck_in_cooldown == ()
+    assert [c.machine for c in plan.cordon] == ["precision"]
+
+
+def test_to_dict_and_outcome_carry_the_field() -> None:
+    plan = rc.plan_cordons(
+        target_version="0.5.192",
+        host_versions={"precision": "0.5.191"},
+        existing={},
+        now=1200.0,
+        pressure=rc.DeferralPressure(consecutive=0, last_release_at=1000.0),
+        busy_reasons={},
+    )
+    assert plan.to_dict()["stuck_in_cooldown"] == ["precision"]
+    assert not plan.empty, "a stuck host is actionable — never silently 'empty'"
+
+    outcome = rc.CordonOutcome()
+    outcome.stuck_in_cooldown = list(plan.stuck_in_cooldown)
+    assert outcome.to_dict()["stuck_in_cooldown"] == ["precision"]
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# The journal round trip: `_apply_cordons` writes it, `_stuck_hosts_from_
+# journal` reads it back — the same shape `coord status` and `coord release
+# cordon` both consume.
+# ══════════════════════════════════════════════════════════════════════════
+
+
+def test_stuck_hosts_from_journal_reads_the_newest_record(
+    tmp_home, monkeypatch, tmp_path
+) -> None:
+    state_dir = _stub_state_dir(monkeypatch, tmp_path)
+    rp.append_record(
+        state_dir,
+        rp.PropagationRecord(
+            started_at=1.0, target_version="0.5.192",
+            status=rp.STATUS_DEFERRED,
+            cordons={"stuck_in_cooldown": ["precision"]},
+        ),
+    )
+    hosts, target = release_cmd._stuck_hosts_from_journal()
+    assert hosts == ["precision"]
+    assert target == "0.5.192"
+
+
+def test_stuck_hosts_from_journal_only_trusts_the_newest_record(
+    tmp_home, monkeypatch, tmp_path
+) -> None:
+    """A host named in an OLDER record may since have gone busy, rolled, or
+    had its cooldown lift — reporting it would be a false alarm."""
+    state_dir = _stub_state_dir(monkeypatch, tmp_path)
+    rp.append_record(
+        state_dir,
+        rp.PropagationRecord(
+            started_at=1.0, target_version="0.5.192",
+            status=rp.STATUS_DEFERRED,
+            cordons={"stuck_in_cooldown": ["precision"]},
+        ),
+    )
+    rp.append_record(
+        state_dir,
+        rp.PropagationRecord(
+            started_at=2.0, target_version="0.5.192",
+            status=rp.STATUS_DEFERRED,
+            cordons={"stuck_in_cooldown": []},
+        ),
+    )
+    hosts, _target = release_cmd._stuck_hosts_from_journal()
+    assert hosts == []
+
+
+def test_no_journal_reads_as_nothing_stuck(tmp_home, monkeypatch, tmp_path) -> None:
+    _stub_state_dir(monkeypatch, tmp_path)
+    assert release_cmd._stuck_hosts_from_journal() == ([], None)
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# `coord release cordon`: the surface an operator lands on once they've
+# noticed the fleet is quiet. Pre-fix, this printed "no machines are
+# cordoned — the fleet is free to take work" for exactly the incident above
+# — technically true and completely misleading.
+# ══════════════════════════════════════════════════════════════════════════
+
+
+def test_the_cordon_listing_flags_a_stuck_host_even_with_none_cordoned(
+    tmp_home, monkeypatch, tmp_path
+) -> None:
+    _stub_state_dir(monkeypatch, tmp_path)
+    rp.append_record(
+        Path(tmp_path / "state"),
+        rp.PropagationRecord(
+            started_at=1.0, target_version="0.5.192",
+            status=rp.STATUS_DEFERRED,
+            cordons={"stuck_in_cooldown": ["precision"]},
+        ),
+    )
+    listed = CliRunner().invoke(main, ["release", "cordon"])
+    assert listed.exit_code == 0, listed.output
+    assert "STUCK" in listed.output
+    assert "precision" in listed.output
+    assert "v0.5.192" in listed.output
+    assert "#2490" in listed.output
+    assert "coord agent update --machine precision" in listed.output
+
+
+def test_the_cordon_listing_is_quiet_when_nothing_is_stuck(
+    tmp_home, monkeypatch, tmp_path
+) -> None:
+    _stub_state_dir(monkeypatch, tmp_path)
+    listed = CliRunner().invoke(main, ["release", "cordon"])
+    assert listed.exit_code == 0, listed.output
+    assert "STUCK" not in listed.output
+    assert "no machines are cordoned" in listed.output
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# `coord status`'s own reader — same journal, same helper underneath.
+# ══════════════════════════════════════════════════════════════════════════
+
+
+def test_status_surface_reads_the_stuck_hosts(tmp_home, monkeypatch, tmp_path) -> None:
+    from coord.commands.status import _stuck_in_cooldown_hosts
+
+    state_dir = _stub_state_dir(monkeypatch, tmp_path)
+    rp.append_record(
+        state_dir,
+        rp.PropagationRecord(
+            started_at=1.0, target_version="0.5.192",
+            status=rp.STATUS_DEFERRED,
+            cordons={"stuck_in_cooldown": ["precision"]},
+        ),
+    )
+    assert _stuck_in_cooldown_hosts() == {"precision": "0.5.192"}
+
+
+def test_status_surface_degrades_to_empty_with_no_journal(
+    tmp_home, monkeypatch, tmp_path
+) -> None:
+    from coord.commands.status import _stuck_in_cooldown_hosts
+
+    _stub_state_dir(monkeypatch, tmp_path)
+    assert _stuck_in_cooldown_hosts() == {}

{code_coordinator-0.5.196 → code_coordinator-0.5.197}/tests/test_release_propagate.py

@@ -664,6 +664,26 @@ def test_a_real_roll_is_never_collapsed():
     assert "verify: ok" in out
 
 
+def test_a_stuck_in_cooldown_host_is_named_in_history():
+    """#2490: a host that's behind, idle, and left uncordoned only by an
+    active #2240 cooldown must be visible in `coord release history`, not
+    just in the raw JSON — this is the surface an operator reaches for after
+    `coord status` looked ordinary."""
+    records = [
+        {"started_at": 1.0, "status": rp.STATUS_DEFERRED,
+         "target_version": "0.5.192",
+         "quiescence": {"reason": "busy"},
+         "cordons": {"cooling_seconds": 900.0, "stuck_in_cooldown": ["precision"]}},
+        {"started_at": 2.0, "status": rp.STATUS_VERIFIED, "target_version": "0.4.111",
+         "lanes": [{"lane": "python", "host": "dellserver", "ok": True, "detail": "now v0.4.111"}],
+         "verification": {"severity": "ok", "findings": []}},
+    ]
+    out = rp.render_history(records)
+    assert "STUCK" in out
+    assert "precision" in out
+    assert "#2490" in out
+
+
 def test_a_rollback_is_rendered():
     record = rp.PropagationRecord(
         started_at=1.0, target_version="0.4.111", status=rp.STATUS_ROLLED_BACK,