code-coordinator 0.5.531__tar.gz → 0.5.533__tar.gz

{code_coordinator-0.5.531 → code_coordinator-0.5.533}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.531
+Version: 0.5.533
 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.533/code_coordinator.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.533",
+  "distance": 0,
+  "node": "g3ea458dbd41140d5bf4dca2f931046590f1b3fb0",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-30"
+}

{code_coordinator-0.5.531 → code_coordinator-0.5.533}/coord/audit.py

@@ -40,6 +40,7 @@ __all__ = [
     "query_audit_log",
     "audit_lock_contention_losses",
     "flush_lock_contention_summary",
+    "sweep_operational_retention",
 ]
 
 # Valid values are documented in the issue but not enforced here — callers
@@ -276,9 +277,14 @@ def _maybe_trim(conn) -> None:
     """Opportunistic cap: when ``audit.max_rows`` is set (> 0), delete the
     oldest rows past that count after every insert.
 
-    Default (``max_rows=0``) is unlimited — this is a no-op in the common
-    case.  Config is read via :func:`_cached_config` rather than re-parsed
-    on every call — see that function's docstring for why (#2654).
+    **Tier-blind** (see :class:`coord.config.AuditConfig`'s ``max_rows``
+    docstring): this deletes the globally oldest rows by ``id`` regardless
+    of ``tier``, so a busy ``operational``-tier writer can push a
+    ``business``-tier row out ahead of it.  Default (``max_rows=0``) is
+    unlimited — this is a no-op in the common case.  Config is read via
+    :func:`_cached_config` rather than re-parsed on every call — see that
+    function's docstring for why (#2654).  Use
+    :func:`sweep_operational_retention` for a tier-scoped cap instead.
     """
     max_rows = _resolve_max_rows()
     if max_rows <= 0:
@@ -292,6 +298,70 @@ def _maybe_trim(conn) -> None:
     conn.commit()
 
 
+# ── #3469: per-tier retention for the operational tier ──────────────────────
+#
+# `_maybe_trim` above is a row-count cap, tier-blind by construction (it has
+# to be: `max_rows` predates the `tier` column's operational-vs-business
+# distinction even mattering for retention). #3469's actual problem --
+# `forge_availability`'s ~100k operational-tier rows/day dwarfing the whole
+# table -- needs a cap that can bound just that tier without ever being able
+# to touch a `business`-tier row (a real board transition: dispatch, test/
+# review/merge verdicts) no matter how old it is. This is that cap: a plain
+# time-window DELETE scoped to `tier = 'operational'`, wired into
+# `coord.housekeeping.sweep`'s low-cadence tick (and `coord housekeeping`'s
+# on-demand run) rather than firing on every insert like `_maybe_trim` does
+# — the same cadence tradeoff `coord.forge_availability._PRUNE_INTERVAL_S`
+# already documents for the exact same reason.
+
+
+def _resolve_operational_retention_days() -> float:
+    """Read ``audit.operational_retention_days`` from coordinator.yml.
+    Returns ``0`` (disabled — keep everything, today's behaviour) on any
+    failure, matching :func:`_resolve_max_rows`'s fail-safe."""
+    try:
+        cfg = _cached_config()
+        return max(0.0, float(cfg.audit.operational_retention_days))
+    except Exception:  # noqa: BLE001 — best-effort; disabled is the safe default
+        return 0.0
+
+
+def sweep_operational_retention(*, now: float | None = None, dry_run: bool = False) -> int:
+    """Delete ``tier='operational'`` ``audit_log`` rows older than
+    ``audit.operational_retention_days`` (#3469).  Returns the number of
+    rows deleted (or, with ``dry_run=True``, that *would be* deleted) —
+    ``0`` when the knob is unset/disabled (the default) or there was
+    nothing past the cutoff.
+
+    **Never touches a ``business``-tier row**, regardless of age — the
+    ``WHERE tier = 'operational'`` clause is the whole point of this
+    function existing alongside the tier-blind :func:`_maybe_trim`.
+
+    Unlike ``record_audit``'s best-effort contract (a board mutation must
+    never fail because its audit row didn't write), this is explicit,
+    on-demand maintenance (``coord housekeeping``, or the daemon's
+    low-cadence tick calling the same path) — a failure here should
+    surface to whoever ran it, not vanish into a debug log.
+    """
+    days = _resolve_operational_retention_days()
+    if days <= 0:
+        return 0
+    now = now if now is not None else time.time()
+    cutoff = now - days * 86400.0
+    conn = get_connection()
+    if dry_run:
+        row = sql.execute(
+            conn,
+            "SELECT COUNT(*) FROM audit_log WHERE tier = 'operational' AND ts < ?",
+            (cutoff,),
+        ).fetchone()
+        return int(row[0]) if row else 0
+    cur = sql.execute(
+        conn, "DELETE FROM audit_log WHERE tier = 'operational' AND ts < ?", (cutoff,),
+    )
+    conn.commit()
+    return cur.rowcount if cur.rowcount and cur.rowcount > 0 else 0
+
+
 # ── #2654: cached config reads for the two per-write resolvers below ───────
 #
 # `_resolve_level` and `_resolve_max_rows` both used to call `coord.config.

{code_coordinator-0.5.531 → code_coordinator-0.5.533}/coord/commands/lifecycle.py

@@ -30,23 +30,47 @@ def _print_housekeeping_result(resp: dict) -> None:
     # this sweep did, so a run that only reclaimed leaked worktrees must not
     # print "nothing to archive" and hide it.
     removed_wt = resp.get("removed_confirm_worktrees", 0)
-    if not archived_a and not archived_n and not removed_wt:
+    # #3469: the operational-tier audit retention sweep runs unconditionally
+    # (its own knob, its own window — see `coord.housekeeping.sweep`'s
+    # docstring), independent of everything above, and must be reported on
+    # its own terms too: once `audit.operational_retention_days` is turned
+    # on, a tick that *only* deletes stale operational audit rows will be
+    # the common case, and silently folding it into the "nothing to
+    # archive" branch would hide the one thing #3469 exists to report.
+    audit_deleted = resp.get("audit_operational_deleted", 0)
+    # #3469: `reclaim=True` can be the only thing a run did (e.g. an
+    # operator running `coord housekeeping --reclaim` against a DB with
+    # nothing currently stale) — it must not go unreported just because
+    # nothing else fired.
+    reclaimed = bool(resp.get("reclaimed"))
+    nothing_archived = not archived_a and not archived_n and not removed_wt and not audit_deleted
+    if nothing_archived:
         click.echo(
             f"housekeeping: nothing to archive (no terminal rows older than {days}d)."
         )
-        return
-    verb = "would archive" if dry else "archived"
-    suffix = "  (dry-run — nothing moved)" if dry else ""
-    click.echo(
-        f"housekeeping: {verb} {archived_a} assignment(s) + "
-        f"{archived_n} notification(s) (terminal, older than {days}d).{suffix}"
-    )
+        if not reclaimed:
+            return
+    if archived_a or archived_n:
+        verb = "would archive" if dry else "archived"
+        suffix = "  (dry-run — nothing moved)" if dry else ""
+        click.echo(
+            f"housekeeping: {verb} {archived_a} assignment(s) + "
+            f"{archived_n} notification(s) (terminal, older than {days}d).{suffix}"
+        )
     if removed_wt:
         wt_verb = "would remove" if dry else "removed"
         click.echo(
             f"housekeeping: {wt_verb} {removed_wt} stale confirm-worktree(s) "
             "(#2974)."
         )
+    if audit_deleted:
+        audit_verb = "would delete" if dry else "deleted"
+        click.echo(
+            f"housekeeping: {audit_verb} {audit_deleted} stale operational "
+            "audit_log row(s) (#3469)."
+        )
+    if reclaimed:
+        click.echo("housekeeping: reclaimed disk space (VACUUM) (#3469).")
 
 
 @click.command(
@@ -58,8 +82,13 @@ def _print_housekeeping_result(resp: dict) -> None:
         "Moves terminal assignments older than COORD_ARCHIVE_RETENTION_DAYS "
         "(default 30) + their notifications into assignments_archive / "
         "notifications_archive — it NEVER deletes, and never touches active, "
-        "recent, merge-queued, open-issue-latest, or review-linked rows. Routes "
-        "through the daemon (the canonical DB lives there)."
+        "recent, merge-queued, open-issue-latest, or review-linked rows. Also "
+        "runs the #3469 operational-tier audit_log retention sweep (deletes "
+        "stale tier='operational' rows only, per audit.operational_retention_days "
+        "— business-tier rows are never touched). Pass --reclaim to also VACUUM "
+        "(dialect-routed) afterwards, so those DELETEs actually shrink the "
+        "on-disk DB — see 'coord housekeeping --help' for that flag's own "
+        "detail. Routes through the daemon (the canonical DB lives there)."
     ),
 )
 
@@ -69,9 +98,18 @@ def _print_housekeeping_result(resp: dict) -> None:
     is_flag=True,
     help="Report what would be archived without moving anything.",
 )
-
-
-def housekeeping(dry_run: bool) -> None:
+@click.option(
+    "--reclaim",
+    is_flag=True,
+    help=(
+        "#3469: after every archive/delete above has run, also run a "
+        "dialect-routed space-reclaim pass (SQLite VACUUM; Postgres VACUUM) "
+        "so a retention sweep's DELETEs actually shrink the on-disk DB "
+        "artifact. One-off, operator-invoked — never run automatically by "
+        "the daemon's low-cadence tick. No-op when combined with --dry-run."
+    ),
+)
+def housekeeping(dry_run: bool, reclaim: bool) -> None:
     """#762: archive stale terminal board rows (active/recent/referenced kept)."""
     from coord.board_service import daemon_reroute_target  # noqa: PLC0415
 
@@ -80,7 +118,12 @@ def housekeeping(dry_run: bool) -> None:
         from coord.client import post_record  # noqa: PLC0415
 
         try:
-            resp = post_record(_svc, "/housekeeping", {"dry_run": dry_run}, timeout=180.0)
+            resp = post_record(
+                _svc,
+                "/housekeeping",
+                {"dry_run": dry_run, "reclaim": reclaim},
+                timeout=180.0,
+            )
         except Exception as exc:  # noqa: BLE001
             click.echo(f"error: housekeeping via daemon failed: {exc}", err=True)
             sys.exit(1)
@@ -89,7 +132,7 @@ def housekeeping(dry_run: bool) -> None:
 
     from coord import housekeeping as _hk  # noqa: PLC0415
 
-    _print_housekeeping_result(_hk.sweep(dry_run=dry_run))
+    _print_housekeeping_result(_hk.sweep(dry_run=dry_run, reclaim=reclaim))
 
 
 @click.command(help="Poll agents and post completion/failure comments on GitHub.")

{code_coordinator-0.5.531 → code_coordinator-0.5.533}/coord/config.py

@@ -1658,15 +1658,21 @@ class StoreConfig:
 
 @dataclass
 class AuditConfig:
-    """``audit:`` block (#1036/#1038) — the append-only ``audit_log``
+    """``audit:`` block (#1036/#1038/#3469) — the append-only ``audit_log``
     table's tunables.
 
-    ``max_rows`` is a future retention cap, not a pruning sweep: when set
-    above the default ``0`` (unlimited), :func:`coord.audit.record_audit`
-    opportunistically deletes the oldest rows past that count after every
-    insert.  ``0`` means keep everything forever — the default for this
-    milestone, since retention policy is explicitly out of scope (see the
-    issue's "Out of scope" section).
+    ``max_rows`` is a **tier-blind** retention cap, not a pruning sweep: when
+    set above the default ``0`` (unlimited), :func:`coord.audit._maybe_trim`
+    opportunistically deletes the oldest rows *by ``id``, across every tier*
+    past that count after every insert. Plainly: capping ``max_rows`` on a
+    busy ``operational``-tier writer (e.g. #1896's ``forge_availability``)
+    can just as easily delete ``business``-tier history (dispatch / test /
+    review / merge verdicts) to make room — it has no concept of tier at
+    all. ``0`` means keep everything forever, still the default (retention
+    policy was explicitly out of scope for the milestone that introduced
+    this field). Use ``operational_retention_days`` below when the intent is
+    "bound the operational tier without ever touching business rows" —
+    that is the tier-aware knob #3469 added for exactly this gap.
 
     ``level`` (#1038) selects how much of the audit taxonomy is captured:
     ``"business"`` records only real board transitions (dispatch, verdicts,
@@ -1676,10 +1682,46 @@ class AuditConfig:
     ``tier="operational"``, ``actor="daemon"``.  Business-tier rows are
     always recorded regardless of ``level`` — this only gates the
     operational tier.
+
+    ``operational_retention_days`` (#3469) is a time-window retention sweep
+    scoped to ``tier="operational"`` rows only — :func:`coord.audit.
+    sweep_operational_retention` deletes ``operational`` rows older than
+    this many days and never touches a ``business`` row, no matter how old.
+    Default ``0`` disables the sweep entirely (today's behaviour: keep
+    everything). Wired into :func:`coord.housekeeping.sweep`'s low-cadence
+    tick, same as every other retention sweep in this codebase.
     """
 
     max_rows: int = 0
     level: str = "operational"
+    operational_retention_days: float = 0.0
+
+
+@dataclass
+class ForgeAvailabilityConfig:
+    """``forge_availability:`` block (#3469) — retention tuning for the
+    ``category="forge_availability"`` rows :mod:`coord.forge_availability`
+    writes into ``audit_log`` (#1896/#2654/#2988).
+
+    ``retention_days`` bounds how long a ``forge_availability`` row survives
+    before :func:`coord.forge_availability._maybe_prune` deletes it. Default
+    (30) is scoped to what ``coord diagnose --forge-availability`` actually
+    reads by default (its own ``--window-days`` defaults to 30) rather than
+    the historical hardcoded 90 — #3469 measured the 90-day steady state at
+    ~9M rows / ~3GB for this one category alone. ``90`` remains the
+    documented ceiling (:data:`coord.forge_availability.RETENTION_DAYS`):
+    any configured value above it is silently clamped down to 90, never up
+    — a config typo should not accidentally uncap the sweep.
+
+    Note the ``0`` asymmetry against ``AuditConfig.operational_retention_days``
+    above: there ``0`` means "sweep disabled, keep everything forever". Here
+    ``0``/negative is rejected outright (must be a positive number) — there is
+    no "never prune forge_availability" concept, since #1896/#2654/#2988 is
+    exactly the unbounded-growth problem this knob exists to prevent, and
+    disabling it by config would silently reopen that gap.
+    """
+
+    retention_days: float = 30.0
 
 
 @dataclass
@@ -2439,6 +2481,9 @@ class Config:
     milestone: MilestoneConfig = field(default_factory=MilestoneConfig)
     providers: ProvidersConfig = field(default_factory=ProvidersConfig)
     audit: AuditConfig = field(default_factory=AuditConfig)
+    forge_availability: ForgeAvailabilityConfig = field(
+        default_factory=ForgeAvailabilityConfig
+    )
     pricing: PricingConfig = field(default_factory=PricingConfig)
     health: HealthConfig = field(default_factory=HealthConfig)
     # #1632 — absent block == disabled == today's behaviour (silence).
@@ -2706,6 +2751,7 @@ def parse_mapping(raw: Any, *, path: Path | None = None) -> Config:
     propagation = _parse_propagation(raw.get("propagation"))
     milestone = _parse_milestone(raw.get("milestone"))
     audit = _parse_audit(raw.get("audit"))
+    forge_availability = _parse_forge_availability(raw.get("forge_availability"))
     pricing = _parse_pricing(raw.get("pricing"))
     health = _parse_health(raw.get("health"))
     notifications = _parse_notifications(raw.get("notifications"))
@@ -2731,6 +2777,7 @@ def parse_mapping(raw: Any, *, path: Path | None = None) -> Config:
         milestone=milestone,
         providers=providers,
         audit=audit,
+        forge_availability=forge_availability,
         pricing=pricing,
         health=health,
         notifications=notifications,
@@ -4626,6 +4673,34 @@ def _parse_audit(raw: Any) -> AuditConfig:
                 f"audit.level must be one of {_VALID_AUDIT_LEVELS!r}, got {value!r}"
             )
         cfg.level = value
+    if "operational_retention_days" in raw:
+        value = raw["operational_retention_days"]
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
+            raise ConfigError(
+                "audit.operational_retention_days must be a non-negative number"
+            )
+        cfg.operational_retention_days = float(value)
+    return cfg
+
+
+def _parse_forge_availability(raw: Any) -> ForgeAvailabilityConfig:
+    """Parse the optional ``forge_availability:`` block (#3469).
+
+    An absent block returns ``ForgeAvailabilityConfig()`` — the new 30-day
+    default, itself a deliberate change from the pre-#3469 hardcoded 90-day
+    retention (see that dataclass's docstring for the measured why).
+    """
+    if raw is None:
+        return ForgeAvailabilityConfig()
+    if not isinstance(raw, dict):
+        raise ConfigError("'forge_availability' must be a mapping")
+
+    cfg = ForgeAvailabilityConfig()
+    if "retention_days" in raw:
+        value = raw["retention_days"]
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+            raise ConfigError("forge_availability.retention_days must be a positive number")
+        cfg.retention_days = float(value)
     return cfg
 
 

{code_coordinator-0.5.531 → code_coordinator-0.5.533}/coord/drive.py

@@ -1387,7 +1387,9 @@ def _decide_acceptance_author(
         # cites), so the thing being waited for could not happen even with
         # `merge.auto_drain` on.
         return replace(
-            _decide_acceptance_landing(state, oracle, opts, counters, machine),
+            _decide_acceptance_landing(
+                state, oracle, opts, counters, machine, verifier
+            ),
             warnings=(
                 f"ACCEPTANCE: JIT slice {aid} is ADVISORY with commits present "
                 "— proceeding per --accept-advisory (#1357)",
@@ -1460,7 +1462,9 @@ def _decide_acceptance_author(
         # Authoring finished and the branch carries commits: hand over to the
         # landing driver, which observes the daemon-driven Test/Review stages
         # and performs the one step the daemon will not (#2079 — the merge).
-        return _decide_acceptance_landing(state, oracle, opts, counters, machine)
+        return _decide_acceptance_landing(
+            state, oracle, opts, counters, machine, verifier
+        )
 
     # "" / running: still authoring — nothing to drive yet.
     return _wait(
@@ -1476,6 +1480,7 @@ def _decide_acceptance_landing(
     opts: DriveOptions,
     counters: DriveCounters,
     machine: str,
+    verifier: MergeVerifier,
 ) -> Action:
     """Land the authored JIT acceptance slice (#2079).
 
@@ -1673,7 +1678,7 @@ def _decide_acceptance_landing(
         merge_aid=state.acceptance_merge_aid,
         merge_pr_url=state.acceptance_merge_pr_url,
     )
-    action = _decide_merge(shadow, opts, counters.slice_budget())
+    action = _decide_merge(shadow, opts, counters.slice_budget(), verifier)
     return replace(
         action,
         label=_acceptance_label(action.label),
@@ -1779,6 +1784,8 @@ class MergeVerifier(Protocol):
         self, state: IssueState
     ) -> EpicChecklistSnapshot | None: ...
 
+    def github_backoff_active(self) -> bool: ...
+
 
 def _remote_matches_repo(remote_url: str, repo_github: str) -> bool:
     """Loosely compare a ``git remote get-url origin`` URL against the
@@ -1991,6 +1998,26 @@ class GitMergeVerifier:
 
         return github_ops.get_branch_sha(state.repo_github, state.work_branch)
 
+    def github_backoff_active(self) -> bool:
+        """True when GitHub's shared, fleet-wide rate-limit backoff
+        (:mod:`coord.github_throttle`, #2809/#2934) is currently in force.
+
+        #3479: the ONE thing :func:`_decide_merge`'s ``"unknown_head"`` arm
+        must check before spending a live ``coord merge --only`` re-check —
+        see that arm's own docstring for the latched-reason bug this
+        guards against. Routed through :func:`coord.github_throttle.
+        consult` (not the same-host-only :func:`~coord.github_throttle.
+        current`) so this honours a backoff another machine recorded via
+        the daemon, exactly like the shared funnel every live ``gh`` call
+        already consults before it ever reaches GitHub — re-probing INTO a
+        window another host just tripped is precisely the synchronized-
+        hammering #2809 exists to prevent.
+        """
+        from coord import github_throttle  # noqa: PLC0415
+
+        _sleep_s, backoff = github_throttle.consult()
+        return backoff is not None
+
     def epic_checklist_snapshot(
         self, state: IssueState
     ) -> EpicChecklistSnapshot | None:
@@ -2913,7 +2940,7 @@ def decide(
             warnings=warnings,
         )
 
-    merge = _decide_merge(state, opts, counters)
+    merge = _decide_merge(state, opts, counters, verifier)
     return replace(merge, warnings=warnings + merge.warnings)
 
 
@@ -4275,7 +4302,10 @@ def _park_uat_fixup_dispatch_failure(
 
 
 def _decide_merge(
-    state: IssueState, opts: DriveOptions, counters: DriveCounters
+    state: IssueState,
+    opts: DriveOptions,
+    counters: DriveCounters,
+    verifier: MergeVerifier,
 ) -> Action:
     """The MERGE stage.
 
@@ -4335,13 +4365,55 @@ def _decide_merge(
     # confirmed. No retry or fix this driver can take changes GitHub's
     # answer; wait, exactly like the CI-unreadable case below, and never
     # spend a merge attempt re-observing the identical unreadable probe.
+    #
+    # #3479: this used to be a BARE `_wait()` for as long as this reason
+    # stayed on the board — nothing here ever re-probed, so a `merge_reason`
+    # from an outage that had already cleared just kept getting re-read
+    # forever (quadraui#1083: 309 consecutive polls over 2.5h reprinting the
+    # identical "branch head unknown" line while GitHub was fully healthy
+    # the whole time — `gh auth status` OK, rate limit 5000/5000 — because
+    # the REAL block, a failing required CI check, was a few lines further
+    # down in `_decide_merge` and this arm returned before ever reaching
+    # it). "Branch head unknown" means "wait until the probe recovers", so
+    # this now actually re-probes: once the shared GitHub backoff
+    # (:mod:`coord.github_throttle`, #2809/#2934 — the SAME funnel every
+    # live `gh` call already consults) is no longer active, dispatch the
+    # identical budget-exempt real `coord merge --only <aid>` re-check the
+    # CI-unreadable arm below uses, instead of re-reading a value nothing
+    # here ever refreshes. That live attempt re-evaluates every gate,
+    # including CI, so a resolved outage reaches the SAME `checks_failed` →
+    # `coord.commands.merge._dispatch_ci_fixes` path a human running the
+    # identical command by hand already does — the quadraui#1083 recovery.
+    #
+    # While the backoff IS active, this still just waits, WITHOUT touching
+    # `verifier`/GitHub at all — #2809's whole point is that hammering
+    # GitHub during a backoff window only prolongs it, so no probe (real or
+    # otherwise) is issued while one is in force.
     if _merge_gate_kind(gate_reason) == "unknown_head":
-        return _wait(
-            label=(
-                "MERGE: branch head unknown — GitHub read failed (rate "
-                "limit, auth, or network); waiting, not retrying (#2704): "
-                f"{gate_reason}"
+        if verifier.github_backoff_active():
+            return _wait(
+                label=(
+                    "MERGE: branch head unknown — GitHub backoff active "
+                    "(#2809); waiting, not probing (#2704/#3479): "
+                    f"{gate_reason}"
+                )
             )
+        aid = state.merge_aid or state.work_aid
+        return Action(
+            kind=RUN,
+            label=(
+                "MERGE: branch head unknown — GitHub backoff clear, "
+                "re-checking for real instead of re-reading the latched "
+                f"reason (#2704/#3479): {gate_reason}"
+            ),
+            command=("merge", "--only", aid, "--method", opts.merge_method),
+            on_error="warn",
+            error_message=(
+                "coord merge returned non-zero (or the merge lock timed "
+                "out) while re-checking an unknown branch head — "
+                "re-checking next poll"
+            ),
+            serialize_merge=True,
         )
     # #2947 (follow-up to #2687): the UAT gate is a human-attended block — no
     # `coord merge` retry can clear it, only an operator or a customer