code-coordinator 0.5.125__tar.gz → 0.5.126__tar.gz

{code_coordinator-0.5.125 → code_coordinator-0.5.126}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.125",
+  "tag": "0.5.126",
   "distance": 0,
-  "node": "g45b284e5f4bdc6047cbd9db9e0a0d4f1c11ca154",
+  "node": "gd69faff040adaad7a346ab65c483934e1eca4c66",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-17"

{code_coordinator-0.5.125 → code_coordinator-0.5.126}/coord/block_log.py

@@ -70,7 +70,9 @@ from typing import Any
 
 from coord.drive_queue import (
     STATE_BLOCKED,
+    STATE_DONE,
     STATE_PARKED,
+    STATE_WAITING,
     QueueEntry,
     TickPlan,
 )
@@ -107,6 +109,8 @@ __all__ = [
     "episodes",
     "is_by_design",
     "log_location",
+    "merge_only_event",
+    "merge_only_fallback_event",
     "operator_resolution_event",
     "plan_events",
     "read_events",
@@ -221,6 +225,20 @@ _LANDED_CAUSE = (
     "already-landed — the work merged or closed while the entry sat in this "
     "state, so the stated reason had outlived the thing it described"
 )
+#: #2350: distinct from `_LANDED_CAUSE` on purpose — that one means "the entry
+#: sat here and something ELSE finished it while nobody was looking" (a human,
+#: an unrelated branch merge, `coord reconcile-merges`); this one means the
+#: QUEUE ITSELF, this same tick, ran `coord merge --only` and landed it —
+#: see `coord.commands.drive_queue._run_merge_only_candidates`'s success
+#: branch, the ONLY writer of the `outcome == "merged"` `_resolve_record`
+#: reads to pick this cause. Conflating the two into one `auto-released`-style
+#: bucket is exactly what #2350 was written to stop: #2235's corpus needs to
+#: tell "the mechanism did this" apart from "the state flipped and something
+#: unrelated did it".
+_AUTO_MERGED_CAUSE = (
+    "auto-merged — the queue completed the merge directly from the tick "
+    "(#2350), Test/Review already satisfied; Merge was the only gate left"
+)
 _OPERATOR_CAUSE = (
     "operator-intervened — no automatic release fired; a human cleared it by "
     "hand, and what they actually fixed is NOT recorded here"
@@ -405,7 +423,17 @@ def _resolve_record(
     now: float,
     outcome: str,
 ) -> dict[str, Any]:
-    if outcome == "done" or new_state == "done":
+    if outcome == "merged":
+        # #2350: checked BEFORE the "done" branch below — a successful
+        # Merge-only fast-path attempt also lands `new_state == "done"` (it
+        # skips the `waiting`/relaunch cycle entirely), so without this
+        # ordering the generic landed check would win the match and this
+        # episode would be indistinguishable from "something else merged it
+        # while it sat here" — exactly the conflation #2350 exists to split
+        # out of #2230's `auto-released`/#2055's `already-landed`.
+        true_cause, human = _AUTO_MERGED_CAUSE, False
+        resolution = "auto_merged"
+    elif outcome == "done" or new_state == "done":
         true_cause, human = _LANDED_CAUSE, False
         resolution = "landed"
     elif outcome == "resumed":
@@ -471,6 +499,81 @@ def enter_event(
     return record
 
 
+def merge_only_event(
+    entry: QueueEntry,
+    *,
+    host: str = "",
+    now: float | None = None,
+) -> dict[str, Any]:
+    """The ``resolve`` record for #2350's Merge-only fast path.
+
+    The other caller-constructed record besides :func:`enter_event`, and for
+    the identical structural reason: the transition happens OUTSIDE
+    :func:`plan_events`'s view. A `merge_only` :class:`~coord.drive_queue.
+    Reconcile` deliberately writes no `state` (see its docstring), so
+    `plan.writes()` never carries the `parked`/`blocked` → `done` move this
+    function records — it only happens once the shell's own live
+    ``coord merge --only`` attempt reports success, strictly after
+    ``_apply_writes`` has already run for the rest of the tick. *entry* is
+    the PRE-tick snapshot (its ``state`` is still `parked`/`blocked`); the
+    entry has already landed by the time this is called, so `new_state` is
+    unconditionally :data:`~coord.drive_queue.STATE_DONE`.
+    """
+    stamp = time.time() if now is None else now
+    record = _resolve_record(
+        entry.key,
+        entry.state,
+        STATE_DONE,
+        "",
+        entry,
+        host=host,
+        now=stamp,
+        outcome="merged",
+    )
+    record["source"] = "tick"
+    return record
+
+
+def merge_only_fallback_event(
+    entry: QueueEntry,
+    *,
+    reason: str,
+    host: str = "",
+    now: float | None = None,
+) -> dict[str, Any]:
+    """The ``resolve`` record for #2350's Merge-only fast path RACE case:
+    the live gate read clear enough to attempt a direct merge, but the
+    attempt itself did not confirm a landed merge, so
+    ``coord.commands.drive_queue._run_merge_only_candidates`` falls back to
+    exactly the pre-#2350 ``resumed`` shape (``STATE_WAITING``) — OUTSIDE
+    ``plan.writes()``, the same reason :func:`merge_only_event` exists for
+    the success case: without this, the episode :func:`plan_events` already
+    opened for *entry* would never see a matching close, and
+    ``coord drive-queue block-log`` would show it stuck ``(unresolved)``
+    forever even though the entry plainly left `parked`/`blocked` this tick.
+
+    Classified as an ordinary ``resumed`` outcome — not a new #2350 cause —
+    on purpose: unlike the success case, this genuinely IS "state flipped,
+    cause a plain gate re-clear" (:func:`_resume_cause`'s fallback,
+    ``auto-released``), the same honest non-answer a bare board-signal
+    resume already gets. #2350's distinct cause is reserved for the tick
+    actually landing the merge itself.
+    """
+    stamp = time.time() if now is None else now
+    record = _resolve_record(
+        entry.key,
+        entry.state,
+        STATE_WAITING,
+        reason,
+        entry,
+        host=host,
+        now=stamp,
+        outcome="resumed",
+    )
+    record["source"] = "tick"
+    return record
+
+
 def operator_resolution_event(
     entry: QueueEntry,
     *,

{code_coordinator-0.5.125 → code_coordinator-0.5.126}/coord/commands/drive_queue.py

@@ -53,6 +53,7 @@ from coord.drive_queue import (
     QUEUE_ALERT_STAGE,
     RESUME_PROBE_TIMEOUT_SECONDS,
     STATE_BLOCKED,
+    STATE_DONE,
     STATE_FAILED,
     STATE_PARKED,
     STATE_RUNNING,
@@ -98,6 +99,33 @@ from coord.overlap_predict import (
 # budget.
 _LAUNCH_TIMEOUT_SECONDS = 120.0
 
+# Wall-clock ceiling for the tick's own `coord merge --only` attempt
+# (#2350's fast path, `_run_merge_only_candidates`).  Deliberately its OWN
+# constant, not a reuse of `_LAUNCH_TIMEOUT_SECONDS` above: that one is
+# scoped to a `coord drive --tmux` launch, which only ever blocks on #1606's
+# bounded liveness check, so 120s is already generous there.  `coord merge
+# --only` is a different animal — elsewhere in the codebase
+# (`Driver._spawn` in `coord/drive.py`) the SAME subcommand runs under NO
+# subprocess timeout at all, nested inside up to a 1800s merge-lock
+# acquisition, i.e. the existing precedent treats its runtime as
+# unbounded/long, not launch-fast.  This call site does still want a
+# backstop — unlike `_spawn`'s fire-and-forget, this one runs synchronously
+# inside `drive_queue_tick`, in a loop over every `merge_only` candidate
+# this tick found (typically 0-2, see `_fetch_merge_only_ready`, but not
+# hard-capped), and a wedge here stalls the whole tick — so it gets a wider
+# ceiling than the launch check instead of no ceiling at all, without going
+# fully unbounded: `coord-drive-queue.service` (the deployed timer unit)
+# gives the ENTIRE `coord drive-queue tick` invocation only 300s
+# (`TimeoutStartSec`) before systemd kills it outright, which is a harder
+# and less graceful stop than this subprocess's own SIGKILL. 240s leaves
+# room for one slow `gh pr merge`/git round trip on a bad network day
+# without letting a single candidate alone consume the whole tick's outer
+# budget (this PR's invocation never passes `--revalidate`, so
+# `wait_for_ci_settle`'s up to 360s doesn't even apply today, but the argv
+# could grow that flag later — revisit this ceiling together with
+# `coord-drive-queue.service`'s `TimeoutStartSec` if it does).
+_MERGE_ONLY_TIMEOUT_SECONDS = 240.0
+
 # Counts are rendered in pipeline order, not alphabetically, so
 # `coord drive-queue status` reads as "1 running · 1 waiting". `parked`
 # (#1891) sits between `waiting` and `blocked` — closer to "nothing wrong"
@@ -2037,6 +2065,82 @@ def _fetch_live_blocked_gate(
     return overrides
 
 
+def _fetch_merge_only_ready(
+    entries: list,
+    live_ci_gate: Mapping[str, bool],
+    live_blocked_gate: Mapping[str, bool],
+) -> dict[str, bool]:
+    """``{entry_key: True}`` for #2350's Merge-only fast path: every entry
+    THIS tick's live gate re-check just found clear — a `parked` entry with
+    ``live_ci_gate[key] is False``, a `blocked` one with
+    ``live_blocked_gate[key] is False`` — whose board-recorded pipeline
+    state ALSO shows Test already `passed` and Review already `approve`,
+    meaning Merge was the only gate that was ever still shut.
+
+    Scoped to exactly the entries about to reconcile `resumed` this tick —
+    typically 0-2, the same bound :func:`_fetch_live_ci_gate`/
+    :func:`_fetch_live_blocked_gate` already keep — so this never re-derives
+    a gate reading of its own (that authority stays with *live_ci_gate*/
+    *live_blocked_gate*, computed moments earlier in the same tick): it only
+    adds two board-only reads (:func:`coord.merge_queue.has_approved_review`,
+    :func:`coord.merge_queue.has_passed_test`) against the SAME local board
+    those callers already loaded. Almost always cheap and I/O-free — but not
+    unconditionally: ``has_approved_review`` can fall through to
+    ``scan_approved_reviews``'s ``_backfill_branch_patch_id``, which does a
+    live ``gh api compare`` round trip via *_gh_ops* when a stale-SHA review
+    needs its patch-id computed on demand. That path is exception-guarded
+    below and fails closed to the pre-#2350 `resumed` path like everything
+    else here, so it is not unsafe — just not the zero-I/O read the rest of
+    this docstring describes.
+
+    Takes no *config_path*, unlike both siblings: neither board-only read
+    needs a :class:`~coord.config.Config` (no ``ci_store``, no live gate
+    re-derivation), so there is nothing to load here.
+
+    Same fail-open-per-entry, fail-closed-overall contract as its siblings:
+    a key ABSENT from the result (no queue row, an unreadable board or
+    merge queue, any exception) simply takes the pre-#2350 `resumed` path —
+    never a wrongly skipped relaunch.
+    """
+    targets = [
+        e for e in entries
+        if (e.state == STATE_PARKED and live_ci_gate.get(e.key) is False)
+        or (e.state == STATE_BLOCKED and live_blocked_gate.get(e.key) is False)
+    ]
+    if not targets:
+        return {}
+
+    from coord.board_service import resolve as resolve_board_service  # noqa: PLC0415
+
+    if resolve_board_service() is not None:
+        return {}
+
+    try:
+        from coord import github_ops as _gh_ops  # noqa: PLC0415
+        from coord import merge_queue as _mq  # noqa: PLC0415
+        from coord.state import load_board as _load_board  # noqa: PLC0415
+
+        board = _load_board()
+        queue_by_key = {
+            entry_key(q.repo_name, q.issue_number): q for q in _mq.load_queue()
+        }
+    except Exception:  # noqa: BLE001 — see the fail-soft note above
+        return {}
+
+    ready: dict[str, bool] = {}
+    for e in targets:
+        q = queue_by_key.get(e.key)
+        if q is None:
+            continue
+        try:
+            ready[e.key] = _mq.has_approved_review(
+                q, board, _gh_ops
+            ) and _mq.has_passed_test(q, board)
+        except Exception:  # noqa: BLE001 — leave this one entry to the ordinary path
+            continue
+    return ready
+
+
 def _launch_argv(entry: QueueEntry, config_path: Path | None) -> list[str]:
     """The ``coord drive --tmux`` argv for *entry*.
 
@@ -2068,6 +2172,136 @@ def _launch_argv(entry: QueueEntry, config_path: Path | None) -> list[str]:
     return argv
 
 
+def _merge_only_argv(entry: QueueEntry, config_path: Path | None) -> list[str]:
+    """The ``coord merge --only <repo>#<issue>`` argv for *entry* (#2350).
+
+    Mirrors :func:`_launch_argv`'s exact shape — same ``coord_argv()`` base,
+    same ``--config`` passthrough — for the direct-merge fast path instead
+    of a fresh drive session. ``--only`` accepts the durable ``repo#issue``
+    form (#1477), which is exactly ``entry.key``, so no assignment_id lookup
+    is needed here.
+    """
+    from coord.drive import coord_argv  # noqa: PLC0415
+
+    argv = coord_argv() + ["merge", "--only", entry.key]
+    if config_path:
+        argv += ["--config", str(config_path)]
+    return argv
+
+
+def _merge_only_landed(entry: QueueEntry) -> bool:
+    """Did *entry* actually MERGE, per the merge-queue's own row — the one
+    ground truth ``coord merge --only``'s exit code alone cannot supply.
+
+    #2350: a ``--only`` run against an already-PENDING entry exits 0
+    whether the attempt landed it, left it blocked on a gate, or routed it
+    into a conflict-fix — see ``coord.commands.merge``'s ``--only`` handler,
+    which prints a summary and returns unconditionally once ``process()``
+    has run. Exit code alone is therefore not evidence of a landed merge;
+    the queue row's own resulting state is.
+    """
+    from coord import merge_queue as _mq  # noqa: PLC0415
+
+    try:
+        rows = _mq.load_queue()
+    except Exception:  # noqa: BLE001 — unreadable queue is not proof of a landed merge
+        return False
+    for q in rows:
+        if entry_key(q.repo_name, q.issue_number) == entry.key:
+            return q.state == _mq.MERGED
+    return False
+
+
+def _run_merge_only_candidates(plan: TickPlan, config_path: Path | None) -> None:
+    """#2350: attempt ``coord merge --only`` directly, THIS tick, for every
+    entry :func:`coord.drive_queue.plan_tick` marked ``merge_only`` — no
+    relaunch, no capacity slot spent. Called AFTER ``_apply_writes(plan)``,
+    same posture as the launch subprocess below it: the entry's real next
+    state is decided from the live outcome of THIS attempt, not from
+    anything ``plan_tick`` could have known when it returned — see
+    :class:`~coord.drive_queue.Reconcile`'s ``merge_only`` outcome for why
+    that Reconcile itself writes nothing.
+
+    On success (the queue's own row now reads ``MERGED`` — see
+    :func:`_merge_only_landed`): writes ``STATE_DONE`` directly, skipping
+    the ``waiting``/relaunch cycle a NEXT tick's ordinary ``landed``
+    re-check would otherwise need, and records a distinct #2350 block-log
+    ``resolve`` (:func:`coord.block_log.merge_only_event`) so #2235's corpus
+    can tell "the queue itself finished this" apart from "the state flipped
+    and something else finished it" (``already-landed``/``auto-released``).
+
+    On failure (the gate flipped shut again between the read and the
+    attempt — a genuine race, not the common case; or the attempt itself hit
+    something a single bounded try cannot resolve): falls back to EXACTLY
+    the pre-#2350 ``resumed`` shape — ``STATE_WAITING``, ``attempts`` reset
+    to 0, ``resumes`` bumped for a ``blocked``-origin entry (mirroring
+    ``_reconcile_blocked``'s own formula, so the #2230 oscillation ceiling
+    still sees every chance this entry got, fast-path or not) — never worse
+    than the status quo, and never a `coord drive --tmux` launch attempt
+    spent retrying a race this bounded attempt already ruled out.
+    """
+    if not plan.merge_only:
+        return
+
+    from coord.block_log import merge_only_event, merge_only_fallback_event  # noqa: PLC0415
+    from coord.state import update_drive_queue_entry  # noqa: PLC0415
+
+    for target in plan.merge_only:
+        argv = _merge_only_argv(target, config_path)
+        try:
+            result = subprocess.run(  # noqa: S603 — argv built from coord_argv + typed row
+                argv,
+                capture_output=True,
+                text=True,
+                timeout=_MERGE_ONLY_TIMEOUT_SECONDS,
+            )
+            returncode = result.returncode
+            detail = (result.stderr or result.stdout or "").strip().splitlines()
+            message = detail[-1] if detail else ""
+        except (subprocess.SubprocessError, OSError) as exc:
+            returncode, message = 1, str(exc)
+
+        if returncode == 0 and _merge_only_landed(target):
+            update_drive_queue_entry(
+                target.repo,
+                target.issue,
+                state=STATE_DONE,
+                last_reason=(
+                    "merged directly from the tick — Test/Review were "
+                    "already satisfied, Merge was the only gate left (#2350)"
+                ),
+                session_name=None,
+            )
+            _record_block_log([merge_only_event(target, host=_local_host_id())])
+            click.echo(f"merge-only: {target.key} merged directly from the tick")
+            continue
+
+        # #2350: the race case — fall back to exactly today's `resumed`
+        # shape, never a consumed drive-queue attempt (this was never a
+        # `coord drive --tmux` launch).
+        reason = f"merge-only attempt for {target.key} did not land it this tick"
+        if message:
+            reason += f" ({message})"
+        reason += " — falling back to an ordinary relaunch (#2350)"
+        updates: dict[str, Any] = {
+            "state": STATE_WAITING,
+            "attempts": 0,
+            "last_reason": reason,
+        }
+        if target.state == STATE_BLOCKED:
+            updates["resumes"] = target.resumes + 1
+        update_drive_queue_entry(target.repo, target.issue, **updates)
+        # #2350: this write bypassed `plan.writes()` entirely, so the
+        # `plan_events` call below (keyed off the ORIGINAL plan) can never
+        # see it — without recording it here, the episode `plan_events`
+        # already opened for `target` when it first went `parked`/`blocked`
+        # would never see a matching close.
+        _record_block_log(
+            [merge_only_fallback_event(target, reason=reason, host=_local_host_id())]
+        )
+        click.echo(f"merge-only: {reason}")
+
+
 def _run_resume_probe(entry: QueueEntry) -> ProbeResult:
     """Run one entry's ``--resume-when`` probe with a hard timeout.
 
@@ -2219,7 +2453,8 @@ def _requeue_command(entry: QueueEntry | None, key: str) -> str:
         "Update the queue's view of reality and launch nothing (#2110). "
         "Every `running` entry is still checked against the board "
         "(done/blocked/parked/retry, exactly as a normal tick would), but no "
-        "new `coord drive` is ever started this run — equivalent to "
+        "new `coord drive` is ever started this run, and no `coord merge "
+        "--only` fast-path attempt (#2350) runs either — equivalent to "
         "`--max-parallel 0`. This is the missing primitive for the "
         "stop-the-timer-to-roll-the-fleet sequence: with the timer stopped, "
         "nothing reconciles a finished drive's `running` row, and that stale "
@@ -2367,6 +2602,15 @@ def drive_queue_tick(
         # landable for most of that window, and nothing ever looked again).
         live_blocked_gate = _fetch_live_blocked_gate(entries, config_path)
 
+        # #2350: for every entry the two live re-checks above just found
+        # clear, also confirm — from the board's own recorded Test/Review
+        # verdicts — that Merge was the only gate ever still shut, so
+        # `plan_tick` can attempt it directly this tick instead of spending
+        # a relaunch. See `_fetch_merge_only_ready`'s docstring.
+        merge_only_ready = _fetch_merge_only_ready(
+            entries, live_ci_gate, live_blocked_gate
+        )
+
         # #2101: release cordons. THIS is the hole the issue names — the
         # queue's launcher had zero pause awareness (`coord/drive.py` checks
         # pause only when routing a *worker*), so a cordoned host kept getting
@@ -2409,6 +2653,7 @@ def drive_queue_tick(
             live_ci_gate_reason=live_ci_gate_reason,
             live_blocked_gate=live_blocked_gate,
             editable_drift=editable_drift,
+            merge_only_ready=merge_only_ready,
         )
 
         if reconcile_only:
@@ -2427,6 +2672,16 @@ def drive_queue_tick(
 
         _apply_writes(plan)
 
+        # #2350: attempt the direct merges `plan_tick` marked `merge_only`,
+        # right after the rest of the plan's writes have landed. Skipped
+        # under `--reconcile-only` (also forced by `--max-parallel 0`, see
+        # `effective_capacity` above) — that mode's whole contract is
+        # "update queue state, launch nothing", and a live `coord merge
+        # --only` attempt is exactly the external action it promises not to
+        # take, same posture as the launch subprocess further down.
+        if not reconcile_only:
+            _run_merge_only_candidates(plan, config_path)
+
         # #2235 Phase 0: record every entry this tick moved INTO or OUT OF
         # `blocked`/`parked`, with the reason the queue stated and — for a
         # release — what the release itself reveals about the true cause.

{code_coordinator-0.5.125 → code_coordinator-0.5.126}/coord/drive_queue.py

@@ -1088,10 +1088,23 @@ class Reconcile:
       startup grace window.  Costs one attempt.
     * ``exhausted`` — as ``retry``, but out of attempts; pairs with a
       :class:`Blocked`.
+    * ``merge_only`` — #2350: a ``parked``/``blocked`` entry whose live gate
+      re-check reads clear AND whose board-recorded Test/Review verdicts
+      already show Merge is the only remaining gate (*merge_only_ready*).
+      Writes NO state here — unlike ``resumed``, this does not fall through
+      to step 4's launch walk at all. The key is instead carried on
+      :attr:`TickPlan.merge_only` for the shell to attempt a direct
+      ``coord merge --only`` from THIS tick, no relaunch, no capacity slot
+      spent. The shell decides the entry's real next state from the live
+      outcome of that attempt (straight to ``done`` on success; falls back
+      to exactly today's ``resumed``-shaped ``STATE_WAITING`` on failure —
+      see :func:`coord.commands.drive_queue._run_merge_only_candidates`),
+      which is why this Reconcile's own ``updates`` stays empty: neither
+      outcome is knowable at the moment :func:`plan_tick` returns.
     """
 
     key: str
-    outcome: str  # alive | starting | held | unknown | done | refused | parked | retry | exhausted
+    outcome: str  # alive | starting | held | unknown | done | refused | parked | retry | exhausted | merge_only
     reason: str
     occupies: bool = False
     updates: Mapping[str, Any] = field(default_factory=dict)
@@ -1243,6 +1256,11 @@ class TickPlan:
 
     reconciles: tuple[Reconcile, ...] = ()
     launch: QueueEntry | None = None
+    # #2350: entries the walk above marked ``merge_only`` — the shell attempts
+    # `coord merge --only` for each directly, no relaunch, no capacity spent.
+    # Unlike `launch` (one slot, one entry), every eligible entry gets one:
+    # nothing here competes for capacity, so there is nothing to ration.
+    merge_only: tuple[QueueEntry, ...] = ()
     blocked: tuple[Blocked, ...] = ()
     deferrals: tuple[Deferral, ...] = ()
     holds: tuple[Hold, ...] = ()
@@ -2226,6 +2244,7 @@ def _reconcile_blocked(
     entry: QueueEntry,
     facts: IssueFacts,
     live_blocked_gate: Mapping[str, bool] | None,
+    merge_only_ready: Mapping[str, bool] | None = None,
 ) -> Reconcile | None:
     """Re-examine ONE `blocked` entry against the current gate reading.
 
@@ -2252,6 +2271,17 @@ def _reconcile_blocked(
     issue's explicit ask), which is also what feeds the oscillation signal
     into `coord drive-queue list`/`status` without inventing a second alert
     channel for it.
+
+    *merge_only_ready* (#2350) is consulted only once a confirmed-clear
+    reading has already survived the oscillation-ceiling check above — the
+    ceiling's "stop giving this entry more chances" verdict applies whether
+    the next chance would have been a relaunch or a direct merge attempt.
+    A ``True`` entry there means Merge is the ONLY gate left (the board's
+    own recorded Test/Review verdicts already show `passed`/`approve` — see
+    :func:`coord.commands.drive_queue._fetch_merge_only_ready`), so this
+    returns a ``merge_only`` :class:`Reconcile` instead of the ordinary
+    ``resumed`` one below — see that outcome's docstring on :class:`Reconcile`
+    for why it writes no state here.
     """
     if is_permanent_block_reason(entry.last_reason):
         return None
@@ -2276,6 +2306,16 @@ def _reconcile_blocked(
             updates={"last_reason": reason},
         )
 
+    if (merge_only_ready or {}).get(entry.key):
+        reason = (
+            f"{entry.key}'s merge gate reads clear now "
+            f"({facts.merge_gate_reason or facts.merge_ci_pending_reason or 'no gate objection'}) "
+            "and the board already shows Test passed and Review approved — "
+            "attempting `coord merge --only` directly from this tick instead "
+            "of relaunching a fresh drive session (#2350)"
+        )
+        return Reconcile(entry.key, "merge_only", reason, occupies=False)
+
     reason = (
         f"{entry.key}'s merge gate reads clear now "
         f"({facts.merge_gate_reason or facts.merge_ci_pending_reason or 'no gate objection'}) "
@@ -2556,6 +2596,7 @@ def plan_tick(
     live_ci_gate_reason: Mapping[str, str] | None = None,
     live_blocked_gate: Mapping[str, bool] | None = None,
     editable_drift: tuple[str, str] | None = None,
+    merge_only_ready: Mapping[str, bool] | None = None,
 ) -> TickPlan:
     """Decide one tick.  Pure; the caller executes the returned plan.
 
@@ -2686,6 +2727,22 @@ def plan_tick(
     beats the cached board's `IssueFacts.merge_gate_status`; absent falls
     through to it. See :func:`_blocked_gate_reading`.
 
+    *merge_only_ready* (#2350) maps a key to whether — GIVEN this SAME tick
+    already found its live gate clear (*live_ci_gate* reading `False` for a
+    `parked` entry, *live_blocked_gate* reading `False` for a `blocked` one)
+    — the board's own recorded pipeline state ALSO shows Test `passed` and
+    Review `approve` already, i.e. Merge is the only gate that was ever
+    still shut. `True` there swaps what would have been today's `resumed`
+    reconcile (write `STATE_WAITING`, compete for next tick's launch slot)
+    for a `merge_only` one instead (write nothing; the shell attempts
+    `coord merge --only` directly, this tick, no relaunch, no capacity
+    spent) — see :class:`Reconcile`'s `merge_only` outcome and
+    :func:`coord.commands.drive_queue._fetch_merge_only_ready` for how the
+    shell computes it. A key ABSENT or `False` changes nothing: the entry
+    takes exactly the pre-#2350 `resumed` path, so an unreadable board, a
+    missing PR, or Test/Review genuinely not both satisfied yet all degrade
+    to today's behaviour, never to a wrongly-skipped relaunch.
+
     The algorithm, from #1754, plus #1757's step 2, #1891's step 1b, #2055's
     extension of it, and #2230's further extension for `blocked`:
 
@@ -2787,6 +2844,9 @@ def plan_tick(
     reconciles: list[Reconcile] = []
     blocked: list[Blocked] = []
     deferrals: list[Deferral] = []
+    # #2350: entries this tick decided to attempt `coord merge --only` on
+    # directly rather than relaunch — see `Reconcile`'s `merge_only` outcome.
+    merge_only_candidates: list[QueueEntry] = []
     occupied = 0
     # #1972: the same count, keyed by repo.  Populated from the SAME
     # `reconcile.occupies` verdict as `occupied` above — one source of truth, so
@@ -2890,9 +2950,16 @@ def plan_tick(
             # gave-up entry via the CI-pending resume was explicitly not the
             # #2055 fix and is not this one either; see
             # :func:`_reconcile_blocked` for the full decision.
-            blocked_reconcile = _reconcile_blocked(entry, facts, live_blocked_gate)
+            blocked_reconcile = _reconcile_blocked(
+                entry, facts, live_blocked_gate, merge_only_ready
+            )
             if blocked_reconcile is not None:
                 reconciles.append(blocked_reconcile)
+                if blocked_reconcile.outcome == "merge_only":
+                    # #2350: no state write — the shell decides the entry's
+                    # real next state from the live merge attempt's outcome.
+                    merge_only_candidates.append(entry)
+                    continue
                 new_state = blocked_reconcile.updates.get("state")
                 if new_state:
                     states[entry.key] = str(new_state)
@@ -2954,6 +3021,24 @@ def plan_tick(
                         )
                     )
                 continue
+            if (merge_only_ready or {}).get(entry.key):
+                # #2350: Merge is the only gate left — the board already
+                # shows Test passed and Review approved. Attempt the merge
+                # directly this tick instead of paying for a relaunch; see
+                # `Reconcile`'s `merge_only` outcome for why no state is
+                # written here.
+                reason = (
+                    f"live re-check of {entry.key}'s gate this tick reads "
+                    "READY (coord merge --plan agrees) and the board already "
+                    "shows Test passed and Review approved — attempting "
+                    "`coord merge --only` directly from this tick instead of "
+                    "relaunching a fresh drive session (#2350)"
+                )
+                reconciles.append(
+                    Reconcile(entry.key, "merge_only", reason, occupies=False)
+                )
+                merge_only_candidates.append(entry)
+                continue
             reason = (
                 f"live re-check of {entry.key}'s gate this tick reads READY "
                 "(coord merge --plan agrees) — resuming from parked without "
@@ -3099,6 +3184,11 @@ def plan_tick(
         # report the reading that `occupied` was taken from.
         "repo_occupied": dict(repo_occupied),
         "repo_capacity": repo_capacity,
+        # #2350: fixed by the time reconciliation (steps 1/1b) finishes —
+        # nothing below this point (holds, capacity, the launch walk) ever
+        # adds to it — so, unlike `reconciles`, every return site can share
+        # this one tuple via `**plan_base` instead of re-taking it fresh.
+        "merge_only": tuple(merge_only_candidates),
     }
 
     # #2186: every currently-closed gate, keyed by the entry it was declared
@@ -3535,6 +3625,11 @@ def render_plan(plan: TickPlan, *, dry_run: bool = False) -> list[str]:
         )
     for item in plan.reconciles:
         lines.append(f"  reconcile {item.key}: {item.outcome} — {item.reason}")
+    # #2350: printed right after the reconciles, same reasoning as the hold
+    # line below — "merge_only" and "attempting the merge directly" are one
+    # thought, not two lines an operator has to correlate by key.
+    for item in plan.merge_only:
+        lines.append(f"  {prefix}merge --only {item.key}")
     # #1757: the gate line goes directly under its reconcile, because "1753
     # done" immediately followed by "and therefore nothing launches" is the
     # sentence an operator reading a timer log needs to read as one thought.