code-coordinator 0.5.46__py3-none-any.whl

coord/reconcile.py

@@ -0,0 +1,2233 @@
+"""Reconcile the coordinator's board with live agent server state."""
+
+from __future__ import annotations
+
+import re
+import time
+import uuid
+
+import httpx
+
+from typing import TYPE_CHECKING
+
+from coord.config import Config
+from coord.dispatch import AGENT_PORT
+from coord.models import WORK_LIKE_TYPES, Assignment, Board, Machine
+
+if TYPE_CHECKING:
+    from coord.merge_queue import QueuedMerge
+
+
+def _query_agent(host: str, port: int = AGENT_PORT, timeout: float = 5.0) -> dict | None:
+    try:
+        resp = httpx.get(f"http://{host}:{port}/status", timeout=timeout)
+        resp.raise_for_status()
+        return resp.json()
+    except (httpx.HTTPError, httpx.TimeoutException):
+        return None
+
+
+# Terminal statuses an agent reports in its /status `completed` history,
+# mapped to the board terminal status we persist. (#625)
+_AGENT_TERMINAL_STATUS = {
+    "done": "done",
+    "advisory": "advisory",
+    "failed": "failed",
+    "cancelled": "failed",
+}
+
+
+def effective_agent_status(entry: dict) -> str:
+    """The agent-reported status for *entry*, with #1534's ``done`` refusal.
+
+    An agent ``completed`` entry that reports ``status="done"`` while ALSO
+    carrying a ``usage_limit_reason`` is self-contradictory: the worker was
+    killed mid-task by the account's Claude session/weekly usage limit (its
+    transcript ends on "You've hit your session limit · resets <time>"), so
+    whatever it did or didn't push, it did not *finish*.  Recording that as
+    ``done`` is the silent corruption #1534 was filed for — it burns money and
+    reports success, and every downstream gate (review dispatch, the
+    acceptance gate, the Pipeline view) then behaves as if the slice exists.
+
+    The agent-side reap (``AgentServer._reap``) already refuses this at the
+    source as of #1534, but that fix only reaches the fleet after a PyPI
+    release and ``coord agent update``.  This is the coordinator-side backstop
+    for the interim — and permanently, for agents pinned to an older build.
+
+    Downgraded to ``failed`` rather than ``advisory`` for the same reason
+    ``_record_usage_limit_reason`` normalises to ``failed``: a usage-limit kill
+    is the one terminal state known safe to re-dispatch unchanged once the
+    window resets, whereas ``advisory`` means "a human needs to look".
+
+    Any truthy ``usage_limit_reason`` counts — not just one matching
+    :func:`coord.worker_events.is_usage_limit_reason`'s prefix — because
+    refusing a ``done`` is the fail-safe direction and the field is only ever
+    written by the kill detector.
+    """
+    raw = (entry.get("status") or "").lower()
+    if raw == "done" and entry.get("usage_limit_reason"):
+        return "failed"
+    return raw
+
+
+def reconcile_completed_assignments(
+    config: Config,
+    *,
+    board: Board | None = None,
+    agent_status_fn=_query_agent,
+    update_state_fn=None,
+    capture_plan: bool = True,
+) -> list[dict]:
+    """Dispatch-free passive completion reconcile (#625).
+
+    Poll the agent of every RUNNING board assignment; for any the agent
+    reports terminal in its ``/status`` ``completed`` history, write the
+    terminal status + ``finished_at`` to the board via the issue_store seam
+    and (best-effort) capture a plan's structured output.  This reflects a
+    headless worker's already-finished state so the board — and the TUI box
+    colour — stops lying when the auto-loop (the only other thing that polled
+    agents) is turned off.
+
+    Deliberately minimal — it is the WHOLE point of #625 that reflecting a
+    termination is *passive* state, decoupled from auto-dispatch so it can
+    never re-introduce the dispatch flood:
+
+    * NEVER dispatches work/review.
+    * NEVER posts a GitHub comment.
+    * Only acts on ``status == "running"`` rows, so it is idempotent — once a
+      row is flipped terminal a later tick skips it.
+
+    **#1616 — what runs the side effects this function refuses to (CONTRACT
+    CHANGE, read this before adding anything here).**  This function's scope is
+    unchanged and must stay unchanged; what changed is *who runs the rest*.
+    Until #1616 the parenthetical here read "the single completion/plan comment
+    is left to an explicit ``coord notify``" — and on a fleet where
+    ``coord-notify.timer`` is deliberately disabled, "an explicit ``coord
+    notify``" meant *a live* ``coord drive``'s **stall nudge**, and nothing
+    else.  So this function advancing a row to ``done`` was the LAST thing that
+    happened to it for as long as 47 minutes (#1122), or forever when no drive
+    was running at all (vimcode#611/#613).  ``status`` said done; ``finished_at``
+    was NULL, no comment was posted, no review was dispatched, and every surface
+    rendered the stage as complete.
+
+    The fix was **not** to widen this function.  The daemon ``_tick_loop`` now
+    calls :func:`coord.serve_app._notify_drain_tick` →
+    :func:`coord.notify.run_drain` as a SIBLING step immediately after this one,
+    which posts the comment, stamps ``finished_at``, backfills the #1076/#1152
+    test gate, and dispatches Test + Review under ``~/.coord/notify.lock``.
+    That is where pipeline-advancing behaviour belongs; this stays passive.
+
+    This is the failure shape ``docs/OPERATING_GOTCHAS.md`` §7 already names —
+    "``reconcile()`` accretes behaviour the automatic drivers never invoke".
+    If you are about to add a side effect here because "nothing else runs it",
+    that is the bug, not the fix: add it to ``run_drain`` instead, and decide
+    deliberately whether it belongs on the daemon's clock at all (work dispatch
+    and fix-round dispatch explicitly do NOT — see that docstring).
+
+    One consequence worth knowing when reading a board: a ``type="review"``
+    ``done`` is downgraded to ``"finalizing"`` below and only leaves that state
+    when the drain captures the verdict.  Pre-#1616 that window was unbounded
+    (#1610); it is now bounded by ``COORD_NOTIFY_DRAIN_INTERVAL`` (default 60s).
+
+    Interactive sessions are tmux launches, not agent subprocesses, so they
+    never appear in the agent's ``completed`` list — a live attended session
+    can't be reaped by this path.
+
+    Returns one dict per reconciled assignment (empty when nothing changed).
+    """
+    if update_state_fn is None:
+        from coord.issue_store import _update_local_state  # noqa: PLC0415
+
+        update_state_fn = _update_local_state
+
+    if board is None:
+        from coord.state import build_board  # noqa: PLC0415
+
+        board = build_board()
+
+    running = [a for a in board.active if a.status == "running"]
+    if not running:
+        return []
+
+    hosts = {m.name: m.host for m in config.machines}
+    status_by_host: dict[str, dict | None] = {}  # poll each agent at most once
+    reconciled: list[dict] = []
+
+    for a in running:
+        aid = a.assignment_id
+        if not aid:
+            continue
+        host = hosts.get(a.machine_name)
+        if not host:
+            continue
+        if host not in status_by_host:
+            status_by_host[host] = agent_status_fn(host)
+        status = status_by_host[host]
+        if not status:
+            continue  # agent unreachable → leave the row, retry next tick
+        entry = next(
+            (e for e in status.get("completed", []) if e.get("id") == aid),
+            None,
+        )
+        if entry is None:
+            continue  # still active on the agent (or rolled off history) → leave it
+        # #1534: `effective_agent_status` refuses an agent-reported `done`
+        # that also carries a usage-limit-kill reason — the daemon's passive
+        # tick is the FIRST place most completions are observed, so without
+        # this the corrupt `done` is persisted here before any other path
+        # gets a chance to look at it.
+        terminal = _AGENT_TERMINAL_STATUS.get(effective_agent_status(entry))
+        if terminal is None:
+            continue
+        # #1566: a review agent reporting `done` has only finished the LLM
+        # session — the verdict itself is parsed + persisted by `coord
+        # notify` (`_try_parse_and_post_review`), a separate, slower step
+        # that can run minutes after this tick observes the completion (this
+        # passive tick runs on a short ~30s cadence; `coord notify` runs on
+        # whatever cadence its caller configures). Writing `status="done"`
+        # straight away leaves a window where the board shows a finished
+        # review with `review_verdict IS NULL` — indistinguishable from the
+        # verdict having been dropped (the #1346/#1348/#1563 failure mode).
+        # `finalizing` closes that window: it reads as "still wrapping up"
+        # (not in `drive_state.TERMINAL_STATUSES`, so `coord drive` correctly
+        # waits rather than declaring a dead end) until `coord notify`'s own
+        # `mark_notified` advances it to the real `done` alongside the
+        # verdict. Other terminal outcomes (`failed`, `advisory`) never go
+        # through that verdict-capture step, so they are unaffected.
+        if terminal == "done" and a.type == "review":
+            terminal = "finalizing"
+
+        # #1083: prefer the board's already-known branch, but fall back to
+        # the agent's live ``completed`` entry (populated by AgentServer._reap
+        # from the worktree's checked-out HEAD — see agent.py) when the board
+        # doesn't have one yet. This is almost always the FIRST place a
+        # freshly-completed assignment is observed (the daemon runs this tick
+        # on a short interval, well ahead of any human-triggered `coord
+        # notify`), so passing the board's stale (usually still-None) branch
+        # here — as this used to do unconditionally — let status flip to
+        # "done" with branch left NULL. For `type="work"` that NULL branch is
+        # later patched by the #611 remote-branch-listing backfill sweep in
+        # `reconcile()`, but that sweep is scoped to `type="work"` only, so
+        # every other write-capable type (mock-author, test-author, ...) had
+        # no path back to a correct branch once this tick got there first.
+        # #1461: stamp a usage-limit-kill diagnostic onto the board row when
+        # the agent's own reap flagged one (AgentServer._reap, agent.py) —
+        # regardless of whether the agent landed on FAILED or ADVISORY, both
+        # observed for a real kill. This is the primary production path
+        # (the daemon's passive tick) for getting the reason out of the
+        # ephemeral agent-side JSON and into the persisted, drive.py-visible
+        # `failure_reason` column.
+        # #1584: `api_error_reason` (a terminal `is_error: true` result event
+        # — e.g. "529 Overloaded") is the SAME `failure_reason` column,
+        # stamped by `AgentServer._reap` exactly like `usage_limit_reason`
+        # (see `coord.agent.AgentAssignment`, both surfaced on the same
+        # `/status` `completed` entry via `to_status_dict`'s `asdict`). The
+        # two are mutually exclusive by construction — a usage-limit kill is
+        # detected from a TRUNCATED log with no terminal `result` event,
+        # while an API-error is read OFF that terminal `result` event — so
+        # this `or` never picks the wrong one.
+        # #1797: `push_failure_reason` is the SAME column too — stamped by
+        # `AgentServer._reap` when the reap-time safety-net push hits an
+        # auth-shaped rejection (see `_is_auth_push_failure`). It never
+        # coexists with the other two either: it is only ever set on a
+        # clean `exit_code == 0` reap, which both `usage_limit_reason` and
+        # `api_error_reason` preempt before the push-failure branch even
+        # runs (see the `elif` chain in `AgentServer._reap`). Without this,
+        # a `type="work"` auth-push failure lands FAILED with no
+        # `failure_reason` at all — invisible to `coord status`, the TUI,
+        # and drive.py, which is the exact visibility gap #1797 exists to
+        # close.
+        _failure_reason = (
+            entry.get("usage_limit_reason")
+            or entry.get("api_error_reason")
+            or entry.get("push_failure_reason")
+        )
+        update_state_fn(
+            assignment_id=aid,
+            terminal_status=terminal,
+            branch=a.branch or entry.get("branch"),
+            review_state=None,
+            failure_reason=_failure_reason,
+            # #1605: the reap already computed the exit code (AgentServer._reap,
+            # agent.py) and it rides on this same `/status` `completed` entry —
+            # nothing downstream of THIS write path ever persisted it, so a
+            # failed Test-stage row was undiagnosable from the board (both
+            # `failure_reason` AND `exit_code` null) even when the reap knew
+            # exactly why it died.
+            exit_code=entry.get("exit_code"),
+        )
+
+        # #1605: a `type="smoke"` (Test-stage) assignment reaching a terminal
+        # FAILED status must resolve the PARENT work row's `test_state` —
+        # never leave it `running` forever. `running` is a documented
+        # transient non-verdict marker (#1395) that every gate treats as "no
+        # verdict yet", so a stranded child leaves the issue permanently
+        # unresolvable and invisible to every instrument except a worker
+        # transcript. See `propagate_smoke_terminal_failure` for the
+        # environmental-vs-work classification (#1590) that decides whether
+        # this clears the verdict for a fresh auto-dispatch or records a real
+        # test failure.
+        if a.type == "smoke" and terminal == "failed":
+            propagate_smoke_terminal_failure(
+                parent_assignment_id=a.review_of_assignment_id,
+                failure_reason=_failure_reason,
+            )
+
+        # #666 Gap A: best-effort cost/token capture from the agent completed
+        # entry.  Must never raise — a tick crash breaks the daemon.
+        _capture_cost_from_entry_best_effort(aid, entry)
+
+        plan_captured = (
+            _capture_plan_best_effort(host, aid)
+            if capture_plan and a.type == "plan"
+            else False
+        )
+
+        # #667: capture token counts from the /status entry (the agent now
+        # includes them there after parsing its own log).  Best-effort — any
+        # failure is swallowed so it can't break the reconcile.
+        _capture_tokens_best_effort(aid, entry)
+
+        reconciled.append(
+            {
+                "assignment_id": aid,
+                "issue_number": a.issue_number,
+                "repo": a.repo_name,
+                "type": a.type,
+                "to_status": terminal,
+                "plan_captured": plan_captured,
+            }
+        )
+
+    return reconciled
+
+
+def propagate_smoke_terminal_failure(
+    *, parent_assignment_id: str | None, failure_reason: str | None,
+) -> None:
+    """#1605: resolve a work row's ``test_state`` when its Test-stage
+    (``type="smoke"``) child dies without ever reporting pass/fail.
+
+    Before this, a smoke assignment landing on ``status="failed"`` (a dead
+    agent, a killed process group, a terminal API error — anything short of
+    the worker itself printing ``SMOKE: pass``/``SMOKE: fail``) left the
+    parent's ``test_state`` at whatever it was — almost always ``"running"``,
+    the marker `dispatch_smoke` stamps the instant it dispatches (#1426).
+    Every downstream gate treats ``"running"`` as "no verdict yet" (#1395),
+    so the work sits in a state nothing will ever resolve: `coord drive`
+    polls it forever, the merge gate never sees a verdict, and `coord
+    diagnose --stage test` had nothing to say because it never looked past
+    the (terminal, `status="done"`) work row itself.
+
+    Classified through :func:`coord.failure_class.classify_failure` — the
+    same #1590 environmental-vs-work split already used for the work/review
+    stages, applied here for the first time to the Test stage:
+
+    * **environmental** (usage limit, an API 5xx, a network drop) — the
+      provider's fault, not the work's. Clears ``test_state`` back to
+      ``NULL`` (not ``"failed"``) so the daemon's normal
+      :func:`coord.smoke.dispatch_pending_smoke` auto-queue picks the work
+      row back up on its next tick and re-dispatches a fresh Test stage —
+      never spending the bounded ``coord fix`` retry budget on a code defect
+      that never existed.
+    * **work** (an unclassifiable crash, a real defect) — records
+      ``test_state="failed"`` exactly like a normal non-zero-exit smoke
+      completion already does (`coord/notify.py`'s completion handler), so
+      the existing bounded `coord fix` loop picks it up from there.
+
+    A no-op when *parent_assignment_id* is falsy (a smoke row somehow
+    missing its ``review_of_assignment_id`` — should not happen in practice,
+    but this must never raise on it).
+    """
+    if not parent_assignment_id:
+        return
+    from coord.failure_class import classify_failure  # noqa: PLC0415
+    from coord.state import record_test_verdict  # noqa: PLC0415
+
+    classification = classify_failure(failure_reason=failure_reason)
+    if classification.is_environmental:
+        record_test_verdict(
+            assignment_id=parent_assignment_id,
+            test_state=None,
+            test_reason=(
+                "Test stage worker died environmentally "
+                f"({classification.reason}) — cleared for automatic "
+                "re-dispatch, not recorded as a work failure (#1605)"
+            ),
+        )
+    else:
+        record_test_verdict(
+            assignment_id=parent_assignment_id,
+            test_state="failed",
+            test_reason=(
+                failure_reason
+                or "Test stage worker failed with no reason recorded (#1605)"
+            ),
+        )
+
+
+def _capture_plan_best_effort(host: str, assignment_id: str) -> bool:
+    """Fetch + persist a plan's structured output from the agent log so the
+    TUI's plan detail panel isn't empty after a passive reconcile.  Best
+    effort: any failure is swallowed — the terminal-status write already
+    landed and is what fixes the stuck box."""
+    try:
+        from coord.plan_parser import parse_plan_from_agent  # noqa: PLC0415
+        from coord.state import save_plan  # noqa: PLC0415
+
+        plan = parse_plan_from_agent(host, assignment_id)
+        if plan is None or plan.is_empty():
+            return False
+        save_plan(assignment_id, plan.to_dict())
+        return True
+    except Exception:  # noqa: BLE001 — never let plan capture break the reconcile
+        return False
+
+
+def _capture_cost_from_entry_best_effort(assignment_id: str, entry: dict) -> None:
+    """#666 Gap A: capture cost from an agent ``completed`` entry when flipping
+    a row terminal.
+
+    Best-effort and silent — any exception is swallowed so a cost-capture
+    failure never crashes the daemon's reconcile tick.
+
+    Cost source: ``total_cost_usd`` (full-log parse, available when the agent
+    serves terminal entries) with ``cost_so_far`` as a fallback.  Either is
+    used only when present and > 0 so an un-measured session isn't written as 0.
+
+    Token counts are captured separately by ``_capture_tokens_best_effort``
+    (#667 Gap B), which is called at the same call site.
+    """
+    try:
+        from coord.state import update_assignment_cost  # noqa: PLC0415
+
+        raw_cost = entry.get("total_cost_usd") or entry.get("cost_so_far")
+        if raw_cost is not None:
+            try:
+                cost = float(raw_cost)
+            except (TypeError, ValueError):
+                cost = None
+            else:
+                if cost > 0:
+                    update_assignment_cost(assignment_id, cost)
+    except Exception:  # noqa: BLE001 — never let cost capture break the reconcile
+        pass
+
+
+def _capture_tokens_best_effort(assignment_id: str, entry: dict) -> None:
+    """#667: persist token counts from a /status completed entry.
+
+    The agent now parses its own log and includes
+    ``input_tokens`` / ``output_tokens`` / ``cache_creation_tokens`` /
+    ``cache_read_tokens`` in the completed entry.  We write them to the DB
+    here so a passive reconcile also captures tokens (not just cost).
+    Best-effort — any failure is swallowed.
+    """
+    try:
+        input_tokens = int(entry.get("input_tokens") or 0)
+        output_tokens = int(entry.get("output_tokens") or 0)
+        cache_creation_tokens = int(entry.get("cache_creation_tokens") or 0)
+        cache_read_tokens = int(entry.get("cache_read_tokens") or 0)
+        if input_tokens + output_tokens + cache_creation_tokens + cache_read_tokens == 0:
+            return
+        from coord.state import update_assignment_tokens  # noqa: PLC0415
+
+        update_assignment_tokens(
+            assignment_id,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cache_creation_tokens=cache_creation_tokens,
+            cache_read_tokens=cache_read_tokens,
+        )
+    except Exception:  # noqa: BLE001 — never let token capture break the reconcile
+        pass
+
+
+def _build_fix_round_retry_briefing(
+    failed: Assignment, board: Board, repo_cfg, max_review_iterations: int,
+) -> str | None:
+    """#1411: rebuild the FIX briefing (reviewer findings included) for a
+    retried fix-round assignment.
+
+    ``failed`` is itself a fix worker (``review_iteration > 0``) dispatched
+    by the auto-loop — its branch already carries the code the reviewer
+    rejected. The generic retry briefing built by :func:`_build_retry_briefing`
+    has no notion of *why*, so a plain continuation retry reliably repeats
+    the same request-changes verdict (a wasted work+review round) and, worse,
+    used to reset ``review_iteration`` to 0 — silently disabling the
+    ``max_review_iterations`` flood guard.
+
+    Reuses ``auto_loop._build_fix_briefing`` — the exact function the
+    original fix dispatch used — fed with the reviewer's findings recovered
+    via ``auto_loop._load_review_findings`` (DB cache → local log → agent
+    HTTP → GitHub message bus), the same resolution chain the auto-loop
+    itself relies on. This is deliberately a reuse, not a new capability.
+
+    Returns ``None`` when the review chain can't be reconstructed (the
+    reviewed work assignment or its review is missing from the board, or the
+    findings can't be recovered from any source) — the caller falls back to
+    the generic continuation briefing rather than blocking the retry.
+    """
+    work = board.find_by_id(failed.review_of_assignment_id)
+    if work is None:
+        return None
+
+    review = next(
+        (
+            a for a in (*board.active, *board.completed)
+            if a.type == "review"
+            and a.review_of_assignment_id == failed.review_of_assignment_id
+        ),
+        None,
+    )
+    if review is None:
+        return None
+
+    from coord.auto_loop import _build_fix_briefing, _load_review_findings  # noqa: PLC0415
+
+    findings = _load_review_findings(
+        review, None, None,
+        repo_github=repo_cfg.github if repo_cfg is not None else None,
+    )
+    if findings is None:
+        return None
+
+    return _build_fix_briefing(
+        work, findings, failed.review_iteration, max_review_iterations,
+    )
+
+
+def _build_retry_briefing(
+    failed: Assignment, repo_cfg, *, default_branch: str | None = None,
+    board: Board | None = None, max_review_iterations: int = 3,
+) -> str:
+    """#1101: reconstruct a real briefing for a retried assignment.
+
+    ``failed.briefing`` is frequently empty or unhelpful by the time a
+    failed assignment is retried — a `work` assignment's fully-assembled
+    briefing (issue body + board context) is built at initial-dispatch
+    time and not always persisted back onto the stored ``Assignment``.
+    Replaying it verbatim can hand the retried worker nothing at all,
+    which reproduced as the worker exiting in one turn with 0 commits
+    (silently reclassified as "advisory" instead of a broken dispatch).
+
+    This rebuilds something the worker can act on:
+    - the original briefing text when present, else a fresh fetch of the
+      issue body from GitHub (mirrors ``coord assign``'s own
+      auto-generate-from-issue-body fallback) so the briefing is never
+      blank;
+    - continuation instructions when the failed assignment already has a
+      branch (mirrors the equivalent ``coord fix`` briefing in
+      ``plan_followup.py``): don't start over, inspect what's already
+      committed;
+    - the recorded failure reason, so the worker knows why the previous
+      attempt stopped instead of re-discovering it from scratch.
+
+    #1411: when *failed* is itself a fix round (``review_iteration > 0``),
+    the ``## Task`` section is instead the rebuilt FIX briefing — reviewer
+    findings included — via :func:`_build_fix_round_retry_briefing`, so the
+    retry knows what the reviewer objected to instead of blindly redoing
+    work the branch already contains.
+    """
+    fix_task: str | None = None
+    if failed.review_iteration and failed.review_iteration > 0 and board is not None:
+        fix_task = _build_fix_round_retry_briefing(
+            failed, board, repo_cfg, max_review_iterations,
+        )
+
+    base = (failed.briefing or "").strip()
+    if not base and fix_task is None and repo_cfg is not None:
+        try:
+            from coord import github_ops  # noqa: PLC0415
+
+            issue_data = github_ops.get_issue(repo_cfg.github, failed.issue_number)
+            issue_body = issue_data.get("body", "")
+            if issue_body:
+                base = f"Issue #{failed.issue_number}: {failed.issue_title}\n\n{issue_body}"
+        except RuntimeError:
+            pass  # best-effort — fall through with whatever we have
+
+    sections: list[str] = []
+    if failed.branch:
+        # #934: point the retry's diff/log instructions at `feature/ms-NN`
+        # when this issue belongs to a milestone and the repo opted into the
+        # git model — falls back to `default_branch` (today's behavior)
+        # otherwise. Callers that already resolved this (``_reassign``) pass
+        # it in via *default_branch*; otherwise resolve it here, but only
+        # perform the milestone lookup (a `gh` call) when the repo opted in.
+        if default_branch is None:
+            default_branch = (repo_cfg.default_branch if repo_cfg is not None else None) or "main"
+            if repo_cfg is not None and getattr(repo_cfg, "develop_branch", None):
+                from coord.branch_model import (  # noqa: PLC0415
+                    fetch_issue_milestone_number,
+                    resolve_base_branch,
+                )
+
+                milestone_number = fetch_issue_milestone_number(
+                    repo_cfg.github, failed.issue_number,
+                )
+                default_branch = resolve_base_branch(repo_cfg, milestone_number)
+        sections.append(
+            "## Retry — continuing existing work\n"
+            f"This is a retry of a previously failed assignment "
+            f"({failed.assignment_id}). The previous worker's branch "
+            f"`{failed.branch}` already exists and may carry real, "
+            f"committed work — you are continuing it, NOT starting over.\n"
+            f"Run `git fetch origin && git log --oneline "
+            f"origin/{default_branch}..HEAD` to see what's already done, "
+            f"and `git diff origin/{default_branch}...HEAD` for the full "
+            f"diff, before writing any new code."
+        )
+    if failed.failure_reason:
+        sections.append(f"## Why the previous attempt failed\n{failed.failure_reason}")
+    if fix_task is not None:
+        sections.append(
+            f"## Task — fix round {failed.review_iteration} "
+            f"(reviewer findings included)\n{fix_task}"
+        )
+    elif base:
+        sections.append(f"## Task\n{base}")
+    if not sections:
+        # Nothing stored, nothing fetched, no branch context either — this
+        # is exactly the silent-empty-briefing failure mode from #1101.
+        sections.append(
+            f"Issue #{failed.issue_number}: {failed.issue_title}\n\n"
+            f"(No stored briefing or issue body was available to "
+            f"reconstruct this retry — investigate issue "
+            f"#{failed.issue_number} directly.)"
+        )
+    return "\n\n".join(sections)
+
+
+def _running_by_machine(board: Board) -> dict[str, list[Assignment]]:
+    """Group ``board.active`` running assignments by machine name (#1417).
+
+    Shared by :func:`_reassign` and :func:`describe_no_candidate_machines` so
+    the two paths can never drift on what counts as "running".
+    """
+    running: dict[str, list[Assignment]] = {}
+    for a in board.active:
+        if a.status == "running":
+            running.setdefault(a.machine_name, []).append(a)
+    return running
+
+
+def _machine_capacity(machine: Machine, config: Config) -> int:
+    """Effective concurrent-assignment cap for *machine* (#1417).
+
+    ``machines[].max_workers`` in coordinator.yml overrides the fleet-wide
+    ``concurrency.max_workers`` default — set it lower on hardware that
+    can't keep up with the fleet norm (e.g. a 4-core box among 20-core
+    desktops). Unset (``None``) means "use the fleet-wide default", so a
+    single running assignment no longer reads as "full" the way a bare
+    ``machine in busy`` membership check used to (#1417).
+    """
+    return machine.max_workers if machine.max_workers is not None else config.concurrency.max_workers
+
+
+class UnsupportedRetryType(ValueError):
+    """Raised by :func:`_reassign` when *failed.type* cannot be safely
+    re-dispatched through the work-retry path (#1636).
+
+    ``_reassign`` used to hardcode ``type="work"`` on every retry regardless
+    of the failed assignment's actual type — a retried ``smoke``/``review``
+    row silently came back as a fresh WORK worker (model escalated) pointed
+    at the already-complete branch, instead of re-running the Test/Review
+    stage. Raising here — instead of silently downgrading to work — lets
+    every caller (``coord retry``, ``auto_reassign``) surface the command
+    that actually re-runs the right stage rather than quietly doing the
+    wrong thing.
+    """
+
+    def __init__(self, assignment_type: str, work_assignment_id: str | None):
+        self.assignment_type = assignment_type
+        self.work_assignment_id = work_assignment_id
+        super().__init__(
+            f"assignment type {assignment_type!r} cannot be retried "
+            "through the work-retry path"
+        )
+
+
+# #1636: types whose failed row can be re-dispatched with the exact command
+# that re-runs their stage — `review_of_assignment_id` on a smoke/review
+# assignment is the work assignment it targets, so the hint is always
+# actionable when set. Extend this map, not the work-retry path, when a new
+# non-WORK_LIKE type grows its own retry story.
+_RETRY_REDIRECT_FLAGS: dict[str, str] = {
+    "smoke": "--smoke-of",
+    "review": "--review-of",
+}
+
+
+def describe_unsupported_retry_type(exc: UnsupportedRetryType) -> str:
+    """Human-readable refusal message for :class:`UnsupportedRetryType` (#1636).
+
+    Mirrors :func:`describe_no_candidate_machines` — a caller shouldn't have
+    to hand-craft the "this can't be retried" message.
+    """
+    flag = _RETRY_REDIRECT_FLAGS.get(exc.assignment_type)
+    if flag is not None and exc.work_assignment_id:
+        return (
+            f"assignment type {exc.assignment_type!r} cannot be retried "
+            "with `coord retry` — that would silently re-dispatch it as a "
+            "fresh work worker on the already-complete branch. Re-run its "
+            f"stage instead: `coord assign --interactive {flag} "
+            f"{exc.work_assignment_id}`."
+        )
+    return (
+        f"assignment type {exc.assignment_type!r} cannot be retried with "
+        "`coord retry` — that would silently re-dispatch it as a fresh "
+        "work worker. Re-dispatch it through its own path instead."
+    )
+
+
+def _reassign(
+    failed: Assignment, board: Board, config: Config,
+    *,
+    model: str | None = None,
+) -> Assignment | None:
+    """Re-dispatch a failed assignment to a machine with spare capacity.
+
+    *model* overrides the model tier on the retry. When None, the
+    original assignment's model is reused (escalation happens at the call
+    site).
+
+    Raises :class:`UnsupportedRetryType` when ``failed.type`` is not in
+    :data:`coord.models.WORK_LIKE_TYPES` — a ``smoke``/``review``/other
+    non-work row must not be silently re-dispatched as a fresh
+    ``type="work"`` worker (#1636).
+    """
+    if failed.type not in WORK_LIKE_TYPES:
+        raise UnsupportedRetryType(failed.type, failed.review_of_assignment_id)
+
+    from coord.machine_pause import paused_set
+    paused = paused_set(config.machines)
+    running = _running_by_machine(board)
+
+    # #1417: fleet-wide cap first — respected regardless of per-machine
+    # headroom, mirroring `concurrency.max_workers`'s documented meaning as
+    # the total concurrent-worker budget across the whole fleet.
+    fleet_running = sum(len(v) for v in running.values())
+    if fleet_running >= config.concurrency.max_workers:
+        return None
+
+    def has_room(m: Machine) -> bool:
+        return len(running.get(m.name, [])) < _machine_capacity(m, config)
+
+    candidates = [
+        m for m in config.machines
+        if m.can_work_on(failed.repo_name)
+        and m.repo_path(failed.repo_name) is not None
+        and has_room(m)
+        and m.name != failed.machine_name
+        and m.name not in paused
+    ]
+    if not candidates:
+        # Fall back to including the same machine that failed last time —
+        # paused machines stay excluded even from the fallback.
+        candidates = [
+            m for m in config.machines
+            if m.can_work_on(failed.repo_name)
+            and m.repo_path(failed.repo_name) is not None
+            and has_room(m)
+            and m.name not in paused
+        ]
+    if not candidates:
+        return None
+
+    machine = candidates[0]
+    repo_path = machine.repo_path(failed.repo_name)
+
+    # #437: STRUCTURAL TOS-COMPLIANCE GATE — auto-reassign is an
+    # unattended dispatch path; refuse to retry through a provider that
+    # opts out of unattended use.  Resolve precedence with per-repo
+    # override and the global default (the failed assignment doesn't
+    # carry a spec-level provider into this path).  On refusal: skip the
+    # reassignment — the failed assignment stays failed for human
+    # attention rather than getting silently re-tried on the wrong
+    # provider.
+    from coord.providers import guard_unattended_dispatch  # noqa: PLC0415
+    repo_for_provider = config.repo(failed.repo_name)
+    try:
+        guard_unattended_dispatch(
+            spec_provider=None,
+            repo_provider=(
+                repo_for_provider.provider
+                if repo_for_provider is not None
+                else None
+            ),
+            providers_cfg=config.providers,
+            models_cfg=config.models,
+            where="auto-reassign (reconcile)",
+        )
+    except ValueError:
+        return None
+
+    retry_model = model if model is not None else failed.model
+    # The Assignment keeps the alias for legibility; the wire payload is
+    # resolved through models.versions when an exact id is pinned.
+    retry_model_wire = config.models.resolve(retry_model)
+
+    repo_cfg = config.repo(failed.repo_name)
+    # #934: retry inherits `feature/ms-NN` as its integration base when this
+    # issue belongs to a milestone and the repo opted into the git model —
+    # falls back to `default_branch` (today's behavior) otherwise. Resolved
+    # once and reused for both the briefing's diff instructions and the
+    # `branch` payload field below, so they never disagree. The milestone
+    # lookup itself is skipped (no `gh` call) when the repo hasn't opted in.
+    retry_default_branch = (repo_cfg.default_branch if repo_cfg is not None else None) or "main"
+    if repo_cfg is not None and getattr(repo_cfg, "develop_branch", None):
+        from coord.branch_model import (  # noqa: PLC0415
+            fetch_issue_milestone_number,
+            resolve_base_branch,
+        )
+
+        milestone_number = fetch_issue_milestone_number(
+            repo_cfg.github, failed.issue_number,
+        )
+        retry_default_branch = resolve_base_branch(repo_cfg, milestone_number)
+    retry_briefing = _build_retry_briefing(
+        failed, repo_cfg, default_branch=retry_default_branch,
+        board=board, max_review_iterations=config.pipeline.max_review_iterations,
+    )
+    payload = {
+        "repo_name": failed.repo_name,
+        "repo_path": repo_path,
+        "issue_number": failed.issue_number,
+        "issue_title": f"[retry] {failed.issue_title}",
+        "briefing": retry_briefing,
+        "files_allowed": failed.files_allowed,
+        "files_forbidden": failed.files_forbidden,
+        "pull_repos": [],
+        # #1636: carries the failed assignment's own type (guaranteed to be
+        # in WORK_LIKE_TYPES by the guard above) instead of hardcoding
+        # "work" — a "mock-author"/"test-author" retry must not silently
+        # relabel itself as plain work.
+        "type": failed.type,
+        "model": retry_model_wire,
+        # #255: retry inherits the repo's configured default branch as the
+        # worker's integration base (the start point / rebase target).
+        "branch": retry_default_branch,
+    }
+    # #1101: continue the failed assignment's actual branch instead of
+    # silently forking a fresh one off the repo default — any real work it
+    # already committed and pushed must not be orphaned by a retry. Mirrors
+    # the `target_branch` wire field `--fix-of`/`--rework-of`/
+    # `_dispatch_followup` already use; the agent checks out this exact
+    # branch (hard-reset to the remote tip) when it exists on origin, and
+    # falls back to a fresh branch off `branch` above when it doesn't.
+    if failed.branch:
+        payload["target_branch"] = failed.branch
+
+    url = f"http://{machine.host}:{AGENT_PORT}/assign"
+    try:
+        resp = httpx.post(url, json=payload, timeout=15)
+        resp.raise_for_status()
+        agent_response = resp.json()
+    except (httpx.HTTPError, httpx.TimeoutException):
+        return None
+
+    retry_assignment = Assignment(
+        machine_name=machine.name,
+        repo_name=failed.repo_name,
+        issue_number=failed.issue_number,
+        issue_title=f"[retry] {failed.issue_title}",
+        files_allowed=failed.files_allowed,
+        files_forbidden=failed.files_forbidden,
+        briefing=retry_briefing,
+        assignment_id=agent_response.get("id") or uuid.uuid4().hex[:12],
+        status="running",
+        dispatched_at=time.time(),
+        type=failed.type,
+        model=retry_model,
+        # #1101: record the continued branch on the board immediately
+        # instead of waiting for a later reconcile backfill from agent
+        # /status — the retry payload above already told the agent to
+        # check out `failed.branch` via target_branch.
+        branch=failed.branch,
+        # #1411: carry the fix-loop bookkeeping across the retry. Without
+        # this the retry's review_iteration silently resets to 0, so
+        # `pipeline.max_review_iterations` loses its accounting — a story
+        # that already burned fix rounds looks fresh again. Preserving
+        # review_of_assignment_id too keeps the work/review chain intact
+        # for `_build_fix_round_retry_briefing` if THIS retry also fails
+        # and gets retried again.
+        review_iteration=failed.review_iteration,
+        review_of_assignment_id=failed.review_of_assignment_id,
+        # #1553: carry the oracle-loop slice attribution across the retry
+        # too — otherwise a retried acceptance slice silently falls back to
+        # being booked against the milestone's tracking issue and the
+        # child's row goes quiet again mid-run. None for ordinary work.
+        for_issue_number=failed.for_issue_number,
+    )
+    board.active.append(retry_assignment)
+
+    from coord.state import record_dispatched_assignment
+    repo = config.repo(failed.repo_name)
+    if repo is not None:
+        record_dispatched_assignment(
+            assignment=retry_assignment,
+            repo_github=repo.github,
+        )
+
+    return retry_assignment
+
+
+def describe_no_candidate_machines(
+    failed: Assignment, board: Board, config: Config,
+) -> str:
+    """Explain why :func:`_reassign` found no candidate machine (#1396).
+
+    ``_reassign`` silently returns ``None`` on any of: no machine with spare
+    capacity can work on the repo, a TOS-gate refusal, or a dispatch POST
+    failure — so a caller (``coord retry``) can only ever say "no available
+    machine to retry on", which is true from the code's point of view and
+    useless to an operator when ``coord status`` shows every machine well
+    under capacity. The real cause is almost always a phantom ``running``
+    board row: a dead interactive (``claude-pty``) session that nothing
+    reaped, still counted against the machine's capacity.
+
+    Mirrors ``_reassign``'s exact candidate filter (repo capability, repo
+    path, pause set, capacity check, same-machine exclusion — #1417 replaced
+    the old binary "any running assignment = busy" rule with a per-machine
+    capacity count against ``machines[].max_workers``/``concurrency.
+    max_workers``) but keeps a reason per excluded machine instead of
+    discarding it, so the message names the blocking machines and what
+    they're apparently running — including the age, which makes a
+    400-hour-old phantom obvious at a glance.
+    """
+    from coord.machine_pause import paused_set  # noqa: PLC0415
+
+    paused = paused_set(config.machines)
+    now = time.time()
+
+    running_by_machine = _running_by_machine(board)
+
+    relevant_machines = [
+        m for m in config.machines
+        if m.can_work_on(failed.repo_name) and m.repo_path(failed.repo_name) is not None
+    ]
+    if not relevant_machines:
+        return f"no machine in coordinator.yml can work on repo {failed.repo_name!r}"
+
+    # #1417: the fleet-wide cap blocks every machine regardless of
+    # individual headroom — computed once so a machine that's personally
+    # under its own cap can still be correctly labeled as blocked by the
+    # fleet-wide budget instead of silently reading as "free".
+    fleet_running = sum(len(v) for v in running_by_machine.values())
+    fleet_cap = config.concurrency.max_workers
+    fleet_full = fleet_running >= fleet_cap
+
+    lines: list[str] = []
+    has_free_candidate = False
+    for m in relevant_machines:
+        if m.name in paused:
+            lines.append(f"  {m.name}: paused")
+            continue
+        running = running_by_machine.get(m.name, [])
+        cap = _machine_capacity(m, config)
+        own_full = len(running) >= cap
+        if own_full or fleet_full:
+            if running:
+                parts = []
+                for a in running:
+                    age_h = (now - a.dispatched_at) / 3600 if a.dispatched_at else None
+                    age_str = f"{age_h:.1f}h" if age_h is not None else "?h"
+                    parts.append(
+                        f"{a.repo_name}#{a.issue_number} type={a.type} age={age_str}"
+                    )
+                load_desc = f"{len(running)}/{cap} running: {'; '.join(parts)}"
+            else:
+                load_desc = f"0/{cap} running"
+            if own_full:
+                reason = f"busy — at capacity ({load_desc})"
+            else:
+                # This machine has its own headroom, but the fleet-wide
+                # budget (concurrency.max_workers) is exhausted — name the
+                # actual binding constraint rather than implying the
+                # machine itself is the problem.
+                reason = (
+                    f"fleet at capacity ({fleet_running}/{fleet_cap} running "
+                    f"fleet-wide; this machine {load_desc})"
+                )
+            lines.append(f"  {m.name}: {reason}")
+            continue
+        if m.name == failed.machine_name:
+            # `_reassign`'s fallback pass drops only the "different machine"
+            # constraint — it still honors capacity/paused — so a
+            # under-capacity machine that just failed IS a real fallback
+            # candidate (#1396 review finding 1). Categorize it as such; the
+            # "(fallback-only)" label stays in `lines` for readers of the
+            # capacity/paused branch below, but this path never reaches that
+            # branch once a candidate is found.
+            lines.append(f"  {m.name}: same machine that just failed (fallback-only)")
+            has_free_candidate = True
+            continue
+        has_free_candidate = True
+
+    if has_free_candidate:
+        # A machine WAS free per this filter — _reassign must have failed for
+        # a different reason: a TOS-gate refusal or a dispatch POST error.
+        # Re-run the same config-only gate check (no network call) so the
+        # message states the *actual* reason instead of a guess that may be
+        # a dead end (#1396 review finding 2 — "check daemon logs" pointed
+        # nowhere, since neither failure path logs anything today).
+        from coord.providers import guard_unattended_dispatch  # noqa: PLC0415
+
+        repo_for_provider = config.repo(failed.repo_name)
+        try:
+            guard_unattended_dispatch(
+                spec_provider=None,
+                repo_provider=(
+                    repo_for_provider.provider
+                    if repo_for_provider is not None
+                    else None
+                ),
+                providers_cfg=config.providers,
+                models_cfg=config.models,
+                where="describe_no_candidate_machines (diagnostic re-check)",
+            )
+        except ValueError as exc:
+            return (
+                "a candidate machine was available, but the retry was "
+                f"refused by the provider TOS gate: {exc}"
+            )
+        return (
+            "a candidate machine was available but the retry dispatch "
+            "request failed (network error or the agent was unreachable) "
+            "— re-run `coord retry` to try again"
+        )
+
+    return "no available machine to retry on:\n" + "\n".join(lines)
+
+
+def _record_usage_limit_reason(assignment_id: str | None, entry: dict) -> None:
+    """#1461/#1584/#1797: stamp a usage-limit-kill, terminal-API-error, or
+    auth-shaped-push-failure diagnostic (whichever the agent flagged on
+    *entry*) onto *assignment_id*'s persisted ``failure_reason``.
+
+    Used by :func:`reconcile`'s (``coord resume``) FAILED/ADVISORY branches.
+    ``reconcile_completed_assignments`` — the daemon's own passive tick and
+    the primary production path — does the equivalent inline via
+    ``update_state_fn`` (a raw local write is safe there: that function is
+    daemon-tick-only, never thin-client-reachable). ``reconcile()`` is
+    different — it is called from ``coord resume``, which IS reachable from a
+    thin client (same #906 audit gap `get_issue_test_mode` was fixed for) —
+    so this goes through :func:`coord.state.set_assignment_failure_reason`,
+    which is already daemon-aware (routes to ``POST
+    /assignment-failure-reason`` when a board service is configured), rather
+    than a raw ``get_connection()`` write that would silently land on a thin
+    client's empty local DB instead.
+
+    ``usage_limit_reason`` is tried first, then ``api_error_reason`` (#1584 —
+    a terminal `is_error: true` result event, e.g. "529 Overloaded"; see
+    `coord.agent.AgentAssignment.api_error_reason`), then
+    ``push_failure_reason`` (#1797 — an auth-shaped rejection from the
+    reap-time safety-net push; see `coord.agent._is_auth_push_failure`). The
+    three never coexist on the same entry — a usage-limit kill is detected
+    from a truncated log with no terminal `result` event, an API error is
+    read OFF that terminal `result` event, and a push failure only ever
+    surfaces on an otherwise-clean `exit_code == 0` reap that neither of the
+    other two preempted (see the `elif` chain in `AgentServer._reap`) — so
+    trying them in order never picks the wrong reason.
+
+    This also normalises the row's status to ``'failed'`` (that helper's own
+    behaviour) even when the agent's reap landed on ADVISORY — a usage-limit
+    kill is, per #1461, the ONE terminal state known safe to re-dispatch
+    unchanged, which is what `coord/drive.py`'s FAILED bucket already means;
+    ADVISORY otherwise implies "needs a human look", which a kill does not.
+    (An `api_error_reason` or `push_failure_reason` entry is never ADVISORY —
+    `AgentServer._reap` always lands both directly on FAILED — so this
+    normalisation is a no-op for those cases, not a behaviour change.)
+
+    Best-effort: never raises — a diagnostic write must not break a real
+    status transition.
+    """
+    reason = (
+        entry.get("usage_limit_reason")
+        or entry.get("api_error_reason")
+        or entry.get("push_failure_reason")
+    )
+    if not reason or not assignment_id:
+        return
+    try:
+        from coord.state import set_assignment_failure_reason  # noqa: PLC0415
+
+        set_assignment_failure_reason(assignment_id, reason)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def reconcile(board: Board, config: Config) -> list[str]:
+    """Poll agent servers and update board assignments that have finished.
+
+    Returns assignment_ids whose status changed or were backfilled.
+    """
+    machines_by_name = {m.name: m for m in config.machines}
+
+    # Collect all machines we need to query: those with active assignments
+    # OR completed assignments missing branch info.
+    machines_to_query: set[str] = set()
+    for a in board.active:
+        machines_to_query.add(a.machine_name)
+    for a in board.completed:
+        if a.branch is None and a.assignment_id is not None:
+            machines_to_query.add(a.machine_name)
+
+    # Query each machine once and cache the result.
+    agent_completed: dict[str, dict] = {}
+    reachable_machines: set[str] = set()
+    for machine_name in machines_to_query:
+        machine = machines_by_name.get(machine_name)
+        if machine is None:
+            continue
+        status = _query_agent(machine.host)
+        if status is None:
+            continue
+        reachable_machines.add(machine_name)
+        for e in status.get("completed", []):
+            agent_completed[e["id"]] = e
+
+    changed: list[str] = []
+    newly_failed: list = []  # assignments that just transitioned to failed
+
+    # Sweep for dead interactive (--interactive / claude-pty) sessions before
+    # processing agent-based assignments.  A killed tmux session leaves a
+    # stale "running" board row + orphaned worktree that blocks relaunch.
+    # Reaping here ensures ``coord resume`` / ``coord notify`` clean up
+    # without requiring the user to first run ``coord reattach``.
+    from coord.interactive import (  # noqa: PLC0415
+        reap_stale_interactive_sessions,
+        reap_stale_remote_interactive_sessions,
+    )
+
+    reaped = reap_stale_interactive_sessions(board, config)
+    changed.extend(reaped)
+
+    # #588: probe remote claude-pty sessions older than the configured timeout
+    # threshold.  The local reaper above skips these; this sweep SSHes to the
+    # remote host and finalizes sessions whose tmux has exited.
+    remote_reaped = reap_stale_remote_interactive_sessions(board, config)
+    changed.extend(remote_reaped)
+
+    # Pass 1: transition active assignments that have finished.
+    for a in board.active[:]:
+        if a.assignment_id is None:
+            continue
+
+        # Track unreachable agents for stale detection
+        if a.machine_name in machines_to_query and a.machine_name not in reachable_machines:
+            a.unreachable_count = getattr(a, "unreachable_count", 0) + 1
+            stale_threshold = getattr(config.concurrency, "stale_threshold", 3)
+            if a.unreachable_count >= stale_threshold:
+                board.mark_failed_by_id(a.assignment_id)
+                newly_failed.append(a)
+                changed.append(a.assignment_id)
+            continue
+        elif a.machine_name in reachable_machines:
+            a.unreachable_count = 0
+
+        entry = agent_completed.get(a.assignment_id)
+        if entry is None:
+            continue
+        branch = entry.get("branch")
+        # #1534: read the status through the `done`-refusal helper so a
+        # usage-limit kill the agent mislabelled `done` lands in the `failed`
+        # branch below (which stamps `failure_reason` via
+        # `_record_usage_limit_reason`) instead of being recorded as a clean,
+        # unmarked completion that auto-dispatches a review.
+        agent_status = effective_agent_status(entry)
+        if agent_status == "done":
+            done = board.mark_done_by_id(
+                a.assignment_id,
+                finished_at=entry.get("finished_at"),
+                branch=branch,
+            )
+            if done is not None:
+                if done.type in WORK_LIKE_TYPES:
+                    # Always mark work(-like) completions as pending review so
+                    # the dispatch loop below (and future reconcile passes)
+                    # can pick them up reliably. #930: "mock-author" is
+                    # work-like too — see WORK_LIKE_TYPES. (#1426: Test-stage
+                    # dispatch no longer needs its own "just transitioned"
+                    # list — dispatch_pending_smoke scans the full completed
+                    # backlog, the same shape as dispatch_pending_reviews.)
+                    done.review_state = "pending"
+                elif done.type == "review":
+                    # #1566: `mark_done_by_id` just stamped `done.status =
+                    # "done"` — correct it to "finalizing". The review
+                    # AGENT finished, but the verdict is parsed + persisted
+                    # by `coord notify` (a separate, slower step — see the
+                    # matching comment in `reconcile_completed_assignments`
+                    # above), so calling this row "done" before that lands
+                    # would show a finished review with no verdict, which is
+                    # indistinguishable from a dropped one. `orig.review_state`
+                    # below is intentionally left "done" immediately (that
+                    # field means "the review PROCESS is over", not "verdict
+                    # known" — see #1584 — and `drive_state.TERMINAL_STATUSES`
+                    # not listing "finalizing" is what keeps `coord drive`
+                    # from misreading this row as a dead end in the meantime).
+                    done.status = "finalizing"
+                    # A review finished — update the original work assignment.
+                    orig_id = done.review_of_assignment_id
+                    if orig_id:
+                        orig = board.find_by_id(orig_id)
+                        if orig is not None:
+                            orig.review_state = "done"
+                elif done.type == "conflict-fix":
+                    # #241: re-enqueue the parent merge entry for retry.
+                    _on_conflict_fix_done(done, succeeded=True)
+        elif agent_status == "advisory":
+            # #448: worker exited cleanly but pushed 0 commits. Move to
+            # completed with status "advisory" — NOT "failed" — so that
+            # auto_reassign does not loop on it. Review is also skipped
+            # because there is no code to review on the branch.
+            done = board.mark_done_by_id(
+                a.assignment_id,
+                finished_at=entry.get("finished_at"),
+                branch=branch,
+            )
+            if done is not None:
+                # mark_done_by_id sets status="done"; correct it to "advisory".
+                done.status = "advisory"
+                if done.type in WORK_LIKE_TYPES:
+                    # No code pushed → nothing to review. Set review_state to
+                    # "advisory" so the review-dispatch loop skips this entry.
+                    done.review_state = "advisory"
+                elif done.type == "review":
+                    # Defensive (should not occur after Bug 2 fix): review
+                    # workers that somehow hit advisory still advance the
+                    # original work assignment's review_state.
+                    orig_id = done.review_of_assignment_id
+                    if orig_id:
+                        orig = board.find_by_id(orig_id)
+                        if orig is not None:
+                            orig.review_state = "done"
+                elif done.type == "conflict-fix":
+                    # A conflict-fix with 0 commits didn't resolve anything.
+                    _on_conflict_fix_done(
+                        done, succeeded=False,
+                        agent_entry=entry, board=board, config=config,
+                    )
+                _record_usage_limit_reason(a.assignment_id, entry)
+            # NOTE: do NOT add to newly_failed — prevents auto_reassign loop.
+        else:
+            # Defensive: don't downgrade a DB-done assignment to failed when
+            # the agent reports cancelled (e.g. after POST /cancel cleanup
+            # of a hung reap). The work succeeded; cancellation here is
+            # bookkeeping noise.
+            if (agent_status == "cancelled"
+                    and (a.status or "").lower() == "done"):
+                continue
+            failed = board.mark_failed_by_id(
+                a.assignment_id,
+                finished_at=entry.get("finished_at"),
+            )
+            if failed is not None:
+                newly_failed.append(failed)
+                if failed.type == "conflict-fix":
+                    # #241: the auto-fix didn't work — escalate.  #1291: a
+                    # SEMANTIC give-up buys one stronger attempt first.
+                    _on_conflict_fix_done(
+                        failed, succeeded=False,
+                        agent_entry=entry, board=board, config=config,
+                    )
+                elif failed.type == "review":
+                    # #1584: a review worker that died (transient API error,
+                    # network drop, ...) before producing a verdict is now
+                    # correctly recorded FAILED (not the pre-#1584 silent
+                    # `done`) — but without this, the ORIGINAL work row's
+                    # `review_state` is left at "dispatched" forever, exactly
+                    # like the `done` (above) and `advisory` branches this
+                    # mirrors would leave it if THEY skipped this update.
+                    # "done" (not "failed") to match the existing
+                    # `coord._board_mapping.infer_review_state` convention,
+                    # which already treats a review row's `status in ("done",
+                    # "failed")` identically when inferring this same field —
+                    # the review PROCESS is over either way; `review_verdict`
+                    # (left empty here) is what actually distinguishes "no
+                    # verdict" from an approval, and `coord/drive.py`'s
+                    # `_decide_review` reads `review_status`/`review_verdict`
+                    # directly rather than this field for that distinction.
+                    orig_id = failed.review_of_assignment_id
+                    if orig_id:
+                        orig = board.find_by_id(orig_id)
+                        if orig is not None:
+                            orig.review_state = "done"
+                _record_usage_limit_reason(a.assignment_id, entry)
+        changed.append(a.assignment_id)
+
+    # Dispatch pending reviews for all completed work assignments.
+    # We iterate board.completed (not just newly-done) so that a failed
+    # dispatch on a previous reconcile pass is retried here automatically.
+    #
+    # #465: review fires immediately on work completion — no manual smoke
+    # prerequisite (the interactive smoke gate now lives on merge).
+    # dispatch_pending_reviews() bounds this with a per-pass cap + surge gate
+    # (flood guard, incident 2026-06-08) and applies the #459 active-fix
+    # dedupe, so a backlog unmasking can't flood metered reviews.
+    from coord.review import dispatch_pending_reviews, dispatch_scoped_reviews_for_queue
+
+    for review in dispatch_pending_reviews(board, config):
+        if review.assignment_id is not None:
+            changed.append(review.assignment_id)
+
+    # #1476: a conflict-fix rebase can void an already-approved review by
+    # changing content (patch-id mismatch) without any other new commit —
+    # dispatch a re-review SCOPED to just the resolution delta instead of
+    # leaving the merge entry blocked until a human notices and forces a
+    # full re-review. Independent of dispatch_pending_reviews above (that
+    # one looks at completed WORK rows; this one looks at PENDING merge
+    # queue entries whose approval a rebase just voided).
+    for review in dispatch_scoped_reviews_for_queue(board, config):
+        if review.assignment_id is not None:
+            changed.append(review.assignment_id)
+
+    # Auto-queue smoke tests for any completed work-like assignment still
+    # missing a test verdict. Independent of review dispatch — both can fire
+    # for the same completion.
+    #
+    # #1426: routed through `dispatch_pending_smoke`, the single choke point
+    # `reconcile()` and `coord notify` both call (mirroring
+    # `dispatch_pending_reviews` for the Review stage) — it scans the FULL
+    # completed backlog, not just this pass's `newly_done_work`, so a row
+    # that was missed on an earlier pass (e.g. no capable machine existed
+    # yet) is retried here automatically instead of staying stuck forever.
+    # `dispatch_pending_smoke` itself enforces `smoke_tests.auto_queue`, the
+    # #685 per-issue test-mode gate (test-mode:smoke skips auto-dispatch —
+    # the TUI offers the interactive smoke agent instead), and the
+    # has_active_followup dedupe.
+    from coord.smoke import dispatch_pending_smoke
+
+    for smoke in dispatch_pending_smoke(board, config):
+        if smoke.assignment_id is not None:
+            changed.append(smoke.assignment_id)
+
+    # Auto-reassign failed work assignments to a different machine.
+    if newly_failed and getattr(config.concurrency, "auto_reassign", False):
+        # #1590: one decision point for "was this the weather or the work".
+        from coord.failure_class import classify_failure  # noqa: PLC0415
+
+        for failed_a in newly_failed:
+            if getattr(failed_a, "type", "work") != "work":
+                continue
+            # #1461 review finding 1: a usage-limit kill is an account-wide
+            # exhausted budget, not a per-machine defect — re-dispatching it
+            # onto a *different* machine still burns the same subscription
+            # limit and is guaranteed to die the same way until the reset.
+            # Check the just-seen agent entry (this pass; `_record_usage_
+            # limit_reason` below only writes through to the DB / board
+            # service, it does not mutate this in-memory `failed_a`) AND the
+            # already-persisted `failure_reason` (a prior pass already
+            # stamped it, e.g. after a race with `reconcile_completed_
+            # assignments`'s own tick).
+            #
+            # #1590 deliberately does NOT widen this skip to every
+            # `environmental` class: an API 5xx/network failure genuinely can
+            # be machine-local (one agent host's DNS, one flaky link), so
+            # moving it to another machine is a reasonable first move and the
+            # bounded `auto_reassign` retry still terminates. Only the
+            # usage limit is provably account-wide, and only it is skipped.
+            entry = agent_completed.get(failed_a.assignment_id)
+            classification = classify_failure(
+                usage_limit_reason=(entry or {}).get("usage_limit_reason"),
+                failure_reason=getattr(failed_a, "failure_reason", None),
+            )
+            if classification.is_usage_limit:
+                continue
+            reassigned = _reassign(failed_a, board, config)
+            if reassigned is not None and reassigned.assignment_id is not None:
+                changed.append(reassigned.assignment_id)
+
+    # Pass 2: backfill branch on completed assignments that are missing it.
+    for a in board.completed:
+        if a.branch is not None or a.assignment_id is None:
+            continue
+        entry = agent_completed.get(a.assignment_id)
+        if entry is None:
+            continue
+        branch = entry.get("branch")
+        if branch:
+            a.branch = branch
+            changed.append(a.assignment_id)
+
+    return changed
+
+
+def _post_human_required_comment_raw(
+    entry: QueuedMerge,
+    fix_assignment_id: str,
+    machine_name: str,
+) -> None:
+    """Notify the user on GitHub that a conflict-fix worker gave up."""
+    from coord import github_ops  # noqa: PLC0415
+
+    body = (
+        "## Conflict-fix worker could not auto-resolve\n\n"
+        f"Worker `{fix_assignment_id}` on "
+        f"`{machine_name}` attempted to rebase "
+        f"`{entry.branch}` onto `{entry.target_branch}` and exited "
+        "non-zero. The merge queue entry is now `HUMAN_REQUIRED`.\n\n"
+        f"**Last error:** `{entry.error or 'unknown'}`\n\n"
+        "Manual resolution required: rebase the branch locally and "
+        "`git push --force-with-lease`, then re-run `coord merge`. The "
+        "coordinator will not re-dispatch a conflict-fix for this entry "
+        "in the current session."
+    )
+    try:
+        github_ops.post_issue_comment(entry.repo_github, entry.issue_number, body)
+    except Exception as exc:  # noqa: BLE001 — best-effort notification
+        import logging  # noqa: PLC0415
+        logging.warning(
+            "could not post HUMAN_REQUIRED comment on %s#%d: %s",
+            entry.repo_github, entry.issue_number, exc,
+        )
+
+
+def _post_semantic_escalation_comment(
+    entry: QueuedMerge,
+    *,
+    model: str,
+    escalated_assignment_id: str,
+    machine_name: str,
+) -> None:
+    """#1291: tell the operator a SEMANTIC merge is being attempted.
+
+    A semantic auto-resolution is higher-trust than a mechanical rebase, so
+    it is announced up front — the point is that the human reviews the diff
+    rather than discovering it after the merge.
+    """
+    from coord import github_ops  # noqa: PLC0415
+
+    body = (
+        "## Semantic conflict — escalated for one stronger attempt\n\n"
+        f"The conflict-fix worker judged the conflict on `{entry.branch}` → "
+        f"`{entry.target_branch}` **semantic** and stopped rather than "
+        f"guess.  The coordinator has dispatched ONE escalated attempt with "
+        f"model `{model}` (assignment `{escalated_assignment_id}` on "
+        f"`{machine_name}`).\n\n"
+        f"**Last error:** `{entry.error or 'unknown'}`\n\n"
+        "⚠️ **Review this diff before it merges.** A semantic resolution "
+        "reconciles two different intents — it is a judgement call, not a "
+        "mechanical rebase.  Every gate still applies (tests, CI, "
+        "`verify-merge`, review); nothing is force-merged.  If this attempt "
+        "fails, the merge entry goes to `HUMAN_REQUIRED` — there is no "
+        "second escalation."
+    )
+    try:
+        github_ops.post_issue_comment(entry.repo_github, entry.issue_number, body)
+    except Exception as exc:  # noqa: BLE001 — best-effort notification
+        import logging  # noqa: PLC0415
+        logging.warning(
+            "could not post semantic-escalation comment on %s#%d: %s",
+            entry.repo_github, entry.issue_number, exc,
+        )
+
+
+def _try_semantic_escalation(
+    entry: QueuedMerge,
+    *,
+    board: Board | None,
+    config: Config | None,
+    machine_name: str,
+    stuck_summary: str | None,
+) -> "Assignment | None":
+    """Dispatch the one escalated (semantic) conflict-fix attempt, if allowed.
+
+    Returns the escalated assignment, or ``None`` when the feature is off,
+    the plumbing isn't available, this entry already had its one escalation,
+    or dispatch failed — in every ``None`` case the caller falls through to
+    today's HUMAN_REQUIRED behaviour.
+    """
+    if board is None or config is None:
+        return None
+    pipeline = getattr(config, "pipeline", None)
+    if pipeline is None or not getattr(pipeline, "escalate_semantic_conflicts", False):
+        return None
+
+    from coord.conflict_fix import dispatch_conflict_fix  # noqa: PLC0415
+
+    model = getattr(pipeline, "semantic_conflict_model", None) or "fable"
+    try:
+        return dispatch_conflict_fix(
+            entry,
+            board,
+            config,
+            prefer_machine=machine_name or None,
+            semantic=True,
+            model=model,
+            stuck_summary=stuck_summary,
+        )
+    except Exception as exc:  # noqa: BLE001 — never break reconcile on this
+        import logging  # noqa: PLC0415
+        logging.warning("semantic escalation dispatch failed: %s", exc)
+        return None
+
+
+def on_conflict_fix_done(
+    *,
+    parent_assignment_id: str,
+    fix_assignment_id: str,
+    machine_name: str,
+    succeeded: bool,
+    semantic: bool = False,
+    board: Board | None = None,
+    config: Config | None = None,
+    stuck_summary: str | None = None,
+    usage_limit_reason: str | None = None,
+) -> None:
+    """Update the parent merge entry after a conflict-fix worker finishes.
+
+    On *succeeded*: the merge entry is reset to PENDING so the next
+    ``coord merge`` retries.  On failure: marked HUMAN_REQUIRED so the TUI
+    can surface "manual resolution required", and a comment is posted on
+    the underlying issue so the user is notified outside the TUI too.
+
+    *usage_limit_reason* (#1461 review finding 2): when the conflict-fix
+    worker was killed by the account's usage limit mid-fix, it did not
+    actually fail to resolve anything — frame the parked entry as "wait for
+    the reset", not "manual rebase required", so the operator isn't sent
+    chasing a defect that doesn't exist. Still lands in HUMAN_REQUIRED
+    (rather than auto-retrying, which would just burn more of the same
+    exhausted budget — the #1461 "do not auto-retry immediately" rule
+    applies here too), just with an accurate message.
+
+    Called from both ``reconcile()`` (via mark_done/failed) and
+    ``coord notify`` (via post_transition) — both paths must trigger this
+    so the re-enqueue fires regardless of which polling command runs first.
+    """
+    from coord import merge_queue as mq  # noqa: PLC0415
+
+    items = mq.load_queue()
+    changed = False
+    failed_entry: mq.QueuedMerge | None = None
+    escalated: tuple[mq.QueuedMerge, str, str, str] | None = None
+    for entry in items:
+        if entry.assignment_id != parent_assignment_id:
+            continue
+        if succeeded:
+            entry.state = mq.PENDING
+            entry.error = None
+            entry.last_attempt = None
+        else:
+            existing_error = entry.error or "conflict-fix failed"
+            if usage_limit_reason:
+                entry.state = mq.HUMAN_REQUIRED
+                entry.error = (
+                    f"{existing_error}; conflict-fix worker was killed by "
+                    f"the account's {usage_limit_reason} — not a real "
+                    "conflict. Wait for the reset, then re-run `coord "
+                    "merge` to retry unchanged."
+                )
+                failed_entry = entry
+            else:
+                # #1291: a SEMANTIC give-up gets ONE escalated attempt from a
+                # stronger model before the entry is parked.  Everything
+                # else — and a second semantic failure (the escalated
+                # attempt is itself a conflict-fix row, so
+                # `has_prior_semantic_escalation` blocks it) — behaves
+                # exactly as before.
+                fix = (
+                    _try_semantic_escalation(
+                        entry,
+                        board=board,
+                        config=config,
+                        machine_name=machine_name,
+                        stuck_summary=stuck_summary,
+                    )
+                    if semantic
+                    else None
+                )
+                if fix is not None:
+                    # Stay in CONFLICT, not HUMAN_REQUIRED — the escalated
+                    # worker is in flight.  If it fails, this hook runs
+                    # again and the escalation guard sends the entry to
+                    # HUMAN_REQUIRED.
+                    entry.state = mq.CONFLICT
+                    model = fix.model or "escalated model"
+                    entry.error = (
+                        f"{existing_error}; semantic conflict escalated to "
+                        f"{model} (assignment {fix.assignment_id}) — review "
+                        "the resolution diff before merge."
+                    )
+                    escalated = (
+                        entry, model, fix.assignment_id or "",
+                        fix.machine_name or "",
+                    )
+                else:
+                    entry.state = mq.HUMAN_REQUIRED
+                    entry.error = (
+                        f"{existing_error}; conflict-fix worker did not "
+                        "resolve. Manual rebase required."
+                    )
+                    failed_entry = entry
+        changed = True
+    if changed:
+        mq.save_queue(items)
+
+    if escalated is not None:
+        esc_entry, esc_model, esc_id, esc_machine = escalated
+        _post_semantic_escalation_comment(
+            esc_entry,
+            model=esc_model,
+            escalated_assignment_id=esc_id,
+            machine_name=esc_machine,
+        )
+
+    if failed_entry is not None:
+        _post_human_required_comment_raw(
+            entry=failed_entry,
+            fix_assignment_id=fix_assignment_id,
+            machine_name=machine_name,
+        )
+
+
+def _on_conflict_fix_done(
+    fix_assignment: Assignment,
+    *,
+    succeeded: bool,
+    agent_entry: dict | None = None,
+    board: Board | None = None,
+    config: Config | None = None,
+) -> None:
+    """Thin wrapper used by the reconcile() loop.
+
+    On failure it also asks the worker's log whether the give-up was a
+    SEMANTIC conflict (the ``coord:conflict=semantic`` marker), which — with
+    ``pipeline.escalate_semantic_conflicts`` on — buys one escalated attempt
+    instead of an immediate HUMAN_REQUIRED (#1291).
+
+    #1461 review finding 2: when the conflict-fix worker was itself killed
+    by the account's usage limit (flagged on *agent_entry* by
+    ``AgentServer._reap`` — the same signal ``_record_usage_limit_reason``
+    stamps onto ordinary work assignments), it didn't actually fail to
+    resolve anything. Skip the SEMANTIC-conflict check (there is nothing to
+    diagnose in the transcript — it was cut off, not concluded) and pass the
+    reason through so the parked entry gets an accurate message instead of
+    "manual rebase required".
+    """
+    parent_id = fix_assignment.review_of_assignment_id
+    if not parent_id:
+        return
+
+    usage_limit_reason = (agent_entry or {}).get("usage_limit_reason")
+
+    semantic = False
+    stuck_summary: str | None = None
+    if (
+        not succeeded
+        and not usage_limit_reason
+        and board is not None
+        and config is not None
+    ):
+        semantic, stuck_summary = _semantic_verdict(
+            fix_assignment, agent_entry, config,
+        )
+
+    on_conflict_fix_done(
+        parent_assignment_id=parent_id,
+        fix_assignment_id=fix_assignment.assignment_id or "",
+        machine_name=fix_assignment.machine_name or "",
+        succeeded=succeeded,
+        semantic=semantic,
+        board=board,
+        config=config,
+        stuck_summary=stuck_summary,
+        usage_limit_reason=usage_limit_reason,
+    )
+
+
+def _semantic_verdict(
+    fix_assignment: Assignment,
+    agent_entry: dict | None,
+    config: Config,
+) -> tuple[bool, str | None]:
+    """(is_semantic, stuck line) for a finished conflict-fix worker.
+
+    Best-effort — any failure to read the log means "not semantic", which
+    preserves the pre-#1291 HUMAN_REQUIRED path.
+    """
+    from coord.conflict_fix import detect_semantic_conflict  # noqa: PLC0415
+
+    log_path = (agent_entry or {}).get("log_path")
+    machine = next(
+        (m for m in config.machines if m.name == fix_assignment.machine_name), None,
+    )
+    try:
+        semantic = detect_semantic_conflict(
+            log_path=log_path,
+            host=machine.host if machine is not None else None,
+            assignment_id=fix_assignment.assignment_id,
+        )
+    except Exception:  # noqa: BLE001 — never break reconcile on a log read
+        return False, None
+
+    stuck_summary: str | None = None
+    if semantic:
+        progress = (agent_entry or {}).get("progress") or {}
+        stuck_summary = progress.get("stuck")
+        if not stuck_summary and log_path:
+            try:
+                from coord.progress import parse_progress  # noqa: PLC0415
+                stuck_summary = parse_progress(log_path).stuck
+            except Exception:  # noqa: BLE001
+                stuck_summary = None
+    return semantic, stuck_summary
+
+
+def _extract_issue_number(branch: str) -> int | None:
+    """Extract N from ``issue-{N}-*`` branch names; returns None if no match."""
+    m = re.match(r"issue-(\d+)-", branch)
+    return int(m.group(1)) if m else None
+
+
+def close_stale_prs(
+    config: Config,
+    *,
+    repo: str | None = None,
+    issue: int | None = None,
+    dry_run: bool = False,
+) -> list[str]:
+    """Close open PRs whose work is already on main or whose issue is closed.
+
+    Sweeps every coord-tracked repo (filtered by *repo* / *issue* when given)
+    for OPEN PRs with ``issue-{N}-*`` head branches.  Each PR is classified as
+    stale when either condition holds:
+
+      1. The linked issue N is CLOSED on GitHub.
+      2. The branch has 0 commits ahead of the repo's default branch (catches
+         fast-forward merges; squash/rebase cases are caught by condition 1
+         because coord closes the issue when squash-merging).
+
+    Stale PRs are closed with an explanatory comment.  Non-stale PRs are left
+    untouched.  *dry_run* lists what would change without writing.  Idempotent.
+    """
+    from coord import github_ops  # noqa: PLC0415
+
+    actions: list[str] = []
+
+    for repo_cfg in config.repos:
+        if repo is not None and repo_cfg.name != repo:
+            continue
+
+        try:
+            open_prs = github_ops.list_open_prs(repo_cfg.github)
+        except Exception as exc:  # noqa: BLE001
+            actions.append(
+                f"skip stale-PR sweep for {repo_cfg.name}: could not list PRs ({exc})"
+            )
+            continue
+
+        default_branch = repo_cfg.default_branch or "main"
+        # #934: per-run cache for the issue -> milestone-number lookup, since
+        # this loop re-derives the base branch per-PR below (a milestone
+        # issue's stale-PR base is `feature/ms-NN`, not the repo's flat
+        # `default_branch`). Only populated when the repo opted in.
+        milestone_cache: dict = {}
+
+        for pr in open_prs:
+            branch = pr.get("headRefName") or ""
+            pr_number = pr.get("number")
+            if not branch or pr_number is None:
+                continue
+
+            issue_number = _extract_issue_number(branch)
+            if issue_number is None:
+                continue  # not a coord-managed branch — skip
+            if issue is not None and issue_number != issue:
+                continue
+
+            # Fail-safe classification: when uncertain, leave the PR open.
+            stale_reason: str | None = None
+
+            # #934: this issue's actual base — `feature/ms-NN` when it
+            # belongs to a milestone and the repo opted into the git model,
+            # `repo_cfg.default_branch` (today's behavior) otherwise. The
+            # milestone lookup itself is skipped (no `gh` call) when the
+            # repo hasn't opted in.
+            pr_base = default_branch
+            if getattr(repo_cfg, "develop_branch", None):
+                from coord.branch_model import (  # noqa: PLC0415
+                    fetch_issue_milestone_number,
+                    resolve_base_branch,
+                )
+
+                milestone_number = fetch_issue_milestone_number(
+                    repo_cfg.github, issue_number, cache=milestone_cache,
+                )
+                pr_base = resolve_base_branch(repo_cfg, milestone_number)
+
+            if github_ops.issue_is_closed(repo_cfg.github, issue_number):
+                stale_reason = f"issue #{issue_number} is closed"
+            elif github_ops.branch_is_fully_merged(
+                repo_cfg.github, branch, pr_base
+            ):
+                stale_reason = f"all commits already on {pr_base}"
+
+            if stale_reason is None:
+                continue  # live PR — leave it alone
+
+            actions.append(
+                f"close PR #{pr_number} "
+                f"({repo_cfg.name} #{issue_number}, {branch}): {stale_reason}"
+                + (" [dry-run]" if dry_run else "")
+            )
+
+            if not dry_run:
+                comment = (
+                    f"Closing stale PR — {stale_reason}. "
+                    f"The work for issue #{issue_number} has already landed.\n\n"
+                    f"<!-- coord:stale-close issue={issue_number} -->"
+                )
+                try:
+                    github_ops.close_pr(repo_cfg.github, pr_number, comment=comment)
+                except Exception as exc:  # noqa: BLE001
+                    actions.append(f"  ↳ error closing PR #{pr_number}: {exc}")
+
+    return actions
+
+
+def is_interactive_merge_session(a: object) -> bool:
+    """True when *a* is an interactive ``--merge-of`` session (#1110).
+
+    Interactive merge-prep sessions are dispatched with ``type="conflict-fix"``
+    — the same type the automated #241 conflict-fix worker uses — so a bare
+    ``type`` check can't tell them apart.  What distinguishes them:
+
+    * ``provider_name == "claude-pty"`` — the automated #241 worker runs
+      headless ``claude -p`` and never sets this.
+    * ``review_of_assignment_id`` is set — both share this, but combined with
+      the provider check above it's unambiguous.
+
+    Used by :func:`reconcile_board_merges` (sweep b) and
+    :func:`coord.serve_app._reap_merged_sessions_tick` to scope terminal-state
+    detection / reaping to interactive merge sessions only, without touching
+    automated conflict-fix workers or ordinary work/review/smoke rows.
+    """
+    return (
+        getattr(a, "type", None) == "conflict-fix"
+        and getattr(a, "provider_name", None) == "claude-pty"
+        and getattr(a, "review_of_assignment_id", None) is not None
+    )
+
+
+def reconcile_board_merges(
+    board: Board,
+    config: Config,
+    *,
+    repo: str | None = None,
+    issue: int | None = None,
+    dry_run: bool = False,
+) -> list[str]:
+    """Reconcile done work assignments against git/GitHub reality.
+
+    Two conservative sweeps, returning a list of human-readable action (and
+    skip) strings:
+
+    (a) #611/#1083 branch backfill — runs over ``status='done'`` rows whose
+        ``type`` is in :data:`coord.models.WORK_LIKE_TYPES` (``work``,
+        ``mock-author``, ``test-author``).  A remote interactive work session
+        (or a headless ``test-author``/``mock-author`` session finalized by
+        the #625 passive reconcile tick before its branch was known — #1083)
+        can finish ``status=done`` with ``branch=None`` even though it pushed
+        ``issue-{N}-*`` to origin, which greys the TUI Start review/test/merge
+        buttons (they require a done work assignment WITH a branch) and makes
+        ``coord pr <aid>`` refuse outright.  When exactly one remote branch
+        matches ``issue-{N}-*`` for the issue, the branch is backfilled via
+        :func:`state.update_assignment_branch`.  More than one candidate (or
+        none) is left untouched and logged.  #1574: sweep (b) below now shares
+        this same ``WORK_LIKE_TYPES`` scope (plus interactive merge sessions,
+        #1110) — a landed branch is a landed branch regardless of which
+        work-like type authored it; only ``type='review'`` (and other
+        non-work-like types) stay out of scope for the terminal-merge check.
+
+    (b) #609/#951 record out-of-band merges — work merged directly on GitHub,
+        or a ``merge_queue`` row that drained without flipping the board, is
+        never recorded as ``status='merged'`` so the TUI shows a grey merge
+        box forever.  When :func:`github_ops.work_is_terminal` reports the
+        issue closed OR the PR merged (fail-open), the row is flipped via
+        :func:`state.mark_assignment_merged`.  ``work_is_terminal``'s
+        issue-closed check needs **no branch**, so this still fires even when
+        sweep (a)'s backfill couldn't resolve one (#951) — an unresolved
+        branch must not block the issue-closed fast path.  Because every
+        finished work assignment defaults to ``review_state='pending'``
+        (reconcile's own Pass 1 sets it unconditionally so the review-dispatch
+        loop can pick it up), flipping ``status`` alone leaves that ghost
+        behind — the row keeps surfacing as "[awaiting review]" forever even
+        though it's merged.  So this sweep also clears a lingering
+        ``review_state='pending'`` via :func:`state.mark_work_review_settled`
+        (#951), mirroring how sweep (e) below settles the sibling
+        review/smoke/conflict-fix rows. This only reaches rows still carrying
+        ``status='done'`` — a row whose ``status`` already flipped to
+        ``'merged'`` in a *prior* reconcile run permanently drops out of this
+        sweep's candidate list, so sweep (e) below also matches
+        ``type='work' status='merged' review_state='pending'`` to catch those
+        (#951 round 2).
+
+    Both sweeps are **conservative**: they never act when uncertain and append a
+    skip reason instead.  *repo* filters to a single local repo name.  When
+    *dry_run* is True no writes happen (no ``state.update_*`` calls) — the
+    actions list still describes what *would* change.  The board objects are
+    mutated in place on a real run so a subsequent ``save_board`` agrees with
+    the targeted DB writes.
+    """
+    from coord import github_ops, state  # noqa: PLC0415
+
+    actions: list[str] = []
+    terminal_cache: dict = {}
+    # One remote-branch listing per repo, fetched lazily and reused.
+    branches_by_repo: dict[str, set[str]] = {}
+
+    candidates = [
+        a
+        for a in board.active + board.completed
+        if (a.type in WORK_LIKE_TYPES or is_interactive_merge_session(a))
+        and a.status == "done"
+        and (repo is None or a.repo_name == repo)
+        and (issue is None or a.issue_number == issue)
+    ]
+
+    for a in candidates:
+        repo_cfg = config.repo(a.repo_name)
+        if repo_cfg is None:
+            actions.append(
+                f"skip {a.assignment_id} ({a.repo_name} #{a.issue_number}): "
+                "repo not in config"
+            )
+            continue
+
+        # (a) #611/#1083 — backfill a missing branch from origin.
+        if not a.branch:
+            if repo_cfg.github not in branches_by_repo:
+                branches_by_repo[repo_cfg.github] = (
+                    github_ops.list_remote_branch_names(repo_cfg.github)
+                )
+            prefix = f"issue-{a.issue_number}-"
+            matches = sorted(
+                name
+                for name in branches_by_repo[repo_cfg.github]
+                if name.startswith(prefix)
+            )
+            if len(matches) == 1:
+                branch = matches[0]
+                actions.append(
+                    f"backfill branch {a.assignment_id} "
+                    f"({a.repo_name} #{a.issue_number}) -> {branch}"
+                    + (" [dry-run]" if dry_run else "")
+                )
+                if not dry_run:
+                    a.branch = branch
+                    state.update_assignment_branch(a.assignment_id or "", branch)
+            elif len(matches) > 1:
+                actions.append(
+                    f"skip backfill {a.assignment_id} "
+                    f"({a.repo_name} #{a.issue_number}): "
+                    f"{len(matches)} ambiguous branch candidates {matches}"
+                )
+                # #951: do NOT bail out here — a.branch is still None, but the
+                # issue-closed fast path below needs no branch, so give it a
+                # chance instead of stranding the row forever.
+            else:
+                actions.append(
+                    f"skip backfill {a.assignment_id} "
+                    f"({a.repo_name} #{a.issue_number}): "
+                    f"no remote branch matching {prefix}*"
+                )
+                # #951: same — fall through rather than `continue`.
+
+        # (b) #609/#951 — flip done work whose branch is merged on GitHub, OR
+        # whose issue is closed even when no branch could be resolved above
+        # (work_is_terminal's issue-closed check needs no branch).  #1083
+        # originally scoped this to type='work' only — test-author rows were
+        # added to `candidates` above for sweep (a)'s branch backfill alone,
+        # with the merged/review-settled semantics here deliberately left
+        # out of scope.  #1574: that scope limit meant a `type='test-author'`
+        # row (every oracle-loop acceptance slice, and by the same token
+        # `type='mock-author'`, #930 Gate A) could never reach `status=
+        # 'merged'` no matter how completely its branch landed, since
+        # `work_is_terminal` — branch/commit-scoped since #1150 — already
+        # answers correctly for these rows too.  There's nothing pipeline-
+        # specific about "this branch merged"; widened to the same
+        # :data:`coord.models.WORK_LIKE_TYPES` set sweep (a) uses.  #1110:
+        # interactive merge sessions (type='conflict-fix',
+        # provider_name='claude-pty', review_of_assignment_id set — see
+        # :func:`is_interactive_merge_session`) reach 'done' the same way work
+        # sessions do, so they get the same terminal-detection sweep so the
+        # auto-reaper can pick them up.  Automated #241 conflict-fix workers
+        # are deliberately excluded (they never set provider_name='claude-pty').
+        # `type='review'` rows never reach this point at all — they aren't in
+        # `candidates` (sweep (a) above is also WORK_LIKE_TYPES-scoped).
+        if (
+            a.type in WORK_LIKE_TYPES or is_interactive_merge_session(a)
+        ) and github_ops.work_is_terminal(
+            repo_cfg.github, a.issue_number, a.branch, cache=terminal_cache
+        ):
+            actions.append(
+                f"mark merged {a.assignment_id} "
+                f"({a.repo_name} #{a.issue_number}, {a.branch or 'no branch'})"
+                + (" [dry-run]" if dry_run else "")
+            )
+            if not dry_run:
+                a.status = "merged"
+                state.mark_assignment_merged(a.assignment_id or "")
+                # #951: mark_assignment_merged only flips status — clear a
+                # lingering review_state='pending' ghost too, or the row keeps
+                # showing "[awaiting review]" forever despite being merged.
+                # #1574: kept ``type == "work"``-only (not widened to
+                # WORK_LIKE_TYPES like the status flip above) — a
+                # test-author/mock-author row's review_state is exactly what
+                # sweep (f)'s #1180 wedged-review repair polices (a stray
+                # review_state='done' with no real review behind it), and
+                # settling it to 'done' here would immediately be flagged as
+                # wedged and reset back to 'pending' by that sweep, an
+                # unhelpful churn this fix doesn't need to introduce. Only
+                # `is_interactive_merge_session` rows share sweep (b)'s
+                # type='work' review-settle path, same as before #1574.
+                if a.review_state == "pending" and (
+                    a.type == "work" or is_interactive_merge_session(a)
+                ):
+                    a.review_state = "done"
+                    state.mark_work_review_settled(a.assignment_id or "")
+
+    # (c) #721 — close open PRs whose work has already landed.
+    actions.extend(close_stale_prs(config, repo=repo, issue=issue, dry_run=dry_run))
+
+    # (d) #732 — prune stale merge_queue entries for closed issues / merged PRs.
+    # Runs after the board sweeps so a just-marked-merged assignment doesn't
+    # also appear as a pruned queue entry in the same reconcile run.
+    # repo/issue filters don't apply here — we always scan the full queue, since
+    # a stale entry affects every `coord merge` run regardless of --repo.
+    from coord import merge_queue as mq  # noqa: PLC0415
+
+    pruned = mq.prune_stale_queue_entries(dry_run=dry_run)
+    for entry in pruned:
+        actions.append(
+            f"prune queue entry {entry.assignment_id} "
+            f"({entry.repo_name} #{entry.issue_number}, state={entry.state})"
+            + (" [dry-run]" if dry_run else "")
+        )
+
+    # (e) #894/#951 — settle sibling ghost rows for terminal issues.
+    #
+    # The #609 sweep (b) only processes type='work' status='done' rows, so it
+    # misses three classes of lingering ghost rows for already-merged/closed issues:
+    #
+    #   * type=review/smoke/conflict-fix rows whose status='done' but
+    #     review_state='pending' — the interactive-completion path
+    #     (issue_store._update_local_state) sets review_state='pending' on ALL
+    #     completed assignments so reconcile picks them up like claude -p workers.
+    #     When the parent issue closes before that handoff fires, these rows
+    #     surface as "awaiting review" in coord status / the TUI forever.
+    #
+    #   * status='advisory' rows (any type) — the #609 candidates filter requires
+    #     status='done', so advisory rows are never reached.  They linger in the
+    #     TUI's advisory view after the issue is terminal.
+    #
+    #   * type='work' rows whose status is ALREADY 'merged' but review_state is
+    #     still 'pending' (#951) — once `mark_assignment_merged` (#609) flips a
+    #     row's status to 'merged' (in this run's sweep (b) above, or in a prior
+    #     reconcile run), it permanently drops out of sweep (b)'s
+    #     status=='done' candidates list on every future pass, so a
+    #     review_state='pending' ghost left on it (from #609 predating the
+    #     review_state clear added above, or any other stale write) is never
+    #     revisited. `state.mark_work_review_settled` already handles
+    #     status='merged' rows fine (no status gate) — the gap was purely that
+    #     reconcile() never called it for a row outside sweep (b)'s candidate
+    #     set. This class fixes that: it directly matches the bug report's
+    #     scenario of already-merged+closed issues stuck "awaiting review".
+    #
+    # This sweep is conservative and fail-open:
+    #   - Only acts when work_is_terminal(...) is confirmed true.
+    #   - Uses the terminal_cache populated by sweep (b) to avoid extra GH calls;
+    #     falls back to a fresh check (still fail-open) for ghost rows whose issue
+    #     wasn't processed in sweep (b) (e.g. work already merged in a prior run).
+    #   - Respects the repo/issue filter so --repo/--issue scopes apply.
+    #   - Terminality is keyed on issue_is_closed OR pr_is_merged — NOT branch
+    #     ancestry, so rebase/squash merges with new SHAs are correctly handled.
+
+    # Build a (repo_name, issue_number) → branch lookup from all work rows so
+    # that sibling rows lacking a branch can still pass a branch to work_is_terminal
+    # (enabling the pr_is_merged fast-path in addition to issue_is_closed).
+    work_branch_for: dict[tuple[str, int], str | None] = {}
+    for _a in board.active + board.completed:
+        if _a.type == "work" and _a.issue_number is not None:
+            key = (_a.repo_name, _a.issue_number)
+            # Prefer a non-None branch; first seen wins (done rows come before
+            # merged rows in board.completed, but any non-None branch is fine).
+            if key not in work_branch_for or work_branch_for[key] is None:
+                work_branch_for[key] = _a.branch
+
+    # Identify ghost sibling rows subject to this sweep.
+    ghost_candidates = [
+        a
+        for a in board.active + board.completed
+        if (
+            (
+                a.type in ("review", "smoke", "conflict-fix")
+                and a.status == "done"
+                and a.review_state == "pending"
+            )
+            or a.status == "advisory"
+            or (
+                a.type == "work"
+                and a.status == "merged"
+                and a.review_state == "pending"
+            )
+        )
+        and (repo is None or a.repo_name == repo)
+        and (issue is None or a.issue_number == issue)
+    ]
+
+    for a in ghost_candidates:
+        repo_cfg = config.repo(a.repo_name)
+        if repo_cfg is None:
+            actions.append(
+                f"skip settle {a.assignment_id} "
+                f"({a.repo_name} #{a.issue_number}): repo not in config"
+            )
+            continue
+
+        # Resolve the best available branch for the terminality probe.  The
+        # sibling row itself may carry a branch; fall back to the work row's
+        # branch so the pr_is_merged check fires even when the sibling has none.
+        branch = a.branch or work_branch_for.get((a.repo_name, a.issue_number))
+
+        if not github_ops.work_is_terminal(
+            repo_cfg.github, a.issue_number, branch, cache=terminal_cache
+        ):
+            continue  # Issue still live — leave this row alone.
+
+        if a.status == "advisory":
+            actions.append(
+                f"settle advisory {a.assignment_id} "
+                f"({a.repo_name} #{a.issue_number})"
+                + (" [dry-run]" if dry_run else "")
+            )
+            if not dry_run:
+                a.status = "merged"
+                state.mark_advisory_settled(a.assignment_id or "")
+        elif a.type == "work":
+            # #951: type=work, status=merged, review_state=pending — a row
+            # that already fell out of sweep (b)'s status=='done' candidates
+            # in a prior run (or earlier in this run) but still carries a
+            # review_state ghost. status is already 'merged', so only the
+            # review_state needs settling.
+            actions.append(
+                f"settle work review_state {a.assignment_id} "
+                f"({a.repo_name} #{a.issue_number})"
+                + (" [dry-run]" if dry_run else "")
+            )
+            if not dry_run:
+                a.review_state = "done"
+                state.mark_work_review_settled(a.assignment_id or "")
+        else:
+            # type=review/smoke/conflict-fix, status=done, review_state=pending
+            actions.append(
+                f"settle sibling {a.assignment_id} "
+                f"({a.repo_name} #{a.issue_number}, type={a.type})"
+                + (" [dry-run]" if dry_run else "")
+            )
+            if not dry_run:
+                a.review_state = "done"
+                state.mark_sibling_review_done(a.assignment_id or "")
+
+    # (f) #1180 — un-wedge a test-author/mock-author row whose review_state
+    # was stamped 'done' by a `work_is_terminal` false positive (pre-#1150:
+    # test-author assignments carry issue_number = the milestone's *tracking*
+    # issue — the JIT-slice aliasing convention, #1142/#1150 — so a tracking
+    # issue with ANY historical merged PR could satisfy the then-issue-only
+    # terminal check for an unrelated, still-open slice sharing that number).
+    # #1150 fixed the check going forward (branch/commit-scoped) but did not
+    # repair rows it had already corrupted: a row stuck at
+    # review_state='done' with no verdict and no type='review' assignment
+    # ever dispatched against its branch is invisible to
+    # dispatch_pending_reviews (only review_state in (None, 'pending') is
+    # eligible) AND to the merge gate (requires a real approved type='review'
+    # row) — a permanent deadlock between the two subsystems. Reset
+    # review_state -> 'pending' so the (now-fixed) auto-loop retries a real
+    # review. This is safe even if the branch genuinely IS terminal by now:
+    # the very next dispatch_pending_reviews pass re-checks
+    # work_is_terminal (correctly branch-scoped post-#1150) and re-settles
+    # the row.
+    wedged_review_candidates = [
+        a
+        for a in board.active + board.completed
+        if a.type in ("test-author", "mock-author")
+        and a.review_state == "done"
+        and a.review_verdict is None
+        and a.branch
+        and (repo is None or a.repo_name == repo)
+        and (issue is None or a.issue_number == issue)
+    ]
+    for a in wedged_review_candidates:
+        has_review = any(
+            r.type == "review"
+            and r.repo_name == a.repo_name
+            and r.branch == a.branch
+            # #1566: "finalizing" is a review row whose agent already
+            # finished but whose verdict hasn't been parsed/posted by
+            # `coord notify` yet — it must count as "has a review" here too,
+            # or a review that lands on 'finalizing' the instant its
+            # candidate check above resolves triggers a spurious "repair
+            # wedged review_state ... done -> pending" and a duplicate
+            # dispatch_pending_reviews pass while the first review is still
+            # wrapping up.
+            and r.status in ("done", "finalizing")
+            for r in board.active + board.completed
+        )
+        if has_review:
+            continue
+        actions.append(
+            f"repair wedged review_state {a.assignment_id} "
+            f"({a.repo_name} #{a.issue_number}, branch={a.branch}): "
+            "done -> pending (#1180)"
+            + (" [dry-run]" if dry_run else "")
+        )
+        if not dry_run:
+            a.review_state = "pending"
+            state.reset_wedged_test_author_review(a.assignment_id or "")
+
+    # (g) #1767 — drop drive escalations whose issue resolved out of band.
+    #
+    # `coord merge`'s success path (merge_queue.process()) dismisses the
+    # escalation for the issue it just merged, but that only covers work
+    # that landed *through* `coord merge`. Work merged directly on GitHub,
+    # or closed without merging, never goes through that path — its
+    # escalation (if any) would otherwise linger forever, since nothing
+    # else ever clears one short of `coord escalate dismiss`. Measured on
+    # the live board (#1767): four open escalations, three already stale —
+    # PRs merged and issues closed days earlier, with the escalation the
+    # only record that hadn't caught up.
+    #
+    # Conservative like every sweep above: only acts when `work_is_terminal`
+    # confirms the issue closed or its PR merged, reusing `terminal_cache`
+    # and the `work_branch_for` lookup built for sweep (e) so this costs no
+    # extra `gh` calls for issues already resolved elsewhere in this run.
+    # An escalation on a still-open, still-blocked issue is never touched,
+    # no matter how old — age is not the signal, resolved state is.
+    for _entry in state.list_drive_escalations(repo):
+        _esc_repo = _entry.get("repo_name")
+        _esc_issue = _entry.get("issue_number")
+        if _esc_repo is None or _esc_issue is None:
+            continue
+        if issue is not None and _esc_issue != issue:
+            continue
+        _repo_cfg = config.repo(_esc_repo)
+        if _repo_cfg is None:
+            # Also filters out the drive-queue's own synthetic alert entry
+            # (repo_name="(drive-queue)"), which isn't a real GitHub issue.
+            continue
+        _branch = work_branch_for.get((_esc_repo, _esc_issue))
+        if not github_ops.work_is_terminal(
+            _repo_cfg.github, _esc_issue, _branch, cache=terminal_cache
+        ):
+            continue
+        actions.append(
+            f"dismiss escalation {_esc_repo} #{_esc_issue}: "
+            "issue resolved out of band (#1767)"
+            + (" [dry-run]" if dry_run else "")
+        )
+        if not dry_run:
+            state.dismiss_drive_escalation(_esc_repo, _esc_issue)
+
+    return actions