code-coordinator 0.5.489__tar.gz → 0.5.491__tar.gz

{code_coordinator-0.5.489 → code_coordinator-0.5.491}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.489",
+  "tag": "0.5.491",
   "distance": 0,
-  "node": "g70de5f163979948f291485eda2a8ac9db8f4d439",
+  "node": "g0bf722668fffd8f60d76696692afdbf7f1b292ff",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-18"

{code_coordinator-0.5.489 → code_coordinator-0.5.491}/coord/db.py

@@ -470,6 +470,92 @@ def _is_release_build(version: str) -> bool:
     return _RELEASE_VERSION_RE.fullmatch(version) is not None
 
 
+class _NoActiveTestConnectionSentinel:
+    """Installed as the ``_conn`` singleton whenever pytest is running but no
+    test's ``coord_db`` fixture currently holds an active override (#3385).
+
+    ``tests/conftest.py``'s autouse ``coord_db`` fixture is function-scoped:
+    it only guarantees an isolated in-memory connection while ONE test's
+    setup/call/teardown phases are running. Before this sentinel existed,
+    that fixture's teardown called :func:`close`, which resets the module
+    singleton to plain ``None`` -- reopening the exact gap #1960's guard was
+    built to close, just one layer up: ANY caller of :func:`get_connection`
+    during that gap (between one test's teardown finishing and the next
+    test's setup starting, or before the very first test's setup has run at
+    all) fell through :func:`get_connection` into :func:`_open`, which
+    resolves the REAL ``~/.coord/coord.db`` (#1960, #3385). #1960's own guard
+    inside :func:`_open` only fires while ``PYTEST_CURRENT_TEST`` happens to
+    be set, which is not guaranteed across that specific gap -- exactly the
+    seam #3385 was filed to close after #3380's daemon-lifespan-shutdown fix
+    left the reported failure count unchanged.
+
+    Installed once at ``pytest_configure`` (before collection even starts,
+    closing the pre-first-test window) and reinstalled by ``coord_db``'s own
+    teardown after every test (closing the inter-test window), so ``_conn``
+    is never plain ``None`` for the life of a pytest process:
+    :func:`get_connection` always hands back either a real per-test override
+    or this sentinel -- it can no longer fall through to :func:`_open` while
+    pytest is running, regardless of what races ahead of the next test's
+    setup or what runs before the first one.
+
+    Any attempt to use it -- ``.execute()``, ``.cursor()``, ``.commit()``,
+    even the ``.closed`` probe :func:`_connection_is_closed` runs on every
+    cached connection -- raises :class:`ProductionDatabaseGuardError`
+    immediately via ``__getattr__``, so a caller that reaches this gets a
+    clear, correctly-attributed error instead of a real database file
+    quietly being opened (or silently reused) underneath it.
+
+    **Scope, stated plainly (#3385 review).** This closes exactly one seam:
+    the ``coord.db._conn`` singleton that :func:`get_connection` reads. It
+    is a real, previously-unguarded gap, but it is not asserted here to be
+    the sole or even primary source of the ~3700
+    ``ProductionDatabaseGuardError`` failures the issue reports on ``main``
+    -- that would require the actual CI failure log, which this fix was not
+    verified against (see the commit message for what evidence is, and is
+    not, available). One other unguarded route was found by inspection
+    while investigating this and is flagged rather than silently left for
+    someone else to rediscover: ``coord.dao.SqliteStore._connect()``'s
+    SQLite branch opens ``self._path`` (``DB_PATH`` by default,
+    resolved once at ``__init__``) with no pytest/non-release guard at all
+    -- unlike its Postgres branch, which calls
+    ``refuse_postgres_under_pytest`` first. ``SqliteStore()`` with no
+    explicit ``db_path`` (e.g. ``coord/reports.py``'s
+    ``_default_usage_rows``) would reach that unguarded path. Left
+    unmodified here: it is outside this fix's file scope
+    (``tests/conftest.py`` / ``coord/db.py``) and there is no confirmed
+    evidence it contributes to the reported count -- but if a post-merge
+    ``main`` ``Tests`` run still shows a nonzero
+    ``ProductionDatabaseGuardError`` count after this change, that is the
+    next place to look.
+    """
+
+    def __getattr__(self, name: str) -> Any:
+        raise ProductionDatabaseGuardError(
+            "coord.db.get_connection() was reached while no test's `coord_db` "
+            "fixture held an active override (#3385) -- this is the gap "
+            "between one test's teardown and the next test's setup, or "
+            "before the very first test's setup has run at all. A caller "
+            f"tried to access {name!r} on the connection singleton in that "
+            "gap. Likely causes: a background thread a prior test spawned "
+            "and never joined, or a fixture that reaches coord.db before "
+            "the autouse `coord_db` fixture has installed its override. See "
+            "#1960 (the guard this generalizes) and #3385 (this sentinel)."
+        )
+
+
+def _pytest_gap_sentinel() -> Any:
+    """Factory for :class:`_NoActiveTestConnectionSentinel` (#3385).
+
+    A function rather than a bare module-level instance so every install
+    site (``tests/conftest.py``'s ``pytest_configure`` and ``coord_db``
+    teardown) gets its own object -- cheap, and it means a traceback's
+    ``id()`` never accidentally suggests two installs shared state they
+    don't (the sentinel is stateless, but nothing here should rely on that
+    by sharing one instance).
+    """
+    return _NoActiveTestConnectionSentinel()
+
+
 def override_connection(conn: Any) -> None:
     """Replace the singleton connection.  Used in tests to inject :memory: DBs.
 

{code_coordinator-0.5.489 → code_coordinator-0.5.491}/coord/diagnose.py

@@ -735,6 +735,22 @@ def diagnose_stage(
     latest = _latest(assignments)
 
     if latest is None:
+        # #3383: a `review_claims` row held for a work assignment with ZERO
+        # review/test-author/mock-author rows (never dispatched, or all
+        # deleted) is unreachable from `_recover_review` below — that
+        # function only ever runs once `latest` above is non-None. Before
+        # this, `--stage review` hit this exact branch and reported the
+        # stage healthy while `dispatch_review` was permanently wedged
+        # behind the leaked claim (#3206's failure one state earlier — see
+        # `_leaked_review_claim_without_row`'s docstring). Checked BEFORE
+        # the "no review assignment" finding below, on claim state rather
+        # than on row existence, exactly as #3206 already does once a row
+        # exists.
+        if stage == "review" and _leaked_review_claim_without_row(
+            board, repo_name, issue_number, res, reset=reset, dry_run=dry_run,
+        ):
+            _cleanup_issue(board, config, repo_name, issue_number, res, dry_run=dry_run, reset=reset)
+            return res
         res.findings.append(f"no {stage} assignment on the board for #{issue_number}")
         res.recovered = True  # nothing wedged
         # Still run the issue-wide cleanup below.
@@ -818,6 +834,154 @@ def diagnose_stage(
     return res
 
 
+# #3383: a claim taken by `claim_review_dispatch` shortly before its caller
+# inserts the review row it's claiming for looks, from a single read,
+# identical to a genuinely leaked claim — the same false-positive window
+# `_recover_review` below already documents for the terminal-row case
+# (#3206). Below this age the claim is reported but NOT offered for release;
+# above it, treated as leaked.
+#
+# NOT short on purpose — `dispatch_review` (coord/review.py) claims at
+# `claim_review_dispatch` (~line 3070) and does NOT insert the review's
+# `assignments` row until `record_dispatched_assignment` (~line 3763); its
+# own `except Exception` handler at ~line 3815 calls the ~500 lines between
+# those two points "pr_lookup, briefing assembly, JSON handling of
+# agent_response, ...". That gap includes several sequential GitHub API
+# calls (`work_is_terminal`, `branch_commits_ahead`, `pr_lookup`,
+# `branch_exists_on_remote`, `pr_diff`, `get_compare_files`,
+# `get_compare_diff`, `get_pr_commit_messages`, an issue-body fetch) and then
+# a candidate loop that POSTs to each reviewer machine's `/assign` with
+# `timeout=ASSIGN_POST_TIMEOUT_SECS` (`coord/dispatch.py` — 60.0s),
+# falling through to the next candidate on rejection/timeout/unreachability.
+# A single slow/unreachable first-choice reviewer machine alone can burn the
+# full 60s before a second candidate is even tried, and there is no hard cap
+# on candidate count — so this has to clear that whole chain, not one
+# network round trip. Picked as a small multiple of minutes so it
+# comfortably outlasts a worst-case multi-candidate dispatch plus GitHub API
+# latency, while still being short enough that a *genuinely* leaked claim
+# doesn't sit unrecoverable for long once someone runs `--reset`.
+_REVIEW_CLAIM_LEAK_GRACE_SECS = 600.0
+
+
+def _leaked_review_claim_without_row(
+    board: "Board",
+    repo_name: str,
+    issue_number: int,
+    res: DiagnoseResult,
+    *,
+    reset: bool,
+    dry_run: bool,
+) -> bool:
+    """#3383: detect (and, under ``--reset``, release) a leaked
+    ``review_claims`` row for a work assignment that has NO review /
+    test-author / mock-author row at all — the one shape `_recover_review`
+    can never see, because `diagnose_stage` only calls it once
+    `stage_assignments(..., "review")` finds a row. A claim can be (and, per
+    the issue that reported this, was) taken and never released when the
+    work assignment it's keyed on was dispatched to review, that review
+    never got as far as inserting its own `assignments` row (or its row was
+    later deleted, e.g. by an earlier `--reset`), and the claim outlived it.
+    Every future `dispatch_review` for that work assignment then denies
+    forever with the misleading #3113 "lost the atomic dispatch-claim race"
+    reason — while `coord diagnose --stage review` (which hit the
+    `latest is None` "no review assignment" branch before this function
+    existed) reported the stage healthy.
+
+    Checked against the WORK assignment's id — `claim_review_dispatch` is
+    keyed on the id of the assignment BEING reviewed, never on a review
+    row's own id (see `_recover_review`'s `work_assignment_id` resolution).
+
+    Returns ``True`` when a claim was found (whether or not it could be
+    released yet — see the grace-period case) and this function has already
+    appended the appropriate finding(s); ``False`` when there is nothing to
+    report, in which case the caller's own "no review assignment" message
+    is the correct (healthy) diagnosis.
+    """
+    from coord.state import (  # noqa: PLC0415
+        has_review_claim,
+        release_review_dispatch_claim,
+        review_claim_age_secs,
+    )
+
+    # Narrowing, acknowledged: this only checks the NEWEST `work`-type row
+    # for the issue, whereas `claim_review_dispatch` is keyed on whatever
+    # work-assignment id `dispatch_review` was actually called with. If the
+    # issue ever accumulates more than one `work` row (e.g. a rework/retry
+    # dispatched after the original work assignment that leaked the claim),
+    # a claim held on the *older* id is invisible here because this checks
+    # only the *newest* one. `_recover_review` avoids this by reading the
+    # exact id off the review row's own `review_of_assignment_id` FK — there
+    # is no review row here to read that FK from, so this has to guess.
+    # Probably rare, and the issue's own "worth also considering" `coord
+    # doctor` suggestion is the more complete fix; left as a known gap
+    # rather than iterating over every `work` row here.
+    work_rows = stage_assignments(board, repo_name, issue_number, "work")
+    work_latest = _latest(work_rows)
+    if work_latest is None or not work_latest.assignment_id:
+        return False
+    work_assignment_id = work_latest.assignment_id
+    if not has_review_claim(work_assignment_id):
+        return False
+
+    age = review_claim_age_secs(work_assignment_id)
+    if age is not None and age < _REVIEW_CLAIM_LEAK_GRACE_SECS:
+        # Too fresh to distinguish from an in-flight `dispatch_review` call
+        # that has taken the claim but not yet inserted its review row —
+        # report it, but don't offer to release something that might still
+        # be a live, wanted dispatch.
+        res.findings.append(
+            f"work assignment {work_assignment_id} holds a review-dispatch "
+            f"claim taken {age:.1f}s ago with no review row yet — likely an "
+            "in-flight dispatch_review, not a leak; re-run diagnose again "
+            "shortly if this persists"
+        )
+        res.recovered = True
+        return True
+
+    res.findings.append(
+        f"no review assignment exists for #{issue_number}, but work "
+        f"assignment {work_assignment_id} still holds a review-dispatch "
+        "claim (leaked review_claims row, #3383 — the #3206 class one state "
+        "earlier) — every future dispatch_review for this work assignment "
+        "will deny with the misleading #3113 'lost the atomic dispatch-claim "
+        "race' reason until it is released. Re-run with --reset to release it."
+    )
+    res.recovered = False
+    res.needs_reset = True
+
+    if reset:
+        if dry_run:
+            res.findings.append(
+                "(dry-run) would release the leaked review-dispatch claim"
+            )
+            return True
+        release_review_dispatch_claim(work_assignment_id)
+        if has_review_claim(work_assignment_id):
+            res.findings.append(
+                f"release requested for {work_assignment_id}'s "
+                "review-dispatch claim, but it is still present on re-read "
+                "— the release did NOT persist"
+            )
+        else:
+            res.actions_taken.append(
+                "released leaked review-dispatch claim for work assignment "
+                f"{work_assignment_id} — dispatch_review is now re-dispatchable"
+            )
+            res.reset_performed = True
+            res.recovered = True
+            res.branch_preserved = True
+            # Matches `_do_reset`'s (#3206) convention: a successful release
+            # must clear the `needs_reset=True` set a few lines above, or
+            # `to_json_dict()` — documented as read by the TUI without
+            # scraping human-readable lines — carries the internally
+            # contradictory `recovered=true needs_reset=true
+            # reset_performed=true` even though the plain-text CLI's "still
+            # wedged" warning happens to be gated on `not reset` and so never
+            # shows it.
+            res.needs_reset = False
+    return True
+
+
 def _recover_review(
     board, config, latest, state, res: DiagnoseResult, *, dry_run: bool
 ) -> None:

{code_coordinator-0.5.489 → code_coordinator-0.5.491}/coord/state.py

@@ -2388,6 +2388,36 @@ def has_review_claim(of_assignment_id: str) -> bool:
     return row is not None
 
 
+def review_claim_age_secs(of_assignment_id: str) -> float | None:
+    """Seconds since *of_assignment_id*'s ``review_claims`` row was taken, or
+    ``None`` when no claim is held (#3383).
+
+    Sibling read to :func:`has_review_claim`, used by ``coord diagnose
+    --stage review`` to gate a claim release on age: a claim taken
+    microseconds ago by an in-flight :func:`claim_review_dispatch` call that
+    has not yet inserted its review ``assignments`` row is indistinguishable,
+    from a single read, from a genuinely leaked claim — exactly the
+    false-positive window already documented on the terminal-review-row path
+    in ``diagnose._recover_review`` (#3206). Comparing ``claimed_at`` against
+    a short grace period lets the caller tell "just claimed, dispatch still
+    running" apart from "claimed a long time ago, nothing is coming".
+
+    Same local-DB-only caveat as :func:`has_review_claim` — reads the local
+    connection, not the daemon, so it undercounts on a thin client.
+    """
+    if not of_assignment_id:
+        return None
+    conn = get_connection()
+    row = sql.execute(
+        conn,
+        "SELECT claimed_at FROM review_claims WHERE of_assignment_id=?",
+        (of_assignment_id,),
+    ).fetchone()
+    if row is None or row[0] is None:
+        return None
+    return time.time() - row[0]
+
+
 def release_review_dispatch_claim(of_assignment_id: str) -> None:
     """Release a claim taken by :func:`claim_review_dispatch`.
 

{code_coordinator-0.5.489 → code_coordinator-0.5.491}/tests/conftest.py

@@ -87,11 +87,27 @@ def pytest_configure(config):
 
     A no-op on the default SQLite path: it neither imports a driver nor opens
     a socket, so a plain ``pytest`` is unaffected.
+
+    #3385: also installs ``coord.db``'s pytest-gap sentinel as the initial
+    connection singleton, before collection (and therefore every test
+    module's import-time code) ever runs. See
+    :func:`coord.db._pytest_gap_sentinel` for what this closes: without it,
+    ``coord.db._conn`` starts life as plain ``None`` and stays that way until
+    the FIRST test's autouse ``coord_db`` fixture installs its override --
+    anything that calls ``coord.db.get_connection()`` before that point (e.g.
+    module-level code a test file runs at import/collection time) could fall
+    through to the real ``~/.coord/coord.db``. Installing the sentinel here
+    closes that window the same way ``coord_db``'s own teardown closes the
+    inter-test one.
     """
     from tests.backends import preflight
 
     preflight()
 
+    from coord import db as db_mod
+
+    db_mod.override_connection(db_mod._pytest_gap_sentinel())
+
 
 @pytest.fixture(autouse=True)
 def _non_terminal_work(monkeypatch):
@@ -1111,6 +1127,18 @@ def coord_db():
         # already-closed connection is a no-op on both drivers).
         session.close()
         db.close()
+        # #3385: `db.close()` just reset the singleton to plain `None` --
+        # reopening the gap #1960's guard exists to close, one layer up.
+        # Anything that calls `coord.db.get_connection()` between THIS
+        # test's teardown finishing and the NEXT test's `coord_db` setup
+        # installing its own override (a background thread a prior test
+        # spawned and never joined, a fixture that reaches coord.db before
+        # this one runs) would otherwise fall through to `_open()` and could
+        # reach the real `~/.coord/coord.db`. Installing the sentinel here
+        # closes that window; the next test's `coord_db` setup overwrites it
+        # with a fresh real override before that test's body ever runs, same
+        # as always.
+        db.override_connection(db._pytest_gap_sentinel())
 
 
 # Every module-attribute name that coord.db / coord.state / coord.config /

{code_coordinator-0.5.489 → code_coordinator-0.5.491}/tests/test_db.py

@@ -1100,6 +1100,77 @@ class TestOverrideConnection:
         _ensure_schema(sqlite3.connect(":memory:"))
 
 
+# ── pytest-gap sentinel (#3385) ──────────────────────────────────────────────
+#
+# #3385: `main`'s `Tests` workflow was red for 33 days with thousands of
+# `ProductionDatabaseGuardError`s, and #3380's daemon-lifespan-shutdown fix
+# left the count unchanged -- because the actual gap is in `coord.db`'s
+# connection singleton itself, not the daemon: `tests/conftest.py`'s autouse
+# `coord_db` fixture only guarantees an isolated override while ONE test's
+# own setup/call/teardown phases are running. Its teardown used to call
+# `close()`, which resets `_conn` to plain `None` -- reopening the #1960 gap
+# one layer up for anything that calls `get_connection()` in the window
+# between one test's teardown and the next test's setup, or before the very
+# first test's setup has run at all. #1960's own `PYTEST_CURRENT_TEST` guard
+# inside `_open()` only protects that window if the env var happens to still
+# be set at that exact moment, which is not guaranteed. `_pytest_gap_
+# sentinel()` (installed by both `pytest_configure` and `coord_db`'s
+# teardown in `tests/conftest.py`) closes it unconditionally: `_conn` is
+# never plain `None` for the life of a pytest process, so `get_connection()`
+# can no longer fall through to `_open()` -- and therefore the real
+# `~/.coord/coord.db` -- while pytest is running, regardless of timing.
+class TestPytestGapSentinel:
+    def test_any_attribute_access_raises_the_guard(self) -> None:
+        sentinel = db_mod._pytest_gap_sentinel()
+        with pytest.raises(db_mod.ProductionDatabaseGuardError, match="coord_db"):
+            sentinel.execute("SELECT 1")
+
+    def test_probing_closed_also_raises(self) -> None:
+        """`_connection_is_closed` -- the first thing `get_connection()` does
+        with a cached connection -- reads `.closed` via
+        `getattr(conn, "closed", False)`. The sentinel must not silently
+        answer "not closed" here: that would let `get_connection()` hand the
+        sentinel back as if it were a usable connection, deferring the
+        failure to whatever statement runs next instead of raising at the
+        point the gap was actually reached."""
+        sentinel = db_mod._pytest_gap_sentinel()
+        with pytest.raises(db_mod.ProductionDatabaseGuardError):
+            db_mod._connection_is_closed(sentinel)
+
+    def test_get_connection_raises_instead_of_opening_the_real_path(self) -> None:
+        """Simulates the exact gap #3385 closes: `_conn` holding the
+        sentinel, as `coord_db`'s teardown (and `pytest_configure`, before
+        the first test) now leave it, instead of plain `None`.
+
+        RED against the pre-#3385 shape (installing plain `None` here
+        instead): `get_connection()` would fall through to `_open()`, whose
+        only protection is whether `PYTEST_CURRENT_TEST` happens to be set at
+        that exact moment -- true during this test's own body, so it would
+        incidentally still raise here, just via a DIFFERENT code path (and
+        not at all in the actual gap this issue is about, between two tests,
+        which this single-test assertion cannot reach). GREEN here
+        demonstrates the sentinel raises unconditionally, before `_open()`
+        -- and therefore the real `~/.coord/coord.db` -- is ever reached,
+        which is what actually closes the inter-test gap.
+
+        Restores the real per-test connection in a ``finally`` rather than
+        via ``monkeypatch``: an earlier autouse fixture in
+        ``tests/conftest.py`` already pulls the shared ``monkeypatch``
+        instance's setup forward ahead of ``coord_db`` (see
+        ``_no_frozen_coord_dir_constants``'s docstring), which pushes
+        ``monkeypatch``'s own undo to AFTER ``coord_db``'s teardown -- so a
+        ``monkeypatch.setattr`` here would leave the sentinel installed when
+        ``coord_db``'s teardown tries to ``close()`` it.
+        """
+        original_conn = db_mod._conn
+        db_mod.override_connection(db_mod._pytest_gap_sentinel())
+        try:
+            with pytest.raises(db_mod.ProductionDatabaseGuardError, match="coord_db"):
+                db_mod.get_connection()
+        finally:
+            db_mod.override_connection(original_conn)
+
+
 # ── _resolve_store_target (#827) ─────────────────────────────────────────────
 
 _VALID_REPOS_MACHINES_YAML = (

{code_coordinator-0.5.489 → code_coordinator-0.5.491}/tests/test_diagnose.py

@@ -1220,6 +1220,24 @@ def _record(a: Assignment) -> None:
     conn.commit()
 
 
+def _backdate_review_claim(of_assignment_id: str, *, seconds_ago: float) -> None:
+    """Push a `review_claims` row's `claimed_at` into the past — used to put
+    a claim outside #3383's grace period (real claims in these tests are
+    taken via `state.claim_review_dispatch`, which stamps `time.time()`;
+    without this every test claim looks "just taken", which is exactly the
+    fresh-claim case the grace period is meant to protect)."""
+    import time as _time
+
+    from coord.db import get_connection
+
+    conn = get_connection()
+    conn.execute(
+        "UPDATE review_claims SET claimed_at=? WHERE of_assignment_id=?",
+        (_time.time() - seconds_ago, of_assignment_id),
+    )
+    conn.commit()
+
+
 def test_reset_review_real_db_deletes_review_when_latest_is_the_review_row(
     monkeypatch, config, coord_db
 ) -> None:
@@ -1381,6 +1399,141 @@ def test_diagnose_review_healthy_when_no_claim_leaked(
     assert any("healthy" in f for f in res.findings)
 
 
+def test_diagnose_review_detects_leaked_claim_with_no_review_rows(
+    monkeypatch, config, coord_db
+) -> None:
+    """#3383 regression: a `review_claims` row held for a work assignment
+    that has NO review/test-author/mock-author row AT ALL (the state one
+    step earlier than #3206's terminal-row case) used to be unreachable —
+    `stage_assignments(..., "review")` finds nothing, `latest is None`, and
+    `diagnose_stage` took the "no review assignment on the board" early
+    return before ever calling `_recover_review` (which is the only place
+    that cross-checked `review_claims`). This left the claim permanently
+    wedged with `coord diagnose --stage review --reset` reporting the stage
+    healthy AND doing nothing. This reproduces against unfixed `main`: the
+    old early return set `recovered=True` unconditionally with no claim
+    check at all.
+    """
+    from coord import state
+
+    _stub(monkeypatch, session="dead")
+    _record(_assign(
+        aid="w1", typ="work", status="done", review_state="dispatched",
+        dispatched_at=100.0,
+    ))
+    # Simulate the leak: a claim was taken (e.g. by a `dispatch_review` call
+    # whose review row never landed, or was later deleted) and never
+    # released — no review row exists to cross-check it against. Backdated
+    # well past the #3383 grace period so it isn't mistaken for a claim an
+    # in-flight `dispatch_review` just took (see the fresh-claim test below).
+    assert state.claim_review_dispatch("w1") is True
+    _backdate_review_claim("w1", seconds_ago=3600.0)
+
+    board = Board(completed=[_assign(aid="w1", typ="work", status="done", dispatched_at=100.0)])
+
+    res = diagnose.diagnose_stage(board, config, "api", 42, "review", dry_run=True)
+
+    assert res.recovered is False
+    assert res.needs_reset is True
+    assert any("review_claims" in f or "review-dispatch claim" in f for f in res.findings)
+    # A dry-run must not touch the claim.
+    assert state.claim_review_dispatch("w1") is False
+
+
+def test_reset_review_releases_leaked_claim_with_no_review_rows(
+    monkeypatch, config, coord_db
+) -> None:
+    """#3383: `--reset` must actually clear the leaked claim detected above
+    so `coord review <work-assignment-id>` becomes dispatchable again — the
+    whole point of the issue (there was previously NO operator CLI path at
+    all to clear this)."""
+    from coord import state
+
+    _stub(monkeypatch, session="dead")
+    _record(_assign(
+        aid="w1", typ="work", status="done", review_state="dispatched",
+        dispatched_at=100.0,
+    ))
+    assert state.claim_review_dispatch("w1") is True
+    _backdate_review_claim("w1", seconds_ago=3600.0)
+
+    board = Board(completed=[_assign(aid="w1", typ="work", status="done", dispatched_at=100.0)])
+
+    res = diagnose.diagnose_stage(board, config, "api", 42, "review", reset=True)
+
+    assert res.reset_performed is True
+    assert res.recovered is True
+    # The claim is gone — a fresh claim attempt for "w1" must succeed again,
+    # exactly like `dispatch_review` would need for a real re-dispatch.
+    assert state.claim_review_dispatch("w1") is True
+
+
+def test_reset_review_reports_leaked_claim_delete_failure_when_row_survives(
+    monkeypatch, config, coord_db
+) -> None:
+    """#3383 non-blocking review gap: `_leaked_review_claim_without_row`'s
+    own release path has the same "trust the write, not a re-read" risk that
+    `_do_reset`'s analogous #3206 terminal-row path already guards against
+    (see `test_reset_review_reports_delete_failure_when_row_survives`
+    above) — but nothing exercised it for this no-review-row shape. Simulate
+    `release_review_dispatch_claim` reporting success while the claim is
+    still present on re-read (mirrors the coord-tui#49 non-persisting write)
+    and assert the action line is honest about it rather than claiming the
+    claim is gone."""
+    from coord import state
+
+    _stub(monkeypatch, session="dead")
+    _record(_assign(
+        aid="w1", typ="work", status="done", review_state="dispatched",
+        dispatched_at=100.0,
+    ))
+    assert state.claim_review_dispatch("w1") is True
+    _backdate_review_claim("w1", seconds_ago=3600.0)
+
+    # Simulate a release call that reports success but never actually
+    # removes the row — `has_review_claim` still finds it on re-read.
+    monkeypatch.setattr(state, "release_review_dispatch_claim", lambda *a, **k: None)
+
+    board = Board(completed=[_assign(aid="w1", typ="work", status="done", dispatched_at=100.0)])
+
+    res = diagnose.diagnose_stage(board, config, "api", 42, "review", reset=True)
+
+    assert res.reset_performed is False
+    assert res.recovered is False
+    assert res.needs_reset is True
+    assert any(
+        "did NOT persist" in f
+        for f in res.findings
+    )
+    # Still held — the release never actually took.
+    assert state.claim_review_dispatch("w1") is False
+
+
+def test_diagnose_review_fresh_claim_without_row_not_treated_as_leaked(
+    monkeypatch, config, coord_db
+) -> None:
+    """Sibling of the two tests above: a claim taken only moments ago, with
+    no review row yet, is indistinguishable from an in-flight
+    `dispatch_review` call that has claimed but not yet inserted its review
+    row — the same false-positive window `_recover_review` already
+    documents for the terminal-row case (#3206), one state earlier. Must be
+    reported but NOT offered for release while this fresh."""
+    from coord import state
+
+    _stub(monkeypatch, session="dead")
+    _record(_assign(aid="w1", typ="work", status="done", dispatched_at=100.0))
+    assert state.claim_review_dispatch("w1") is True  # claimed "just now"
+
+    board = Board(completed=[_assign(aid="w1", typ="work", status="done", dispatched_at=100.0)])
+
+    res = diagnose.diagnose_stage(board, config, "api", 42, "review", dry_run=True)
+
+    assert res.needs_reset is False
+    assert any("in-flight dispatch_review" in f for f in res.findings)
+    # Untouched — still held.
+    assert state.claim_review_dispatch("w1") is False
+
+
 def test_reset_review_reports_delete_failure_when_row_survives(
     monkeypatch, config, coord_db
 ) -> None: