code-coordinator 0.5.77__tar.gz → 0.5.78__tar.gz

{code_coordinator-0.5.77 → code_coordinator-0.5.78}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.77",
+  "tag": "0.5.78",
   "distance": 0,
-  "node": "gb940996c651692e5e0c90012a9046b2dfe09ec50",
+  "node": "g8c83f30ecf95a0893142d13948ccbadef68524f8",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-14"

{code_coordinator-0.5.77 → code_coordinator-0.5.78}/coord/commands/merge.py

@@ -76,6 +76,7 @@ def _apply_revalidation(items, board, config, gh_ops, *, dry_run: bool):
 
     recorded_any = False
     total_runs = 0
+    conflicted: list = []
     groups = _rv.group_candidates(candidates)
     for (repo_name, target_branch), group in groups:
         click.echo(
@@ -85,6 +86,7 @@ def _apply_revalidation(items, board, config, gh_ops, *, dry_run: bool):
         batch = _rv.revalidate_group(group, config, echo=click.echo)
         total_runs += batch.suite_runs
         recorded_any = recorded_any or bool(batch.recorded)
+        conflicted.extend(batch.conflicted)
         if not batch.composite.ok:
             # The composite's own failure report — stderr, as before.
             for line in _rv.format_failure(batch.composite):
@@ -100,6 +102,13 @@ def _apply_revalidation(items, board, config, gh_ops, *, dry_run: bool):
             f"{len(candidates)} entry(ies)"
         )
 
+    # #2231: the composed run just PROVED these branches don't merge. That is
+    # not a staleness problem and re-testing can never resolve it — hand it to
+    # the mechanism built for it instead of formatting a diagnosis nobody acts
+    # on.
+    if conflicted:
+        _dispatch_revalidation_conflicts(conflicted, config, dry_run=dry_run)
+
     if not recorded_any:
         return board
 
@@ -249,6 +258,65 @@ def _reload_board_after_wait(board, *, dry_run: bool):
     return refreshed if refreshed is not None else _Board(active=[], completed=[])
 
 
+def _dispatch_revalidation_conflicts(conflicted, config, *, dry_run: bool) -> None:
+    """#2231: turn ``--revalidate``'s conflict verdict into a #241 dispatch.
+
+    *conflicted* is :attr:`coord.revalidate.BatchRevalidationResult.conflicted`
+    — the candidates whose revalidation run died composing the branch onto its
+    current base. ``--revalidate`` already did the expensive, authoritative
+    part: it fetched, built a worktree at the live base, ran ``git merge`` and
+    watched it fail. That is strictly better evidence than the failed ``gh pr
+    merge`` that normally arms this path, and it was being spent on an
+    operator-facing paragraph and then discarded (quadraui #306/#309 sat 11h
+    each behind a "test verdict stale" gate whose real blocker was a content
+    conflict; a human eventually typed ``coord fix --force`` by hand, which is
+    #241's own job description).
+
+    Two things happen per entry, in this order:
+
+    1. The entry is moved to ``CONFLICT`` with an ``entry.error`` that names
+       the conflict (:func:`coord.revalidate.compose_conflict_error`). This is
+       the reporting half: the gate reason stops reading (only) "stale
+       verdict", so ``coord drive``'s #1738 arm no longer sees a shape it
+       would answer with a re-test, and ``merge_queue.process()`` — which acts
+       only on ``PENDING`` — leaves the entry alone this pass instead of
+       re-deriving the same smoke block. The caller persists the mutation with
+       the rest of the queue; nothing is written here.
+    2. The entry is handed to :func:`_dispatch_conflict_fixes` as a synthetic
+       ``conflict`` event, which is the SAME call the whole-queue and
+       ``--only`` paths make after a live merge attempt. Every guard it owns
+       still applies unchanged: :func:`coord.merge_queue.classify_conflict`
+       must read the error as ``rebaseable``, the #241/#784 retry cap still
+       flips a second failure to ``HUMAN_REQUIRED``, and
+       ``dispatch_conflict_fix``'s own in-flight check still refuses a
+       duplicate. Deliberately routed through that function rather than
+       calling ``dispatch_conflict_fix`` directly — a second dispatch site
+       with its own copy of those guards is how they drift apart.
+
+    Under ``--dry-run`` nothing is mutated and nothing is dispatched (the
+    revalidation itself never ran either — see :func:`_apply_revalidation`).
+    """
+    if dry_run or not conflicted:
+        return
+
+    from coord.merge_queue import CONFLICT, MergeEvent  # noqa: PLC0415
+    from coord.revalidate import compose_conflict_error  # noqa: PLC0415
+
+    events = []
+    for candidate, _result in conflicted:
+        entry = candidate.entry
+        entry.error = compose_conflict_error(entry)
+        entry.state = CONFLICT
+        click.echo(
+            f"  --revalidate: {entry.repo_name} #{entry.issue_number}: "
+            "the blocker is a CONFLICT, not a stale verdict — the branch does "
+            "not compose onto its base. Routing to the conflict-fix path "
+            "(#241) instead of re-testing (#2231)."
+        )
+        events.append(MergeEvent(entry, "conflict", entry.error))
+    _dispatch_conflict_fixes(events, config, dry_run=False)
+
+
 def _dispatch_conflict_fixes(events, config, *, dry_run: bool) -> None:
     """#241: classify any conflict events and dispatch a conflict-fix worker
     for the eligible ones.  Mutates each conflict event's ``ev.entry.state``

{code_coordinator-0.5.77 → code_coordinator-0.5.78}/coord/merge_queue.py

@@ -1906,6 +1906,67 @@ def evaluate_smoke_verdict(
     )
 
 
+def stale_smoke_conflict_reason(entry, smoke, gh_ops) -> str | None:
+    """#2231: the conflict hiding behind a stale-verdict smoke block, if any.
+
+    Gate evaluation is ordered (review → smoke → CI → …) and every gate
+    short-circuits, so an entry whose branch does not merge AT ALL never gets
+    that far: it reports "test verdict stale", which invites exactly the one
+    remedy that cannot work. Worse, the two mechanisms that could fix it are
+    both downstream of a step that never runs — #1738's auto-repair answers a
+    stale verdict (there wasn't one) and #241's conflict-fix is dispatched off
+    a failed *merge attempt* (the smoke gate returned before one happened).
+    quadraui #306/#309 spent 11h there apiece.
+
+    So: when the smoke gate is about to block on a **stale** verdict
+    specifically, ask GitHub whether the PR merges at all. A confirmed
+    ``mergeable: false`` means the stale verdict is not the blocker, and this
+    returns a reason naming the conflict — the caller turns that into a
+    ``conflict`` event, which is what arms :func:`classify_conflict` and #241.
+
+    Returns ``None`` — leaving today's stale-verdict block exactly as it was —
+    whenever the answer isn't a definite yes:
+
+    * the verdict is MISSING rather than stale (the #1640 lost-write shape,
+      deliberately out of scope here as in :func:`revalidation_candidates`);
+    * there is no PR yet, so there is nothing to ask about;
+    * ``gh_ops`` has no ``check_pr_mergeable`` — the same duck-typed probe the
+      #1877 CI-absent branch uses, and for the same reason: this function also
+      runs against a :class:`~coord.gate_snapshot.GateSnapshot` on the
+      ``/board`` read path (#1336 Invariant 1, no third-party I/O), which
+      doesn't implement it;
+    * the probe returns ``None`` (GitHub still computing mergeability) or
+      raises. An inconclusive read must never be upgraded to "conflict": that
+      would replace a recoverable staleness block with one that dispatches a
+      rebase worker at a branch which merges fine.
+
+    The wording is load-bearing in both directions — see
+    :func:`coord.revalidate.compose_conflict_error`, whose docstring explains
+    the same constraint for the local-compose variant of this fact.
+    """
+    if smoke is None or smoke.ok or smoke.kind != SMOKE_STALE:
+        return None
+    pr_number = getattr(entry, "pr_number", None)
+    if not pr_number:
+        return None
+    probe = getattr(gh_ops, "check_pr_mergeable", None)
+    if probe is None:
+        return None
+    try:
+        conflicted = probe(entry.repo_github, pr_number) is False
+    except Exception:  # noqa: BLE001 — inconclusive, never a block upgrade
+        return None
+    if not conflicted:
+        return None
+    return (
+        f"merge conflict: PR #{pr_number} does not merge into "
+        f"{entry.target_branch} — GitHub reports it as not mergeable. Its "
+        "test verdict is out of date against the current base too, but that "
+        "is downstream: no re-test can clear a branch that will not merge "
+        "(#2231)"
+    )
+
+
 @dataclass(frozen=True)
 class RevalidationCandidate:
     """One queue entry that ``coord merge --revalidate`` may re-test (#1769).
@@ -3184,6 +3245,19 @@ def _entry_gate_status(
             # write instead of re-verifying against the moved base.
             smoke = evaluate_smoke_verdict(entry, board, gh_ops)
             if not smoke.ok:
+                # #2231: name the conflict when there is one — the plan view
+                # is where an operator (and `coord drive`, via the board's
+                # `merge_reason`) reads WHY an entry is stuck, and "test
+                # verdict stale" on a branch that doesn't compose sends both
+                # of them at a remedy that cannot work. Costs one `gh` call,
+                # only for an entry already blocked on a STALE verdict, and
+                # only where a live probe exists (never on the `/board` read
+                # path — see `stale_smoke_conflict_reason`).
+                conflict_reason = stale_smoke_conflict_reason(
+                    entry, smoke, gh_ops,
+                )
+                if conflict_reason is not None:
+                    return PLAN_BLOCKED, conflict_reason
                 return PLAN_BLOCKED, smoke.short_reason
     if ci_store is not None and ci_store.is_available and entry.pr_number:
         checks = ci_store.list_checks_for_pr(entry.repo_github, entry.pr_number)
@@ -4279,6 +4353,23 @@ def process(
                         else evaluate_smoke_verdict(entry, board, gh_ops)
                     )
                     if _smoke is None or not _smoke.ok:
+                        # #2231: mirror the live path (line ~4689) — before
+                        # previewing a block on a stale verdict, check whether
+                        # the branch is actually conflicted. A dry run that
+                        # skips this reports the misleading "test verdict
+                        # stale" headline for an entry a real run (or
+                        # `--plan`) would already report/dispatch as
+                        # `conflict`, which is precisely the split-brain this
+                        # issue exists to fix.
+                        _conflict_msg = stale_smoke_conflict_reason(
+                            entry, _smoke, gh_ops,
+                        )
+                        if _conflict_msg is not None:
+                            events.append(MergeEvent(
+                                entry, "conflict",
+                                f"(dry run) {_conflict_msg}",
+                            ))
+                            continue
                         _why = (
                             "board unavailable to confirm smoke verdict"
                             if _smoke is None
@@ -4606,6 +4697,22 @@ def process(
                     None if board is None else evaluate_smoke_verdict(entry, board, gh_ops)
                 )
                 if smoke is None or not smoke.ok:
+                    # #2231: before parking this entry behind a gate whose
+                    # stated cause invites a re-test, check whether the branch
+                    # merges at all. A confirmed conflict is the real blocker
+                    # and a re-test can never clear it — emit the `conflict`
+                    # event so `_dispatch_conflict_fixes` arms #241's rebase
+                    # worker, exactly as a failed merge attempt would have.
+                    conflict_msg = stale_smoke_conflict_reason(
+                        entry, smoke, gh_ops,
+                    )
+                    if conflict_msg is not None:
+                        entry.state = CONFLICT
+                        entry.error = conflict_msg
+                        events.append(
+                            MergeEvent(entry, "conflict", conflict_msg)
+                        )
+                        continue
                     msg = (
                         "smoke test required but board unavailable to confirm verdict"
                         if smoke is None

{code_coordinator-0.5.77 → code_coordinator-0.5.78}/coord/revalidate.py

@@ -379,6 +379,15 @@ class BatchRevalidationResult:
     A red composite fills ``per_entry`` with one solo result per candidate.
     ``recorded`` then holds only the survivors' assignment ids, and
     ``culprits`` names the branches whose own run failed.
+
+    ``conflicted`` (#2231) is the subset of the culprits whose run died at
+    :data:`KIND_COMPOSE` — the branch does not merge onto its current base at
+    all. That is categorically different from every other culprit: no verdict
+    is wrong, no suite is red, and no amount of re-testing can change it. It
+    carries the *candidate* (not just its label) precisely so a caller can act
+    on it — see :func:`coord.commands.merge._dispatch_revalidation_conflicts`,
+    which turns it into #241's ``conflict-fix`` dispatch. Before #2231 this
+    diagnosis was formatted for a human and then dropped on the floor.
     """
 
     composite: RevalidationResult
@@ -386,6 +395,9 @@ class BatchRevalidationResult:
     recorded: list[str] = field(default_factory=list)
     culprits: list[str] = field(default_factory=list)
     suite_runs: int = 0
+    conflicted: list[tuple[RevalidationCandidate, RevalidationResult]] = field(
+        default_factory=list,
+    )
 
     @property
     def ok(self) -> bool:
@@ -1000,6 +1012,16 @@ def revalidate_group(
     )
 
     if composite.ok or len(candidates) == 1 or not composite.narrowable:
+        # #2231: a single-candidate composite IS that candidate's own run, so
+        # a COMPOSE failure here names it as surely as a solo run would. The
+        # N>1 case is attributed in the per-entry loop below instead — the
+        # composite stops at the FIRST branch that won't merge, which says
+        # nothing about the ones after it.
+        if (
+            len(candidates) == 1
+            and composite.kind == KIND_COMPOSE
+        ):
+            batch.conflicted.append((candidates[0], composite))
         return batch
 
     echo(
@@ -1027,6 +1049,12 @@ def revalidate_group(
         else:
             batch.culprits.append(label)
             echo(f"  --revalidate: {label} FAILS alone — {solo.reason}")
+            if solo.kind == KIND_COMPOSE:
+                # #2231: not a verdict problem at all — this branch cannot
+                # merge. Recorded structurally so the caller can dispatch
+                # #241's conflict-fix instead of leaving the entry parked
+                # behind a stale-verdict gate it can never clear.
+                batch.conflicted.append((c, solo))
 
     if not batch.culprits:
         # Every branch is green by itself, yet together they are not. That is a
@@ -1046,6 +1074,36 @@ def revalidate_group(
     return batch
 
 
+def compose_conflict_error(entry) -> str:
+    """The ``entry.error`` text for a branch that will not compose (#2231).
+
+    Deliberately worded to be classified correctly by the two consumers that
+    read merge prose rather than structured state:
+
+    * :func:`coord.merge_queue.classify_conflict` must return ``"rebaseable"``
+      — it is what decides whether ``coord merge`` dispatches #241's
+      conflict-fix worker — so the text carries the ``merge conflict`` signal
+      that function already keys on.
+    * :func:`coord.merge_queue.is_stale_smoke_reason` (and ``coord drive``'s
+      ``_SMOKE_GATE_MARKERS``) must NOT match, or the driver would read this
+      as the #1738 stale-verdict shape and spend a fix round re-testing a
+      branch that cannot merge — the exact loop #2231 reports. So the stale
+      verdict is *described* here in wording that matches none of
+      :data:`coord.merge_queue.STALE_SMOKE_MARKERS` (this module must not
+      carry a copy of those strings either — see
+      ``TestSingleStaleDetector``). ``tests/test_revalidate.py`` asserts both
+      classifications directly, since the wording is load-bearing rather than
+      cosmetic.
+    """
+    return (
+        f"merge conflict: branch {entry.branch!r} does not compose onto "
+        f"origin/{entry.target_branch} — `git merge` reported a content "
+        "conflict when --revalidate composed it against the current base, so "
+        "no test verdict (fresh or otherwise) can clear this entry until the "
+        "branch is rebased (#2231)"
+    )
+
+
 def format_batch(batch: BatchRevalidationResult) -> list[str]:
     """Operator-facing OUTCOME lines for one group's revalidation (#1715).
 
@@ -1201,6 +1259,7 @@ __all__ = [
     "BatchRevalidationResult",
     "RevalidationResult",
     "client_timeout_seconds",
+    "compose_conflict_error",
     "describe_batches",
     "describe_candidates",
     "format_batch",

{code_coordinator-0.5.77 → code_coordinator-0.5.78}/docs/OPERATING_GOTCHAS.md

@@ -907,3 +907,60 @@ these figures. Note also that #2132's classification covers 27 rows, not the
 38 the original count named — the worker could not reproduce the exact window
 boundary, and cross-validated instead against the `review_iteration=2 → 6 legs`
 figure, which matched exactly. Treat it as representative, not a literal audit.
+
+## 18. "test verdict stale" on a branch that no longer merges is the wrong headline — the conflict is (#2231)
+
+Gate evaluation is ordered (review → smoke → CI → …) and every gate
+short-circuits. So an entry whose branch does not merge **at all** never
+reaches the merge attempt: it reports `smoke gate — test verdict stale`, which
+invites the one remedy that cannot possibly work, and neither repair mechanism
+can arm behind it —
+
+- **#1738**'s stale-smoke auto-repair answers a stale verdict, and the verdict
+  was never the problem;
+- **#241**'s `conflict-fix` worker is dispatched by `coord merge` *when the
+  merge attempt fails on a rebaseable conflict* — and no merge was attempted.
+
+quadraui **#306/#309** sat 11h each in exactly that position (`mergeable:
+false, mergeable_state: dirty`; four sibling driver-test backfills all
+appending to `quadraui/tests/tui_example_driver.rs`, two stranded once the
+first two merged). A human eventually ran `coord fix <aid> --force --guidance
+"<rebase, keep both sides, push --force-with-lease>"` — which is #241's own job
+description.
+
+Two things now close that gap, both keyed to a **STALE** verdict specifically
+(a genuinely missing verdict is the #1640 lost-write shape and still escalates
+to a human, unchanged):
+
+1. **The smoke gate asks whether the branch merges before it blocks.** When
+   the gate is about to refuse on a stale verdict, `merge_queue.
+   stale_smoke_conflict_reason` probes `check_pr_mergeable`. A confirmed
+   `mergeable: false` turns the refusal into a `conflict` event —
+   `entry.state = CONFLICT`, and `_dispatch_conflict_fixes` arms the rebase
+   worker exactly as a failed merge attempt would have. `coord merge --plan`
+   and the board's `merge_reason` name the conflict too, so `coord drive`
+   stops reading the entry as re-testable. An inconclusive probe (`None` —
+   GitHub still computing — or a `gh` error, or a caller with no live probe
+   at all, e.g. the `/board` read path's `GateSnapshot`) leaves today's
+   stale-verdict block exactly as it was.
+2. **`--revalidate` acts on the conflict it finds.** It already composes each
+   branch onto the live base in a throwaway worktree, so a `git merge`
+   conflict there is a stronger fact than GitHub's `mergeable` field. That
+   verdict used to be formatted for the operator and then dropped; it is now
+   carried out structurally (`BatchRevalidationResult.conflicted`) and routed
+   through the same `_dispatch_conflict_fixes` call. The suite never runs for
+   a branch that will not compose, and no verdict is rewritten.
+
+What you should see instead of an 11-hour park:
+
+```
+  --revalidate: api #102: the blocker is a CONFLICT, not a stale verdict — the
+      branch does not compose onto its base. Routing to the conflict-fix path
+      (#241) instead of re-testing (#2231).
+  api #102: conflict-fix dispatched to laptop
+```
+
+If the conflict-fix worker itself fails, the #241/#784 retry cap still flips
+the entry to `HUMAN_REQUIRED` on the second attempt — rule #10's escape hatch
+applies from there. Nothing here loosens that: this only removes the case
+where **no** mechanism ran at all.

{code_coordinator-0.5.77 → code_coordinator-0.5.78}/tests/test_merge_queue.py

@@ -8252,3 +8252,224 @@ class TestAbandonedRunningMarkerIsStaleNotMissing:
             candidates = mq.revalidation_candidates([entry], board, _Cfg())
 
         assert [c.work_assignment_id for c in candidates] == ["w1"]
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# #2231: a conflict hiding behind a stale-verdict smoke block
+# ══════════════════════════════════════════════════════════════════════════════
+
+class TestStaleSmokeConflictProbe:
+    """#2231: gate evaluation short-circuits on the smoke gate, so an entry
+    whose branch does not merge AT ALL reports "test verdict stale" — the one
+    remedy that cannot work — and never reaches the merge attempt that would
+    have armed #241's conflict-fix.
+
+    quadraui #306/#309 sat 11h each in exactly that position: `mergeable:
+    false, mergeable_state: dirty`, four sibling branches appending to one
+    file, two of them stranded once the first two merged. `--revalidate`
+    diagnosed it perfectly and nothing acted; a human finally typed `coord fix
+    --force`, which is #241's own job description.
+    """
+
+    @staticmethod
+    def _config():
+        return TestSmokeGate._config()
+
+    @staticmethod
+    def _stale_setup(*, mergeable: bool | None):
+        """One PENDING entry whose passed verdict was staled by a base move,
+        plus a `gh` stub with a definite answer about mergeability."""
+        work = TestSmokeGate._work("w1", test_state="passed")
+        work.test_head_sha = "branch-sha-1"
+        work.test_patch_id = "patch-1"
+        work.test_base_sha = "main-sha-old"
+        board = TestSmokeGate._board(completed=[work])
+
+        entry = _q("w1", size=10, pr=100)
+        entry.branch_head_sha = "branch-sha-1"
+        entry.branch_patch_id = "patch-1"
+        entry.target_branch_head_sha = "main-sha-new"   # base moved under it
+        gh = FakeGh(mergeable_results={100: mergeable})
+        return entry, board, gh
+
+    # ── the predicate ──
+
+    def test_reason_names_the_conflict_when_github_says_not_mergeable(self) -> None:
+        entry, board, gh = self._stale_setup(mergeable=False)
+        smoke = mq.evaluate_smoke_verdict(entry, board)
+        assert smoke.kind == mq.SMOKE_STALE
+
+        reason = mq.stale_smoke_conflict_reason(entry, smoke, gh)
+
+        assert reason is not None
+        # The conflict leads; the stale verdict is named as downstream, not as
+        # the blocker (the acceptance criterion's "not (only) a stale verdict").
+        assert "merge conflict" in reason.lower()
+        assert "test verdict" in reason.lower()
+
+    def test_reason_classifies_as_rebaseable_and_not_as_stale_smoke(self) -> None:
+        """The wording is load-bearing in both directions: `classify_conflict`
+        decides whether #241 dispatches, and `is_stale_smoke_reason` decides
+        whether `coord drive` answers with a re-test. Getting either wrong
+        reproduces the bug with extra steps."""
+        entry, board, gh = self._stale_setup(mergeable=False)
+        reason = mq.stale_smoke_conflict_reason(
+            entry, mq.evaluate_smoke_verdict(entry, board), gh,
+        )
+
+        assert mq.classify_conflict(reason) == "rebaseable"
+        assert mq.is_stale_smoke_reason(reason) is False
+
+    def test_silent_when_the_pr_is_mergeable(self) -> None:
+        """Acceptance: a genuinely stale verdict on a cleanly-composing branch
+        still takes the #1738 path, unchanged."""
+        entry, board, gh = self._stale_setup(mergeable=True)
+        assert mq.stale_smoke_conflict_reason(
+            entry, mq.evaluate_smoke_verdict(entry, board), gh,
+        ) is None
+
+    def test_silent_when_mergeability_is_still_computing(self) -> None:
+        """`None` is "GitHub hasn't decided", not "conflict". Upgrading an
+        inconclusive read would point a rebase worker at a clean branch."""
+        entry, board, gh = self._stale_setup(mergeable=None)
+        assert mq.stale_smoke_conflict_reason(
+            entry, mq.evaluate_smoke_verdict(entry, board), gh,
+        ) is None
+
+    def test_silent_when_the_probe_raises(self) -> None:
+        entry, board, _gh = self._stale_setup(mergeable=False)
+
+        class _Boom:
+            def check_pr_mergeable(self, repo, number):
+                raise RuntimeError("gh exploded")
+
+        assert mq.stale_smoke_conflict_reason(
+            entry, mq.evaluate_smoke_verdict(entry, board), _Boom(),
+        ) is None
+
+    def test_silent_without_a_probe_at_all(self) -> None:
+        """The `/board` read path evaluates gates against a GateSnapshot, which
+        implements no `gh` calls (#1336 Invariant 1). Duck-typed, like the
+        #1877 CI-absent branch."""
+        entry, board, _gh = self._stale_setup(mergeable=False)
+
+        class _NoProbe:
+            pass
+
+        assert mq.stale_smoke_conflict_reason(
+            entry, mq.evaluate_smoke_verdict(entry, board), _NoProbe(),
+        ) is None
+
+    def test_silent_for_a_missing_verdict(self) -> None:
+        """SMOKE_MISSING is the #1640 lost-write shape and stays out of scope,
+        exactly as it is for `revalidation_candidates`."""
+        work = TestSmokeGate._work("w1", test_state=None)
+        board = TestSmokeGate._board(completed=[work])
+        entry = _q("w1", pr=100)
+        smoke = mq.evaluate_smoke_verdict(entry, board)
+
+        assert smoke.kind == mq.SMOKE_MISSING
+        assert mq.stale_smoke_conflict_reason(
+            entry, smoke, FakeGh(mergeable_results={100: False}),
+        ) is None
+
+    def test_silent_before_a_pr_exists(self) -> None:
+        entry, board, gh = self._stale_setup(mergeable=False)
+        entry.pr_number = None
+        assert mq.stale_smoke_conflict_reason(
+            entry, mq.evaluate_smoke_verdict(entry, board), gh,
+        ) is None
+
+    # ── process(): the event that arms #241 ──
+
+    def test_process_emits_a_conflict_event_not_smoke_required(self) -> None:
+        """The headline: the entry that used to park at PENDING/"stale" now
+        parks at CONFLICT with a `conflict` event — which is precisely what
+        `coord.commands.merge._dispatch_conflict_fixes` consumes."""
+        entry, board, gh = self._stale_setup(mergeable=False)
+        events = process([entry], gh, config=self._config(), board=board)
+
+        kinds = [e.kind for e in events]
+        assert "conflict" in kinds
+        assert "smoke_required" not in kinds
+        assert "merged" not in kinds
+        assert gh.merge_calls == []
+        assert entry.state == CONFLICT
+        assert mq.classify_conflict(entry.error) == "rebaseable"
+
+    def test_process_still_blocks_on_smoke_when_the_branch_is_clean(self) -> None:
+        entry, board, gh = self._stale_setup(mergeable=True)
+        events = process([entry], gh, config=self._config(), board=board)
+
+        kinds = [e.kind for e in events]
+        assert "smoke_required" in kinds
+        assert "conflict" not in kinds
+        assert entry.state == PENDING
+        assert mq.is_stale_smoke_reason(entry.error) is True
+
+    def test_process_unchanged_when_gh_reports_nothing(self) -> None:
+        """Every pre-#2231 test uses a `gh` stub whose `check_pr_mergeable`
+        answers `None`; none of them may change behaviour."""
+        entry, board, _gh = self._stale_setup(mergeable=None)
+        events = process([entry], FakeGh(), config=self._config(), board=board)
+
+        assert [e.kind for e in events].count("smoke_required") == 1
+        assert entry.state == PENDING
+
+    # ── process(dry_run=True): the preview must not disagree with --plan ──
+
+    def test_dry_run_reports_conflict_not_smoke_required(self) -> None:
+        """Review finding on iteration 1: the smoke gate's own `--dry-run`
+        preview block sat right next to the CI gate's #1877 dry-run conflict
+        check but wasn't updated for #2231, so `coord merge --dry-run`
+        (without `--revalidate`) kept printing the stale-verdict headline for
+        an entry `--plan`/a real run both correctly report as `conflict` —
+        the exact "two surfaces answer the same question differently"
+        split-brain this issue exists to fix."""
+        entry, board, gh = self._stale_setup(mergeable=False)
+        events = process([entry], gh, config=self._config(), board=board, dry_run=True)
+
+        kinds = [e.kind for e in events]
+        assert "conflict" in kinds
+        assert "smoke_required" not in kinds
+        assert gh.merge_calls == []
+        # dry-run never mutates state
+        assert entry.state == PENDING
+        conflict_event = next(e for e in events if e.kind == "conflict")
+        assert mq.classify_conflict(conflict_event.message) == "rebaseable"
+
+    def test_dry_run_still_shows_smoke_required_when_the_branch_is_clean(self) -> None:
+        """Acceptance: a genuinely stale verdict on a cleanly-composing
+        branch still takes the #1738 path, unchanged — including in the
+        dry-run preview."""
+        entry, board, gh = self._stale_setup(mergeable=True)
+        events = process([entry], gh, config=self._config(), board=board, dry_run=True)
+
+        kinds = [e.kind for e in events]
+        assert "smoke_required" in kinds
+        assert "conflict" not in kinds
+        assert entry.state == PENDING
+
+    # ── _entry_gate_status(): what the plan/board reports ──
+
+    def test_plan_reason_names_the_conflict(self) -> None:
+        """Acceptance: "An entry whose branch does not compose onto its base
+        reports conflict as its blocking reason, not (only) a stale verdict."
+        """
+        entry, board, gh = self._stale_setup(mergeable=False)
+        status, reason = mq.entry_gate_status(
+            entry, board, self._config(), None, gh,
+        )
+
+        assert status == mq.PLAN_BLOCKED
+        assert "merge conflict" in reason.lower()
+        assert mq.is_stale_smoke_reason(reason) is False
+
+    def test_plan_reason_unchanged_for_a_clean_branch(self) -> None:
+        entry, board, gh = self._stale_setup(mergeable=True)
+        status, reason = mq.entry_gate_status(
+            entry, board, self._config(), None, gh,
+        )
+
+        assert status == mq.PLAN_BLOCKED
+        assert mq.is_stale_smoke_reason(reason) is True