code-coordinator 0.5.213__tar.gz → 0.5.215__tar.gz

{code_coordinator-0.5.213 → code_coordinator-0.5.215}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.213",
+  "tag": "0.5.215",
   "distance": 0,
-  "node": "ga9e3937295f13339509408e4a07ca7e7028b9987",
+  "node": "g43e59d754122e055c18ab64170d43a1f2d7a4afd",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-21"

{code_coordinator-0.5.213 → code_coordinator-0.5.215}/coord/auto_loop.py

@@ -34,6 +34,7 @@ Data model:
 from __future__ import annotations
 
 import logging
+import sqlite3
 import time
 import uuid
 from dataclasses import dataclass
@@ -1221,10 +1222,37 @@ def _dispatch_fix(
     )
     board.active.append(fix_assignment)
 
-    record_dispatched_assignment(
-        assignment=fix_assignment,
-        repo_github=repo.github,
-    )
+    try:
+        record_dispatched_assignment(
+            assignment=fix_assignment,
+            repo_github=repo.github,
+        )
+    except sqlite3.OperationalError as exc:
+        if "database is locked" not in str(exc).lower():
+            # Not the transient contention this guard exists for (#2538) —
+            # a schema mismatch or malformed statement is a real bug and
+            # must not be swallowed as an ordinary declined dispatch.
+            raise
+        # `record_dispatched_assignment` already retries transient
+        # "database is locked" contention itself (coord.db.retry_on_locked,
+        # via coord._record_dispatched_assignment_local) — this is only
+        # reached once that bounded retry budget is exhausted. The fix
+        # worker has already been POSTed to the agent above and is really
+        # running; only the durable board-DB row failed to write. Treat it
+        # the same as any other declined dispatch (no machine, agent
+        # unreachable, …) rather than letting a transient lock crash the
+        # whole caller (`coord merge`'s CI-fix queue, the review auto-loop,
+        # …) — undo the in-memory append so a saved board never carries a
+        # row this call never durably recorded, and let the caller's
+        # existing "dispatch declined" handling take it from here.
+        board.active.remove(fix_assignment)
+        log.warning(
+            "auto_loop: fix dispatch for %s hit persistent DB contention "
+            "recording assignment %s (%s) — treating as not dispatched; "
+            "will retry next run",
+            work.assignment_id, fix_assignment.assignment_id, exc,
+        )
+        return None
     return fix_assignment
 
 

{code_coordinator-0.5.213 → code_coordinator-0.5.215}/coord/commands/merge.py

@@ -610,10 +610,24 @@ def _dispatch_ci_fixes(events, config, *, dry_run: bool) -> None:
                 details={"reason": "ci_fix_retry_cap", "error": entry.error},
             )
             dispatched_any = True  # the HUMAN_REQUIRED mutation needs saving
-        # else: budget remains but dispatch declined for another reason (no
-        # machine, an unrelated fix already in flight, agent unreachable) —
-        # leave the entry PENDING for the next tick to retry, exactly like a
-        # declined conflict-fix dispatch does.
+        else:
+            # Budget remains but dispatch declined for another reason (no
+            # machine, an unrelated fix already in flight, agent
+            # unreachable, or — #2538 — `_dispatch_fix` hit persistent
+            # "database is locked" contention recording the assignment
+            # after its own bounded retry budget was exhausted) — leave the
+            # entry PENDING for the next tick to retry, exactly like a
+            # declined conflict-fix dispatch does. Echoed (matching
+            # `_dispatch_conflict_fixes`'s equivalent branch) so an
+            # operator watching `coord merge` isn't left wondering why
+            # nothing happened for this entry — and so a transient DB lock
+            # collision on ONE entry is visibly a retry, not a silent drop,
+            # while every other entry keeps processing normally.
+            click.echo(
+                f"  {entry.repo_name} #{entry.issue_number}: "
+                "ci-fix not dispatched (no machine / already in flight / "
+                "transient DB contention — will retry next run)"
+            )
     if dispatched_any:
         save_board(fix_board)
 

{code_coordinator-0.5.213 → code_coordinator-0.5.215}/coord/db.py

@@ -15,7 +15,9 @@ from __future__ import annotations
 import json
 import os
 import sqlite3
+import time
 from pathlib import Path
+from typing import Callable, TypeVar
 
 from coord.platform_paths import default_coord_dir
 
@@ -88,6 +90,57 @@ def close() -> None:
         _conn = None
 
 
+_T = TypeVar("_T")
+
+# #2538: a handful of consecutive short retries — long enough to ride out a
+# concurrent writer (the daemon's own passive tick, another `coord merge`/
+# `coord notify` invocation) that only holds the DB for a moment, short
+# enough that a genuinely stuck lock still fails fast rather than hanging
+# `coord merge` for a long time.
+_LOCK_RETRY_ATTEMPTS = 5
+_LOCK_RETRY_BASE_DELAY_S = 0.1
+
+
+def retry_on_locked(
+    write: Callable[[], _T],
+    *,
+    attempts: int = _LOCK_RETRY_ATTEMPTS,
+    base_delay: float = _LOCK_RETRY_BASE_DELAY_S,
+) -> _T:
+    """Run *write* (a zero-arg callable performing one or more SQLite writes),
+    retrying with exponential backoff when SQLite raises ``database is
+    locked`` (#2538).
+
+    That error is transient contention — a concurrent writer holding the DB
+    at the exact moment this call tries to write, not a real failure — and a
+    short wait is very likely to let it clear.  ``PRAGMA busy_timeout``
+    (set on every connection in :func:`_open`) already makes SQLite itself
+    wait before raising, but under sustained contention (several writers in
+    a tight loop) that single wait can still be exhausted; this adds a few
+    more short, backed-off attempts on top rather than failing on the first
+    collision.
+
+    Any other ``OperationalError`` (schema drift, a malformed statement, …)
+    is re-raised immediately without retrying — those are not transient, and
+    retrying would only delay surfacing a real bug.  After *attempts*
+    consecutive ``database is locked`` collisions, re-raises the last
+    ``sqlite3.OperationalError`` so the caller can decide how to degrade
+    (see ``coord.state._record_dispatched_assignment_local``, whose caller —
+    ``coord.auto_loop._dispatch_fix`` — treats it as a declined dispatch
+    rather than letting it crash the whole run).
+    """
+    delay = base_delay
+    for attempt in range(1, attempts + 1):
+        try:
+            return write()
+        except sqlite3.OperationalError as exc:
+            if "database is locked" not in str(exc).lower() or attempt >= attempts:
+                raise
+            time.sleep(delay)
+            delay *= 2
+    raise AssertionError("unreachable")  # loop above always returns or raises
+
+
 # ── Schema ────────────────────────────────────────────────────────────────────
 
 def _ensure_schema(conn: sqlite3.Connection) -> None:

{code_coordinator-0.5.213 → code_coordinator-0.5.215}/coord/notify.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING
 import httpx
 
 if TYPE_CHECKING:
+    from coord.merge_queue import QueuedMerge
     from coord.models import Assignment, Board
     from coord.progress import SmokeVerdict
 
@@ -991,6 +992,14 @@ class StalledDispatchAction:
       (#602).
     - ``"skipped_human_required"``  — the conflict-fix retry cap was already
       hit; surfacing to a human, not auto-retrying.
+    - ``"skipped_sealed_conflict"`` (#2537) — ``merge_conflict_unresolved``
+      on a :data:`coord.models.SEALED_PATH_AUTHOR_TYPES` row whose conflict
+      was confirmed (:func:`_conflict_confined_to_sealed_paths`) to be
+      confined to the repo's sealed acceptance-oracle paths — a
+      conflict-fix worker is guaranteed to self-restrict and push nothing
+      there, so the dispatch was skipped rather than spending a worker
+      session on a known no-op; needs a sealed-path-aware rebase dispatcher
+      (a follow-up issue, not yet implemented).
     - ``"disabled"``                — ``pipeline.auto_dispatch_stalled`` is
       off; detection/narration still happened, dispatch did not.
     """
@@ -1044,6 +1053,50 @@ def _stalled_row_has_live_session(board: "Board", work: "Assignment") -> bool:
     return False
 
 
+def _conflict_confined_to_sealed_paths(
+    entry: "QueuedMerge", config: Config,
+) -> list[str] | None:
+    """#2537: best-effort check for whether *entry*'s merge conflict can
+    ONLY be within the repo's sealed acceptance-oracle paths
+    (:meth:`coord.config.AcceptanceConfig.sealed_paths`).
+
+    Returns the entry branch's changed-file list when every file it touches
+    (the three-dot compare of *entry.target_branch*...*entry.branch*, via
+    :func:`coord.github_ops.get_compare_files` — the SAME GitHub-API-only,
+    no-local-checkout seam #1720's dispatch-time overlap fence already uses)
+    falls under a sealed path. GitHub's conflicting-file set is necessarily
+    a SUBSET of this branch's own changed files — a file can only conflict
+    if *this* branch touches it too — so confining the WHOLE branch diff to
+    sealed paths is sufficient to guarantee the conflict is, without needing
+    a local checkout or a `git merge-tree` call.
+
+    Returns ``None`` — "can't confirm confinement, don't skip the ordinary
+    dispatch" — when: the repo has no acceptance driver configured (nothing
+    is sealed); the compare API call fails or reports no files; or anything
+    is touched outside every sealed path. This is a pure availability
+    signal, never a hard "not confined" claim — a caller that gets ``None``
+    falls back to :func:`coord.conflict_fix.dispatch_conflict_fix` exactly
+    as before, which is always safe: a genuinely sealed-confined conflict
+    just makes that dispatch a no-op (the conflict-fix worker self-restricts
+    per CLAUDE.md's own sealed-path rule), so the only cost of a missed
+    detection here is one wasted worker session, never an incorrect action.
+    """
+    sealed = config.acceptance.sealed_paths(entry.repo_name)
+    if not sealed:
+        return None
+    from coord import github_ops  # noqa: PLC0415
+    from coord.review import _path_is_sealed  # noqa: PLC0415
+
+    files = github_ops.get_compare_files(
+        entry.repo_github, entry.target_branch, entry.branch,
+    )
+    if not files:
+        return None
+    if all(any(_path_is_sealed(f, s) for s in sealed) for f in files):
+        return files
+    return None
+
+
 def dispatch_stalled_pipeline_action(
     detection: StalledDetection,
     work: "Assignment",
@@ -1058,11 +1111,12 @@ def dispatch_stalled_pipeline_action(
     Gated by ``config.pipeline.auto_dispatch_stalled`` (default ``False`` —
     detection/narration via :func:`post_stalled_pipeline` is unconditional;
     this is the opt-in action half) — EXCEPT for a ``review_request_changes_
-    no_fix`` stall on a :data:`coord.models.SEALED_PATH_AUTHOR_TYPES` row
-    (``test-author``/``mock-author``), which dispatches regardless of the
-    flag: no loop owns that row (#2302), so the flag would only leave it
-    stalled forever with no alternative dispatcher to race. ``work`` rows
-    under the same reason keep the opt-in gate — ``coord drive`` owns those.
+    no_fix`` OR (#2537) ``merge_conflict_unresolved`` stall on a
+    :data:`coord.models.SEALED_PATH_AUTHOR_TYPES` row (``test-author``/
+    ``mock-author``), which dispatches regardless of the flag: no loop owns
+    that row (#2302), so the flag would only leave it stalled forever with
+    no alternative dispatcher to race. ``work`` rows under the same reasons
+    keep the opt-in gate — ``coord drive`` owns those.
     Mutates *board* in place exactly like
     the auto-loop / review-dispatch helpers it delegates to — the caller is
     responsible for persisting it.
@@ -1091,7 +1145,15 @@ def dispatch_stalled_pipeline_action(
       the same bulk gate-checked enqueue the daemon passive tick already
       runs on every interval.
     - ``merge_conflict_unresolved`` → :func:`coord.conflict_fix.dispatch_conflict_fix`,
-      the #1474 ``_dispatch_conflict_fixes`` path.
+      the #1474 ``_dispatch_conflict_fixes`` path — UNLESS (#2537) *work* is a
+      :data:`coord.models.SEALED_PATH_AUTHOR_TYPES` row AND the conflict can
+      be confirmed (via :func:`_conflict_confined_to_sealed_paths`, a
+      compare-API-only check) to be confined to the repo's sealed
+      acceptance-oracle paths — a conflict-fix worker is REQUIRED by
+      CLAUDE.md's own sealed-path rule to self-restrict from editing those,
+      so it is guaranteed to push nothing; that case returns
+      ``"skipped_sealed_conflict"`` instead of spending a worker session on
+      a known no-op.
     - ``review_failed_no_verdict`` (#1584) → :func:`coord.review.dispatch_review`
       again, the SAME call as ``done_no_review`` — the failed review left no
       verdict behind, so recovery is identical to "no review was ever
@@ -1116,10 +1178,20 @@ def dispatch_stalled_pipeline_action(
     # no drive run over it at all (see #2289). So this one reason+type
     # combination bypasses the flag — every other reason, and `work` rows
     # under this same reason, keep the opt-in gate unchanged.
+    #
+    # #2537: a `merge_conflict_unresolved` stall on the SAME row types is the
+    # identical shape — `coord drive` has no conflict-fix arm for
+    # test-author/mock-author rows either (it `_die()`s on them before ever
+    # reaching a merge), and the passive tick only re-enqueues, never
+    # dispatches a conflict-fix. Without this, the row bounces
+    # PENDING → CONFLICT → parked forever with nobody attempting a fix
+    # (observed live: coord-portal#132). So this reason joins the bypass for
+    # these row types too — every other reason, and `work` rows under either
+    # reason, keep the opt-in gate unchanged.
     from coord.models import SEALED_PATH_AUTHOR_TYPES  # noqa: PLC0415
 
     sealed_author_stall = (
-        detection.reason == "review_request_changes_no_fix"
+        detection.reason in ("review_request_changes_no_fix", "merge_conflict_unresolved")
         and work.type in SEALED_PATH_AUTHOR_TYPES
     )
     if not config.pipeline.auto_dispatch_stalled and not sealed_author_stall:
@@ -1423,6 +1495,35 @@ def dispatch_stalled_pipeline_action(
                 kind="skipped_human_required",
                 detail="conflict-fix already active or its retry cap was already hit",
             )
+        # #2537: dispatch_conflict_fix is guaranteed to no-op on a conflict
+        # confined to the repo's sealed acceptance-oracle paths — the
+        # conflict-fix worker is REQUIRED by CLAUDE.md's own sealed-path
+        # rule to self-restrict from editing them (the additive carve-out
+        # applies only to test-author/mock-author dispatches, never
+        # conflict-fix), so it pushes nothing and the entry just re-stalls
+        # next tick. Confirmed live on coord-portal#132/#135: a manually
+        # forced dispatch_conflict_fix restored its worktree clean and
+        # pushed nothing. Skip the known-wasted dispatch when we can
+        # confirm confinement in advance; resolving it for real needs a
+        # sealed-path-aware re-dispatch (tracked as a follow-up issue, not
+        # yet implemented) — dispatch_conflict_fix stays the fallback for
+        # every other case (can't confirm confinement, or genuinely not
+        # confined).
+        if work.type in SEALED_PATH_AUTHOR_TYPES:
+            sealed_files = _conflict_confined_to_sealed_paths(entry, config)
+            if sealed_files is not None:
+                return StalledDispatchAction(
+                    kind="skipped_sealed_conflict",
+                    detail=(
+                        "conflict is confined to sealed acceptance paths ("
+                        + ", ".join(sealed_files)
+                        + ") — a conflict-fix worker is required to "
+                        "self-restrict from editing them (CLAUDE.md's "
+                        "sealed-path rule) and would push nothing; needs a "
+                        "sealed-path-aware rebase dispatcher (follow-up "
+                        "issue), not dispatch_conflict_fix"
+                    ),
+                )
         fix = dispatch_conflict_fix(entry, board, config, prefer_machine=work.machine_name)
         if fix is None:
             return StalledDispatchAction(

{code_coordinator-0.5.213 → code_coordinator-0.5.215}/coord/state.py

@@ -37,7 +37,7 @@ from coord._board_mapping import (
 from coord.audit import record_audit as _record_audit
 from coord.board_service import resolve as _board_service_resolve
 from coord.board_service import route_write as _route_write
-from coord.db import get_connection
+from coord.db import get_connection, retry_on_locked
 from coord.models import (
     WORK_LIKE_TYPES,
     Assignment,
@@ -1018,8 +1018,17 @@ def _record_dispatched_assignment_local(
     )
 
     conn = get_connection()
-    conn.execute(
-        """INSERT INTO assignments (
+
+    # #2538: this INSERT/commit is the one write in this function that's
+    # actually load-bearing (unlike the best-effort `_record_audit` call
+    # below it) — a concurrent writer (the daemon's own passive tick,
+    # another `coord merge`/`coord notify` invocation) holding the DB for a
+    # moment must not crash the caller.  The statement is safe to retry
+    # as-is: `assignment_id` is the primary key and the `ON CONFLICT ...
+    # DO UPDATE` makes a re-attempted write idempotent.
+    def _write() -> None:
+        conn.execute(
+            """INSERT INTO assignments (
             assignment_id, machine_name, repo_name, repo_github,
             issue_number, issue_title, status, type, briefing,
             files_allowed, model, dispatched_at, review_of_assignment_id,
@@ -1101,8 +1110,10 @@ def _record_dispatched_assignment_local(
             assignment.driven_by,
             assignment.dispatched_by_assignment_id,
         ),
-    )
-    conn.commit()
+        )
+        conn.commit()
+
+    retry_on_locked(_write)
     _record_audit(
         tier="business",
         category="dispatch",

{code_coordinator-0.5.213 → code_coordinator-0.5.215}/tests/test_auto_loop.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import sqlite3
 import uuid
 from dataclasses import replace
 from typing import Any
@@ -2402,6 +2403,105 @@ class TestDispatchFixRemoteBranchGuard:
         assert result.machine_name == "server"
 
 
+# ── #2538: persistent "database is locked" must decline, not crash ─────────
+
+
+class TestDispatchFixDbContention:
+    """coord-portal#2538: a concurrent writer (the daemon's own passive
+    tick, another `coord merge`/`coord notify` invocation) can hold the DB
+    at the exact moment `record_dispatched_assignment` tries to record a
+    dispatched fix. `coord.state`'s own bounded retry
+    (`coord.db.retry_on_locked`) already rides out a short collision; this
+    covers what happens once that retry budget is well and truly exhausted
+    — `_dispatch_fix` must degrade to its documented "None on failure"
+    contract instead of letting the raw `sqlite3.OperationalError` crash
+    the caller (`coord merge`'s CI-fix queue, the review auto-loop, …)."""
+
+    def _work(self, machine: str = "laptop") -> Assignment:
+        return Assignment(
+            machine_name=machine,
+            repo_name="api",
+            issue_number=5,
+            issue_title="Fix thing",
+            briefing="Original briefing.",
+            assignment_id="work-2538",
+            status="done",
+            branch="issue-5-fix-thing",
+            dispatched_at=0.0,
+            finished_at=1.0,
+            type="work",
+        )
+
+    def test_persistent_lock_contention_returns_none_without_crashing(
+        self,
+    ) -> None:
+        cfg = _two_machine_config()
+        work = self._work()
+        board = Board(completed=[work])
+        mock_http = MagicMock()
+        mock_http.post.return_value.json.return_value = {"id": "fix-2538-a"}
+        mock_http.post.return_value.raise_for_status = MagicMock()
+
+        with patch(
+            "coord.auto_loop.record_dispatched_assignment",
+            side_effect=sqlite3.OperationalError("database is locked"),
+        ):
+            result = _dispatch_fix(
+                work, "Fix briefing.", board, cfg, iteration=1,
+                http_client=mock_http,
+            )
+
+        assert result is None
+
+    def test_persistent_lock_contention_rolls_back_the_board_append(
+        self,
+    ) -> None:
+        """The fix assignment is appended to `board.active` before the DB
+        write is attempted (so a fully successful dispatch needs no extra
+        round trip) — a failed write must undo that append, or a later
+        `save_board` call (triggered by some OTHER entry succeeding in the
+        same `coord merge` tick) would persist a phantom row that was never
+        actually recorded."""
+        cfg = _two_machine_config()
+        work = self._work()
+        board = Board(completed=[work])
+        mock_http = MagicMock()
+        mock_http.post.return_value.json.return_value = {"id": "fix-2538-b"}
+        mock_http.post.return_value.raise_for_status = MagicMock()
+
+        with patch(
+            "coord.auto_loop.record_dispatched_assignment",
+            side_effect=sqlite3.OperationalError("database is locked"),
+        ):
+            _dispatch_fix(
+                work, "Fix briefing.", board, cfg, iteration=1,
+                http_client=mock_http,
+            )
+
+        assert board.active == []
+
+    def test_unrelated_operational_error_still_propagates(self) -> None:
+        """A genuine bug (schema drift, a malformed statement) must not be
+        swallowed as if it were routine transient contention — only the
+        specific `database is locked` message is treated as declinable."""
+        cfg = _two_machine_config()
+        work = self._work()
+        board = Board(completed=[work])
+        mock_http = MagicMock()
+        mock_http.post.return_value.json.return_value = {"id": "fix-2538-c"}
+        mock_http.post.return_value.raise_for_status = MagicMock()
+
+        with patch(
+            "coord.auto_loop.record_dispatched_assignment",
+            side_effect=sqlite3.OperationalError("no such column: bogus"),
+        ):
+            with pytest.raises(sqlite3.OperationalError, match="no such column"):
+                _dispatch_fix(
+                    work, "Fix briefing.", board, cfg, iteration=1,
+                    http_client=mock_http,
+                )
+
+
 # ── #1176: test-author bounce gets a type="test-author" fix, not "work" ─────
 
 

{code_coordinator-0.5.213 → code_coordinator-0.5.215}/tests/test_ci_fix.py

@@ -333,3 +333,27 @@ class TestDispatchCiFixesWrapper:
             merge_cmd._dispatch_ci_fixes(events, two_machine_config, dry_run=False)
 
         assert entry.state == PENDING
+
+    def test_declined_dispatch_under_budget_is_echoed(
+        self, two_machine_config: Config, coord_db, capsys,
+    ) -> None:
+        """#2538: a declined dispatch (including `_dispatch_fix` hitting
+        persistent DB-lock contention, which surfaces exactly like any
+        other decline — see coord.auto_loop._dispatch_fix) must be visible
+        in `coord merge` output, not silently dropped — otherwise an
+        operator watching the run has no idea this entry didn't advance."""
+        from coord.commands import merge as merge_cmd
+        from coord.state import save_board
+
+        board = Board()
+        save_board(board)
+
+        entry = _entry()
+        events = [self._checks_failed_event(entry)]
+
+        with patch("coord.ci_fix.dispatch_ci_fix", return_value=None):
+            merge_cmd._dispatch_ci_fixes(events, two_machine_config, dry_run=False)
+
+        out = capsys.readouterr().out
+        assert "ci-fix not dispatched" in out
+        assert f"#{entry.issue_number}" in out

{code_coordinator-0.5.213 → code_coordinator-0.5.215}/tests/test_db.py

@@ -9,7 +9,13 @@ from pathlib import Path
 import pytest
 
 from coord import db as db_mod
-from coord.db import _ensure_schema, override_connection, close, _migrate_gate_order
+from coord.db import (
+    _ensure_schema,
+    override_connection,
+    close,
+    _migrate_gate_order,
+    retry_on_locked,
+)
 
 
 # ── Fixtures ──────────────────────────────────────────────────────────────────
@@ -724,6 +730,78 @@ class TestMergeQueueCiFixDispatchesColumn:
         conn.close()
 
 
+# ── retry_on_locked (#2538) ─────────────────────────────────────────────────
+
+
+class TestRetryOnLocked:
+    """#2538: `coord merge` crashed the whole run on a transient
+    `sqlite3.OperationalError: database is locked` raised while recording a
+    dispatched CI-fix assignment. `retry_on_locked` gives a momentary
+    collision (the daemon's own passive tick, another `coord merge`/`coord
+    notify` invocation holding the DB) a few short, backed-off attempts to
+    clear before it becomes the caller's problem.
+    """
+
+    def test_succeeds_immediately_when_no_contention(self) -> None:
+        calls = []
+
+        def _write() -> str:
+            calls.append(1)
+            return "ok"
+
+        assert retry_on_locked(_write) == "ok"
+        assert len(calls) == 1
+
+    def test_retries_through_transient_lock_then_succeeds(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        sleeps: list[float] = []
+        monkeypatch.setattr(db_mod.time, "sleep", lambda s: sleeps.append(s))
+
+        attempts = {"n": 0}
+
+        def _write() -> str:
+            attempts["n"] += 1
+            if attempts["n"] < 3:
+                raise sqlite3.OperationalError("database is locked")
+            return "ok"
+
+        result = retry_on_locked(_write)
+
+        assert result == "ok"
+        assert attempts["n"] == 3
+        # Two collisions before the third, successful attempt — backed off
+        # (each wait longer than the last), never a busy-loop.
+        assert len(sleeps) == 2
+        assert sleeps[1] > sleeps[0]
+
+    def test_raises_after_exhausting_the_retry_budget(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setattr(db_mod.time, "sleep", lambda s: None)
+
+        def _write() -> None:
+            raise sqlite3.OperationalError("database is locked")
+
+        with pytest.raises(sqlite3.OperationalError, match="database is locked"):
+            retry_on_locked(_write, attempts=3, base_delay=0.0)
+
+    def test_unrelated_operational_error_is_not_retried(self) -> None:
+        """A schema/statement bug is a real failure, not transient
+        contention — it must surface on the very first attempt rather than
+        being retried (and delayed) as if it were lock contention."""
+        calls = []
+
+        def _write() -> None:
+            calls.append(1)
+            raise sqlite3.OperationalError("no such table: bogus")
+
+        with pytest.raises(sqlite3.OperationalError, match="no such table"):
+            retry_on_locked(_write)
+
+        assert len(calls) == 1
+
+
 # ── override_connection ────────────────────────────────────────────────────────
 
 class TestOverrideConnection: