code-coordinator 0.5.519__tar.gz → 0.5.520__tar.gz

{code_coordinator-0.5.519 → code_coordinator-0.5.520}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.519
+Version: 0.5.520
 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.519 → code_coordinator-0.5.520}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.519",
+  "tag": "0.5.520",
   "distance": 0,
-  "node": "gdec8a9dd7ece07ccb502104f68acf67eeaff322a",
+  "node": "g2ea6b6f3078698338dac5da492049a1c5a760d8e",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-26"

{code_coordinator-0.5.519 → code_coordinator-0.5.520}/coord/gates.py

@@ -42,6 +42,7 @@ duck-typed shape they expect.
 from __future__ import annotations
 
 from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
 from typing import TYPE_CHECKING
 
 from coord.confirm_test import (
@@ -60,6 +61,21 @@ if TYPE_CHECKING:  # avoid import cycles / heavy imports at module load
 # "smoke_required" finds both a live merge attempt AND a `coord gates` read.
 REVIEW_REQUIRED = "review_required"
 SMOKE_REQUIRED = "smoke_required"
+# #3445: distinct from the two tokens above — a latched HUMAN_REQUIRED
+# merge-queue entry (an automated conflict-fix that already gave up, #1291)
+# is not "review/smoke unmet", it is "the merge itself already failed and
+# needs a human (or `--override-human-required`)". Clearing review or smoke
+# cannot unstick it, so it outranks both as the merge gate's headline reason
+# — see `_merge_queue_state_decision` and its call site in
+# `build_gate_report`.
+HUMAN_REQUIRED_BLOCKED = "human_required"
+# #3445 review: SKIPPED is `_merge_queue_state_decision`'s own comment's
+# other "parked, needs-attention" state alongside HUMAN_REQUIRED (and
+# `coord/drive.py`'s `_RETRYABLE_MERGE_STATUSES` docstring independently
+# documents it as equally terminal, unlike CONFLICT, which self-heals via
+# `dispatch_conflict_fix` and is deliberately NOT in this override) — so it
+# gets the same headline-outranking treatment, not just HUMAN_REQUIRED.
+SKIPPED_BLOCKED = "skipped"
 
 
 @dataclass
@@ -451,6 +467,124 @@ def _exempt_dependency_notes_for_winner(
         return []
 
 
+def _iso(ts: float | None) -> str | None:
+    if not ts:
+        return None
+    return datetime.fromtimestamp(float(ts), tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%SZ")
+
+
+def _merge_queue_state_decision(
+    repo_name: str, issue_number: int, fallback_assignment_id: str | None,
+) -> GateDecision | None:
+    """The REAL, persisted ``merge_queue`` row's state for
+    ``(repo_name, issue_number)``, or ``None`` when no such row exists
+    (#3445).
+
+    This is deliberately a *second* read, distinct from the synthetic
+    ``QueuedMerge`` :func:`build_gate_report` builds via
+    ``mq.live_gate_entry`` to feed the review/test/registry gate checks:
+    that object is constructed fresh on every call and never persisted, so
+    it always carries the dataclass default ``state=PENDING`` — it was
+    never going to surface a *latched* CONFLICT/HUMAN_REQUIRED/SKIPPED.
+    Before this, ``coord gates`` had no read of the real merge-queue table
+    at all, so an issue whose entry had already given up (an automated
+    conflict-fix exhausting its one retry, #1291, or a stale-rebase worker
+    refusing to push a non-content-preserving rebase) reported
+    ``merge : BLOCKED — smoke_required`` — true in isolation, but not the
+    reason nothing is moving: clearing the smoke gate cannot unstick a
+    HUMAN_REQUIRED entry, only a human (or ``coord merge --only <aid>
+    --override-human-required``) can.
+
+    Matched on ``(repo_name, issue_number)`` — the same two facts
+    :func:`coord.drive_state._merge_entry` matches the raw ``merge_queue``
+    row against for exactly the same reason (a fix-chain may have re-keyed
+    the entry's ``assignment_id`` to a newer work row) — with
+    *fallback_assignment_id* (the winning work row `build_gate_report`
+    already selected) preferred when more than one row matches.
+
+    Fail-open like every other best-effort DB read in this module
+    (``_backfill_is_interactive``, ``_apply_gate_decision``): an
+    unreachable DB degrades to "no merge-queue line" rather than failing
+    the whole ``coord gates`` read.
+    """
+    try:
+        from coord import merge_queue as mq  # noqa: PLC0415
+
+        entries = mq.load_queue()
+    except Exception:  # noqa: BLE001 — advisory only, see docstring
+        return None
+
+    matches = [
+        e for e in entries
+        if e.repo_name == repo_name and e.issue_number == issue_number
+    ]
+    if not matches:
+        return None
+    if fallback_assignment_id:
+        by_aid = [e for e in matches if e.assignment_id == fallback_assignment_id]
+        if by_aid:
+            matches = by_aid
+    # First match in list order — not the most recent — mirroring
+    # `coord.drive_state._merge_entry` (the docstring's own cited
+    # precedent for matching on this same `(repo_name, issue_number)` pair):
+    # when more than one row matches and none matches *fallback_assignment_id*
+    # (e.g. a retarget/new branch for the same issue left an old row behind),
+    # `coord gates` must agree with the other `merge_queue` consumers
+    # (`coord drive-queue block-log`, `coord status`, `_decide_merge`) on
+    # which row is "the" entry, or the same issue reads differently on
+    # different surfaces (#3445 review).
+    entry = matches[0]
+
+    state = (entry.state or "").upper()
+    # PENDING/MERGING/MERGED (and any future non-terminal state) read as
+    # "nothing to escalate here" — the raw state name is still shown, but
+    # unadorned. CONFLICT/HUMAN_REQUIRED/SKIPPED are the parked, needs-
+    # attention states. Delegated to `mq._state_to_plan_status` — the
+    # CANONICAL classifier for this exact question (`PENDING`->READY,
+    # `MERGING`->MERGING, `MERGED`->MERGED, anything else, including any
+    # future/unknown state -> NEEDS_ATTENTION) — rather than a second,
+    # hand-maintained tuple of "which states need attention" that could
+    # silently drift from it (#2096, #3445 review). That classifier fails
+    # CLOSED on an unrecognized state; re-deriving the tri-state locally
+    # would fail open instead, exactly the "gate must be able to fail"
+    # pattern this repo's review checklist calls out.
+    ok = mq._state_to_plan_status(entry.state or "") != mq.PLAN_NEEDS_ATTENTION
+
+    reason: str | None = None
+    if state == "HUMAN_REQUIRED":
+        aid = entry.assignment_id or fallback_assignment_id or "<assignment-id>"
+        detail_lines = [entry.error or "no reason recorded"]
+        latched = _iso(entry.last_attempt)
+        if latched:
+            detail_lines.append(
+                f"as of last merge-queue write {latched} — this timestamp "
+                "does not advance while the entry is parked, so treat it as "
+                "a LOWER BOUND on when it latched, not necessarily still "
+                "current (#3445)"
+            )
+        else:
+            detail_lines.append(
+                "latched time unknown — no merge-queue attempt timestamp "
+                "recorded on this entry"
+            )
+        detail_lines.append(
+            f"override: coord merge --only {aid} --override-human-required "
+            "'<reason>'"
+        )
+        reason = "\n".join(detail_lines)
+    elif not ok:
+        reason = entry.error or None
+
+    return GateDecision(
+        gate="merge_queue",
+        required=False,
+        ok=ok,
+        reason=reason,
+        state=state or None,
+        assignment_id=entry.assignment_id or None,
+    )
+
+
 def _apply_gate_decision(repo_name: str, issue_number: int) -> GateDecision | None:
     """The ``"apply"`` :class:`GateDecision` for *(repo_name, issue_number)*,
     or ``None`` when there is no ``--hold-after`` deploy-gate entry for it in
@@ -741,8 +875,42 @@ def build_gate_report(
         registry_decisions[gate_name] = decision
         report.decisions.append(decision)
 
+    # #3445: the REAL, persisted merge-queue row — distinct from the
+    # synthetic `entry` above, which always reads state=PENDING (see
+    # `_merge_queue_state_decision`'s docstring). Read AFTER the registry
+    # gates so it can be reported alongside them, but consulted FIRST below
+    # when deciding the merge gate's headline reason: a latched
+    # HUMAN_REQUIRED (or SKIPPED, #3445 review) entry is the actual reason
+    # nothing is moving, and no amount of review/smoke/registry-gate
+    # clearing can unstick it. CONFLICT is deliberately NOT in this set — it
+    # self-heals via `dispatch_conflict_fix` (#1474), so it does not outrank
+    # the normal review/smoke headline.
+    mq_state_decision = _merge_queue_state_decision(
+        repo_name, issue_number, winner.assignment_id,
+    )
+    if mq_state_decision is not None:
+        report.decisions.append(mq_state_decision)
+
     merge_blocked_gate: str | None = None
-    if review_required and not review_ok:
+    if mq_state_decision is not None and mq_state_decision.state in (
+        "HUMAN_REQUIRED", "SKIPPED",
+    ):
+        # #3445 review: the full detail (reason, latched-time caveat,
+        # override command) is already rendered on the "merge-queue" line
+        # `format_gate_report` prints alongside this one — keep the
+        # presentation cross-reference ("see the merge-queue line above...")
+        # OUT of this data field, since `merge.reason` is also consumed
+        # verbatim by non-CLI-rendering readers with no such line above it
+        # (`coord.queue_diagnose`'s `_gates()` probe). This field stays a
+        # short, state-only headline; `format_gate_report` adds the
+        # cross-reference itself, only where the referent actually exists.
+        token = (
+            HUMAN_REQUIRED_BLOCKED
+            if mq_state_decision.state == "HUMAN_REQUIRED"
+            else SKIPPED_BLOCKED
+        )
+        merge_blocked_gate = f"{token} — {mq_state_decision.state}"
+    elif review_required and not review_ok:
         merge_blocked_gate = REVIEW_REQUIRED
     elif smoke_required and not test_ok:
         merge_blocked_gate = SMOKE_REQUIRED
@@ -912,6 +1080,29 @@ def format_gate_report(report: GateReport) -> str:
                 lines.append(f"           {test.reason}")
             else:
                 lines.append(f"  test   : BLOCKED — {test.reason}")
+        # #3445: the REAL, persisted merge-queue row's state — distinct from
+        # the review/test/merge decisions above, which are all evaluated
+        # against a synthetic, never-persisted entry (see
+        # `_merge_queue_state_decision`'s docstring). Only printed when a
+        # row actually exists for this (repo, issue) — the common case for
+        # an issue that never reached the merge queue at all is silence,
+        # same convention as the "apply" line below. A HUMAN_REQUIRED row
+        # gets its full multi-line detail (reason, latched-time caveat,
+        # override command); every other state is a single unadorned line.
+        merge_queue_decision = by_gate.get("merge_queue")
+        if merge_queue_decision is not None:
+            state_label = merge_queue_decision.state or "UNKNOWN"
+            detail_lines = (
+                merge_queue_decision.reason.split("\n")
+                if merge_queue_decision.reason
+                else []
+            )
+            if not detail_lines:
+                lines.append(f"  merge-queue : {state_label}")
+            else:
+                lines.append(f"  merge-queue : {state_label} — {detail_lines[0]}")
+                for extra in detail_lines[1:]:
+                    lines.append(f"                {extra}")
         # #3273 (S-5 of #3261): any other registry-backed gate (today just
         # "uat") renders generically here, in `report.decisions`' own
         # insertion order — a gate GATE_REGISTRY grows in the future needs no
@@ -919,7 +1110,7 @@ def format_gate_report(report: GateReport) -> str:
         # skipped/inapplicable one (UAT not configured, or an exempt issue)
         # gets an explicit reason instead of being silently omitted like it
         # was before #3273.
-        _KNOWN_GATE_LINES = ("review", "test", "merge", "apply")
+        _KNOWN_GATE_LINES = ("review", "test", "merge_queue", "merge", "apply")
         for decision in report.decisions:
             if decision.gate in _KNOWN_GATE_LINES:
                 continue
@@ -938,9 +1129,27 @@ def format_gate_report(report: GateReport) -> str:
                 lines.append(f"  {label} : BLOCKED — {decision.reason}")
         merge = by_gate.get("merge")
         if merge is not None:
-            lines.append(
-                "  merge  : READY" if merge.ok else f"  merge  : BLOCKED — {merge.reason}"
-            )
+            if merge.ok:
+                lines.append("  merge  : READY")
+            else:
+                lines.append(f"  merge  : BLOCKED — {merge.reason}")
+                # #3445 review: the cross-reference belongs only in THIS
+                # rendering, right after the "merge-queue" line it actually
+                # points at — not baked into `merge.reason` itself, which
+                # `coord.queue_diagnose`'s `_gates()` probe also surfaces
+                # verbatim with no such line above it.
+                if (
+                    merge_queue_decision is not None
+                    and merge_queue_decision.state in ("HUMAN_REQUIRED", "SKIPPED")
+                ):
+                    lines.append(
+                        "           (see the merge-queue line above for detail"
+                        + (
+                            " — the latched time and the override command)"
+                            if merge_queue_decision.state == "HUMAN_REQUIRED"
+                            else ")"
+                        )
+                    )
         # #3236: only printed when a --hold-after deploy gate actually
         # exists for this (repo, issue) — see `_apply_gate_decision`.
         apply_ = by_gate.get("apply")

{code_coordinator-0.5.519 → code_coordinator-0.5.520}/tests/test_gates.py

@@ -12,7 +12,9 @@ import pytest
 from coord import merge_queue as mq
 from coord.config import Config, PipelineConfig, ReviewsConfig
 from coord.gates import (
+    HUMAN_REQUIRED_BLOCKED,
     REVIEW_REQUIRED,
+    SKIPPED_BLOCKED,
     SMOKE_REQUIRED,
     build_gate_report,
     format_gate_report,
@@ -824,6 +826,212 @@ class TestApplyGate:
         assert "MERGED, NOT APPLIED" not in text
 
 
+# ── merge-queue latched state (#3445) ────────────────────────────────────────
+# `mq.live_gate_entry` (used for the review/test/registry gates above) is a
+# SYNTHETIC, never-persisted QueuedMerge — it always reads state=PENDING, so
+# it was blind to a latched CONFLICT/HUMAN_REQUIRED/SKIPPED row. These tests
+# cover the REAL, persisted `merge_queue` table read this issue adds.
+
+class TestMergeQueueHumanRequired:
+    def test_no_merge_queue_entry_means_no_merge_queue_line(
+        self, config: Config, coord_db,
+    ) -> None:
+        work = _work(test_state=None)
+        review = _review("w1", verdict="approve")
+        board = Board(active=[], completed=[work, review])
+        report = build_gate_report(board, config, "api", 42, gh_ops=FakeGh())
+
+        by_gate = {d.gate: d for d in report.decisions}
+        assert "merge_queue" not in by_gate
+        assert by_gate["merge"].reason == SMOKE_REQUIRED
+
+    def test_pending_merge_queue_entry_does_not_override_smoke_required(
+        self, config: Config, coord_db,
+    ) -> None:
+        work = _work(test_state=None)
+        review = _review("w1", verdict="approve")
+        board = Board(active=[], completed=[work, review])
+        mq.save_queue([
+            mq.QueuedMerge(
+                assignment_id="w1", repo_name="api", repo_github="acme/api",
+                branch="issue-42-foo", target_branch="main", issue_number=42,
+                issue_title="t", state=mq.PENDING,
+            )
+        ])
+        report = build_gate_report(board, config, "api", 42, gh_ops=FakeGh())
+
+        by_gate = {d.gate: d for d in report.decisions}
+        assert by_gate["merge_queue"].state == "PENDING"
+        assert by_gate["merge_queue"].ok is True
+        assert by_gate["merge"].reason == SMOKE_REQUIRED
+        assert "merge-queue : PENDING" in format_gate_report(report)
+
+    def test_human_required_entry_outranks_smoke_required(
+        self, config: Config, coord_db,
+    ) -> None:
+        # #3445 repro (vimcode#523/#526): smoke never ran (test_state=None)
+        # AND the merge-queue entry already latched HUMAN_REQUIRED — a
+        # stale-rebase worker refused to push a non-content-preserving
+        # rebase. Clearing the smoke gate cannot unstick that, so it must be
+        # the merge gate's HEADLINE reason, not "smoke_required".
+        work = _work(test_state=None)
+        review = _review("w1", verdict="approve")
+        board = Board(active=[], completed=[work, review])
+        mq.save_queue([
+            mq.QueuedMerge(
+                assignment_id="w1", repo_name="api", repo_github="acme/api",
+                branch="issue-42-foo", target_branch="main", issue_number=42,
+                issue_title="t", state=mq.HUMAN_REQUIRED,
+                error=(
+                    "stale-rebase worker refused to push: rebase was not "
+                    "content-preserving — manual resolution required"
+                ),
+                last_attempt=1_700_000_000.0,
+            )
+        ])
+        report = build_gate_report(board, config, "api", 42, gh_ops=FakeGh())
+
+        by_gate = {d.gate: d for d in report.decisions}
+        mq_decision = by_gate["merge_queue"]
+        assert mq_decision.state == "HUMAN_REQUIRED"
+        assert mq_decision.ok is False
+        assert "stale-rebase worker refused to push" in mq_decision.reason
+        assert "--override-human-required" in mq_decision.reason
+
+        merge = by_gate["merge"]
+        assert merge.ok is False
+        assert merge.reason != SMOKE_REQUIRED
+        assert merge.reason.startswith(HUMAN_REQUIRED_BLOCKED)
+        assert "HUMAN_REQUIRED" in merge.reason
+
+        text = format_gate_report(report)
+        assert "HUMAN_REQUIRED" in text
+        assert "stale-rebase worker refused to push" in text
+        assert "--override-human-required" in text
+        assert "merge-queue : HUMAN_REQUIRED" in text
+        assert "smoke_required" not in text
+
+    def test_human_required_with_no_recorded_error_still_reports(
+        self, config: Config, coord_db,
+    ) -> None:
+        """A HUMAN_REQUIRED entry with no `error` text at all (shouldn't
+        normally happen, but the reader must not crash or go silent)."""
+        work = _work(test_state="passed")
+        review = _review("w1", verdict="approve")
+        board = Board(active=[], completed=[work, review])
+        mq.save_queue([
+            mq.QueuedMerge(
+                assignment_id="w1", repo_name="api", repo_github="acme/api",
+                branch="issue-42-foo", target_branch="main", issue_number=42,
+                issue_title="t", state=mq.HUMAN_REQUIRED,
+            )
+        ])
+        report = build_gate_report(board, config, "api", 42, gh_ops=FakeGh())
+
+        by_gate = {d.gate: d for d in report.decisions}
+        assert "no reason recorded" in by_gate["merge_queue"].reason
+        assert "latched time unknown" in by_gate["merge_queue"].reason
+        assert by_gate["merge"].reason.startswith(HUMAN_REQUIRED_BLOCKED)
+
+    def test_skipped_entry_also_outranks_smoke_required(
+        self, config: Config, coord_db,
+    ) -> None:
+        """#3445 review: SKIPPED is the sibling terminal, needs-attention
+        state to HUMAN_REQUIRED (unlike CONFLICT, which self-heals via
+        `dispatch_conflict_fix`) — it must outrank `smoke_required` as the
+        merge gate's headline reason too, not just HUMAN_REQUIRED."""
+        work = _work(test_state=None)
+        review = _review("w1", verdict="approve")
+        board = Board(active=[], completed=[work, review])
+        mq.save_queue([
+            mq.QueuedMerge(
+                assignment_id="w1", repo_name="api", repo_github="acme/api",
+                branch="issue-42-foo", target_branch="main", issue_number=42,
+                issue_title="t", state=mq.SKIPPED,
+                error="closed as duplicate of #99",
+            )
+        ])
+        report = build_gate_report(board, config, "api", 42, gh_ops=FakeGh())
+
+        by_gate = {d.gate: d for d in report.decisions}
+        mq_decision = by_gate["merge_queue"]
+        assert mq_decision.state == "SKIPPED"
+        assert mq_decision.ok is False
+
+        merge = by_gate["merge"]
+        assert merge.ok is False
+        assert merge.reason != SMOKE_REQUIRED
+        assert merge.reason.startswith(SKIPPED_BLOCKED)
+        assert "SKIPPED" in merge.reason
+
+        text = format_gate_report(report)
+        assert "merge-queue : SKIPPED" in text
+        assert "smoke_required" not in text
+
+    def test_conflict_entry_does_not_outrank_smoke_required(
+        self, config: Config, coord_db,
+    ) -> None:
+        """CONFLICT is excluded from the headline override on purpose — it
+        self-heals via a `coord merge --only` retry (`dispatch_conflict_fix`,
+        #1474), so `smoke_required` stays the accurate headline reason."""
+        work = _work(test_state=None)
+        review = _review("w1", verdict="approve")
+        board = Board(active=[], completed=[work, review])
+        mq.save_queue([
+            mq.QueuedMerge(
+                assignment_id="w1", repo_name="api", repo_github="acme/api",
+                branch="issue-42-foo", target_branch="main", issue_number=42,
+                issue_title="t", state=mq.CONFLICT,
+                error="merge conflict in foo.py",
+            )
+        ])
+        report = build_gate_report(board, config, "api", 42, gh_ops=FakeGh())
+
+        by_gate = {d.gate: d for d in report.decisions}
+        assert by_gate["merge_queue"].state == "CONFLICT"
+        assert by_gate["merge_queue"].ok is False
+        assert by_gate["merge"].reason == SMOKE_REQUIRED
+
+    def test_multiple_rows_for_same_issue_picks_first_match_in_list_order(
+        self, config: Config, coord_db,
+    ) -> None:
+        """#3445 review: when more than one `merge_queue` row matches
+        `(repo_name, issue_number)` and none matches the winning work row's
+        assignment id, `coord gates` must pick the SAME row every other
+        `merge_queue` consumer would — `coord.drive_state._merge_entry`
+        takes the first match in list order (oldest/lowest id), not the most
+        recent, so this mirrors that instead of silently disagreeing with
+        `coord drive-queue block-log`/`coord status`/`_decide_merge` about
+        which row is "the" entry for this issue."""
+        work = _work(test_state=None)
+        review = _review("w1", verdict="approve")
+        board = Board(active=[], completed=[work, review])
+        mq.save_queue([
+            mq.QueuedMerge(
+                assignment_id="stale-aid", repo_name="api", repo_github="acme/api",
+                branch="issue-42-old-branch", target_branch="main", issue_number=42,
+                issue_title="t", state=mq.HUMAN_REQUIRED,
+                error="first (older) row — left behind by a retarget",
+            ),
+            mq.QueuedMerge(
+                assignment_id="other-stale-aid", repo_name="api", repo_github="acme/api",
+                branch="issue-42-newer-branch", target_branch="main", issue_number=42,
+                issue_title="t", state=mq.PENDING,
+                error="second (newer) row",
+            ),
+        ])
+        report = build_gate_report(board, config, "api", 42, gh_ops=FakeGh())
+
+        by_gate = {d.gate: d for d in report.decisions}
+        mq_decision = by_gate["merge_queue"]
+        # Neither row's assignment_id matches the winning work row ("w1"),
+        # so the fallback-by-assignment-id narrowing never kicks in — the
+        # first (oldest) row in insertion order wins.
+        assert mq_decision.assignment_id == "stale-aid"
+        assert mq_decision.state == "HUMAN_REQUIRED"
+        assert "first (older) row" in mq_decision.reason
+
+
 # ── is_interactive enrichment (#748/#632: not an Assignment dataclass field) ─
 
 class TestIsInteractive: