code-coordinator 0.5.225__tar.gz → 0.5.227__tar.gz

{code_coordinator-0.5.225 → code_coordinator-0.5.227}/CLAUDE.md

@@ -201,6 +201,18 @@ The operator-side counterparts to these rules (dispatch economics, what to send
 versus keep in the coordinator session) are in
 [`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md).
 
+## Rules for the coordinator session
+
+- **Prefer `coord issue` / `coord repo` / `coord milestone` over raw `gh`.** Workers can't reach
+  `gh` at all (deny-listed, above); an interactive coordinator session technically can, but should
+  still route issue/PR/milestone reads and writes through the `coord` seam wherever a subcommand
+  covers it — that's what keeps the backend-agnostic forge seam
+  ([`docs/FORGE_MIGRATION.md`](docs/FORGE_MIGRATION.md)) actually exercised instead of quietly
+  bypassed by the one class of session most likely to reach for `gh` out of habit. Where no `coord`
+  subcommand covers what's needed — a real gap as of 2026-08 (e.g. #2484: `coord issue` has no
+  `list`/`view`) — falling back to `gh` for that one read is fine, but say so and treat it as a gap
+  to flag or file, not a silent workaround.
+
 ## Testing — black-box coverage is the acceptance bar
 
 **Every PR that changes user-visible behavior must ship a black-box test** that drives the *running app* and asserts on its rendered output — not just unit tests on internal functions. The adversarial reviewer reads this file and **rejects behavior-changing PRs that lack one** (pure refactors / internal-only changes are exempt — say so in the PR if that applies). Build the **harness once per repo**; add **tests incrementally, one (or a few) per behavior-changing issue** — do *not* big-bang a full suite. Coverage then grows with churn and ratchets up (PRs add coverage, never remove it). Keep a thin **core smoke set** over the few most-trafficked screens so critical flows stay guarded even by unrelated changes.

{code_coordinator-0.5.225 → code_coordinator-0.5.227}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.225
+Version: 0.5.227
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.225 → code_coordinator-0.5.227}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.225
+Version: 0.5.227
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.225 → code_coordinator-0.5.227}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.225",
+  "tag": "0.5.227",
   "distance": 0,
-  "node": "g58cb8cb15dcd2273e9500a56722b2430b3601848",
+  "node": "g4d72834d6806b7c52ef9e25a887a4ddd33fc5427",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-22"

{code_coordinator-0.5.225 → code_coordinator-0.5.227}/coord/reconcile.py

@@ -203,6 +203,7 @@ def reconcile_completed_assignments(
     agent_status_fn=_query_agent,
     update_state_fn=None,
     capture_plan: bool = True,
+    commits_ahead_fn=None,
 ) -> list[dict]:
     """Dispatch-free passive completion reconcile (#625).
 
@@ -275,9 +276,22 @@ def reconcile_completed_assignments(
     The fix is a positive disproof: ``/status`` carries both ``active`` and
     ``completed``, and an id in NEITHER is a statement about the agent's state,
     not an inference from its silence.  Those — and only those — are
-    reconciled, to ``failed`` (never ``done``) with :data:`NO_AGENT_RECORD_
-    REASON`.  See :func:`agent_has_no_record` and
-    :func:`_reconcile_no_agent_record`.
+    reconciled, never to ``done``, with :data:`NO_AGENT_RECORD_REASON`.  See
+    :func:`agent_has_no_record` and :func:`_reconcile_no_agent_record`.
+
+    **#2553 — "the agent forgot" is not "the work is gone".** The arm above
+    used to record ``failed`` unconditionally, but "the agent has no record"
+    is evidence about the agent's memory, not about the work: a
+    :data:`~coord.models.WORK_LIKE_TYPES` row's own ``branch`` is the one
+    artifact in this path that survives an agent restart, a machine reboot,
+    and the 25-entry completion-history cap, and the board row already has
+    its name. :func:`_reconcile_no_agent_record` now consults it
+    (``commits_ahead_fn``, defaulting to :func:`coord.github_ops.
+    branch_commits_ahead_for_assignment`) before choosing ``failed`` — a
+    branch with real commits ahead of its base lands on ``advisory`` instead
+    (work exists, provenance unverified, needs a human or a verify pass),
+    naming the branch in the reason so an operator doesn't have to go
+    spelunking for it.
 
     Three guards, because **this arm reaps** and #1658 is what getting that
     wrong looks like in production:
@@ -301,6 +315,12 @@ def reconcile_completed_assignments(
     #1421's handler) — and there the workers really are gone, so reconciling
     every row on that machine is the correct answer rather than an accident.
 
+    ``commits_ahead_fn`` (#2553) is the injectable seam for the branch check
+    above — ``fn(assignment, config) -> int | None`` — defaulting to
+    :func:`coord.github_ops.branch_commits_ahead_for_assignment`.  Tests stub
+    it to avoid a real ``gh`` call, exactly like ``agent_status_fn`` stubs the
+    real agent poll.
+
     Returns one dict per reconciled assignment (empty when nothing changed).
     """
     if update_state_fn is None:
@@ -308,6 +328,11 @@ def reconcile_completed_assignments(
 
         update_state_fn = _update_local_state
 
+    if commits_ahead_fn is None:
+        from coord import github_ops  # noqa: PLC0415
+
+        commits_ahead_fn = github_ops.branch_commits_ahead_for_assignment
+
     if board is None:
         from coord.state import build_board  # noqa: PLC0415
 
@@ -352,7 +377,10 @@ def reconcile_completed_assignments(
                 and not is_attended_session(a)
                 and _no_record_grace_elapsed(a)
             ):
-                _reconcile_no_agent_record(a, aid, update_state_fn, reconciled)
+                _reconcile_no_agent_record(
+                    a, aid, update_state_fn, reconciled,
+                    config=config, commits_ahead_fn=commits_ahead_fn,
+                )
             continue
         # #1534: `effective_agent_status` refuses an agent-reported `done`
         # that also carries a usage-limit-kill reason — the daemon's passive
@@ -516,49 +544,123 @@ def reconcile_completed_assignments(
     return reconciled
 
 
+def _no_agent_record_branch_reason(branch: str, ahead: int) -> str:
+    """#2553's operator-facing reason for the "work is on the branch" half.
+
+    Distinct from :data:`NO_AGENT_RECORD_REASON` (the "nothing was pushed"
+    half) precisely so the two are told apart at a glance — the acceptance
+    bar for #2553 is that the reason NAMES the branch rather than making an
+    operator go looking for it, since that branch is the whole point: it is
+    the one artifact of this leg that survived the agent's amnesia.
+    """
+    return (
+        "agent has no record of this assignment (present in neither its "
+        "/status `active` nor `completed` list), but its branch "
+        f"`{branch}` has {ahead} commit(s) ahead of its base — the worker "
+        "pushed real work before the agent's record of it was lost. "
+        "Provenance is unverified (no worker ever reported a verdict), so "
+        "this is recorded as advisory rather than failed: it needs a human "
+        "or a verify pass, not to be discarded (#2553)"
+    )
+
+
 def _reconcile_no_agent_record(
     a: Assignment,
     aid: str,
     update_state_fn,
     reconciled: list[dict],
+    *,
+    config: Config,
+    commits_ahead_fn,
 ) -> None:
-    """#2275: flip a ``running`` row the agent has no record of to ``failed``.
+    """#2275: flip a ``running`` row the agent has no record of to a terminal
+    status — ``failed`` by default, or ``advisory`` when #2553's branch check
+    below finds the row's own branch outlived the agent's amnesia.
 
     Called from :func:`reconcile_completed_assignments` only, and only once
     all three guards there have passed (positive disproof, not attended, past
     the grace window).
 
-    **``failed``, never ``done``.** This leg never reported a verdict, so the
-    one thing that must not happen is a silent flip to ``done`` — that
-    manufactures a pass and every downstream gate (review dispatch, the
-    acceptance gate, the merge queue) then behaves as if a slice exists that
-    nobody ever produced.  A stall is bad; a manufactured pass is worse.
-    ``failure_reason`` is the pinned :data:`NO_AGENT_RECORD_REASON`, so
-    ``coord status``/the TUI/``coord drive`` all name the cause rather than
-    showing a failure with no explanation.
-
-    ``exit_code`` is deliberately left ``None``: there is no reap, so there is
-    no exit code, and writing a fake one would be the same class of lie as
-    writing ``done``.
+    **Never ``done``.** This leg never reported a verdict, so the one thing
+    that must not happen — regardless of which terminal status below fires —
+    is a silent flip to ``done``: that manufactures a pass and every
+    downstream gate (review dispatch, the acceptance gate, the merge queue)
+    then behaves as if a slice exists that nobody ever produced.  A stall is
+    bad; a manufactured pass is worse.
+
+    **#2553 — "the agent forgot" is evidence about the agent, not the work.**
+    Before this, every row reaching here was unconditionally recorded
+    ``failed`` with :data:`NO_AGENT_RECORD_REASON`, even when the row's own
+    ``branch`` carried real, pushed commits — stranding that work with no
+    second chance (most visible on ``test-author``, whose sealed-path rule
+    means nothing else will ever pick the branch back up; see
+    claude-coordinator#2553, ``coord-portal``#129 assignment
+    ``c2120f7206ec``). The branch is the one artifact in this whole path
+    that survives an agent restart, a machine reboot, and the 25-entry
+    completion-history cap, and the board row already names it — so this now
+    asks it directly via ``commits_ahead_fn(a, config)`` before choosing:
+
+    * Only for :data:`~coord.models.WORK_LIKE_TYPES` (``work``,
+      ``mock-author``, ``test-author``) — the types whose ``a.branch`` holds
+      commits THIS row itself produced.  A ``smoke``/``review`` row's
+      ``branch`` is inherited verbatim from the work it rides on (e.g.
+      ``coord.smoke.dispatch_pending_smoke`` stamps
+      ``branch=completed.branch``), so "commits ahead of base" there would
+      just be re-discovering the PARENT's diff, not anything this leg
+      produced — checking it would misfire the #2208 smoke path (a dead Test
+      leg on an already-green branch) into ``advisory`` instead of the
+      environmental clear it needs.
+    * A positive, known commit count (``ahead`` a plain ``int > 0``) is the
+      only thing that moves the needle, to ``advisory`` with
+      :func:`_no_agent_record_branch_reason` (which names the branch).
+      Anything else — no branch, a non-``WORK_LIKE_TYPES`` row, ``ahead ==
+      0``, or ``ahead is None`` (unknown: the repo isn't in ``config``, the
+      remote call failed, ...) — keeps the pre-#2553 behaviour: ``failed``
+      with :data:`NO_AGENT_RECORD_REASON`.  Unknown fails CLOSED toward
+      ``failed`` rather than guessing ``advisory``, matching this arm's
+      existing polarity: a stall is recoverable, a manufactured verdict of
+      either kind is not the thing to guess at.
+    * ``commits_ahead_fn`` is called defensively — a network hiccup querying
+      the remote must not crash the passive daemon tick any more than an
+      unreachable agent does elsewhere in this module.
+
+    ``exit_code`` is deliberately left ``None`` in both cases: there is no
+    reap, so there is no exit code, and writing a fake one would be the same
+    class of lie as writing ``done``.
 
     Kept passive, per this module's #1616 contract — it writes state through
-    the same ``update_state_fn`` seam and dispatches nothing.  The ONE thing
-    it does beyond the write is the #1605 Test-stage propagation, which is not
-    a new side effect: it is the same call the ordinary ``terminal ==
-    "failed"`` path already makes, and skipping it would leave the parent
-    work row's ``test_state="running"`` forever — i.e. it would fix half of
-    #2208 and leave the other half stranded.
+    the same ``update_state_fn`` seam and dispatches nothing.  The commits-
+    ahead check is a read, not a mutation, and it decides between two
+    non-dispatching terminal states — it does not advance the pipeline any
+    more than the write itself does.  The #1605 Test-stage propagation below
+    is not a new side effect either: it is the same call the ordinary
+    ``terminal == "failed"`` path already makes, and skipping it would leave
+    the parent work row's ``test_state="running"`` forever — i.e. it would
+    fix half of #2208 and leave the other half stranded.
     """
+    terminal_status = "failed"
+    reason = NO_AGENT_RECORD_REASON
+    branch = (a.branch or "").strip()
+
+    if branch and a.type in WORK_LIKE_TYPES:
+        try:
+            ahead = commits_ahead_fn(a, config)
+        except Exception:  # noqa: BLE001 — best-effort; unknown → failed below
+            ahead = None
+        if isinstance(ahead, int) and not isinstance(ahead, bool) and ahead > 0:
+            terminal_status = "advisory"
+            reason = _no_agent_record_branch_reason(branch, ahead)
+
     update_state_fn(
         assignment_id=aid,
-        terminal_status="failed",
+        terminal_status=terminal_status,
         branch=a.branch,
         review_state=None,
-        failure_reason=NO_AGENT_RECORD_REASON,
+        failure_reason=reason,
         exit_code=None,
     )
 
-    if a.type == "smoke":
+    if a.type == "smoke" and terminal_status == "failed":
         # #2275: environmental by construction, so state it rather than
         # letting `classify_failure` guess.  `NO_AGENT_RECORD_REASON` is
         # coordinator-authored prose with no wire token in it, so the
@@ -569,9 +671,12 @@ def _reconcile_no_agent_record(
         # vanished worker is the machine's fault, not the work's; clearing
         # the verdict lets `dispatch_pending_smoke` re-run the Test stage on
         # its next tick, which is exactly what a human did in 14 minutes.
+        # (`terminal_status` is always "failed" for `smoke` in practice — the
+        # branch check above only ever fires for WORK_LIKE_TYPES — but the
+        # guard keeps this correct even if that scoping ever changes.)
         propagate_smoke_terminal_failure(
             parent_assignment_id=a.review_of_assignment_id,
-            failure_reason=NO_AGENT_RECORD_REASON,
+            failure_reason=reason,
             environmental=True,
         )
 
@@ -581,9 +686,9 @@ def _reconcile_no_agent_record(
             "issue_number": a.issue_number,
             "repo": a.repo_name,
             "type": a.type,
-            "to_status": "failed",
+            "to_status": terminal_status,
             "plan_captured": False,
-            "reason": NO_AGENT_RECORD_REASON,
+            "reason": reason,
         }
     )
 

{code_coordinator-0.5.225 → code_coordinator-0.5.227}/coord/test_author.py

@@ -247,6 +247,7 @@ def build_test_author_briefing(
     issue_body: str | None,
     driver_entrypoint: str = "",
     driver_mock: str = "",
+    default_branch: str = "main",
 ) -> str:
     """Compose the test-author's briefing (its first/only user message).
 
@@ -255,6 +256,16 @@ def build_test_author_briefing(
     None) authors the full initial suite from the contract; *JIT mode*
     (`issue_number` set) extends just that issue's slice.
 
+    *default_branch* (#2539) is the repo's merge target (``repo_cfg.
+    default_branch or "main"`` at both call sites, the same value already
+    sent as the dispatch payload's ``branch`` field). JIT mode uses it to
+    tell the author to check this branch's mergeability before finishing —
+    a re-dispatch onto an already-authored slice branch (see the #2552
+    RESUMING note appended by `dispatch_test_author`) previously had no
+    instruction to look at `default_branch` at all, so a slice that had
+    gone stale behind a sibling slice's merge would report done with an
+    unresolved conflict still sitting on the PR (coord-portal#132).
+
     *driver_entrypoint* (#1552) is the driver's declared ``entrypoint:`` —
     the crate root a slice must be registered in before the run command can
     see it, for a framework that links tests through an entry point rather
@@ -346,6 +357,43 @@ def build_test_author_briefing(
         parts.append("")
         parts.append(f"ISSUE #{issue_number}: {issue_title or '(no title)'}")
         parts.append(issue_body.strip() if issue_body and issue_body.strip() else "(no body)")
+        parts.append("")
+        parts.append(
+            f"MERGEABILITY (#2539): before you finish — after step 4b's "
+            f"manifest update, before step 6's commit/push — fetch "
+            f"`{default_branch}` (`git fetch origin {default_branch}`) and "
+            f"check whether this branch still merges onto it cleanly (e.g. "
+            f"`git merge --no-commit --no-ff origin/{default_branch}`, then "
+            "`git merge --abort` once you've seen the result — never leave "
+            "the worktree mid-merge). This branch may already carry commits "
+            "from a prior dispatch (see any note above about resuming "
+            "unfinished work), and a sibling slice's PR may have merged "
+            f"into `{default_branch}` since this one was authored. If it "
+            "merges clean, proceed to commit/push as normal. If it "
+            "conflicts:\n"
+            f"  - Confined to `{ACCEPTANCE_DIRNAME}/{ms_dir}/**` (the sealed "
+            "suite YOU already have authoring rights over) AND a clean "
+            "additive collision — the common case is two slices each "
+            "appending their own block to the shared "
+            "`manifest.(yml|json)` (that file documents its own "
+            "convention: later slices MERGE into it) — resolve it "
+            f"yourself: rebase onto `origin/{default_branch}` and keep BOTH "
+            "sides' additions, never dropping the other slice's entries to "
+            "make yours resolve. Re-run step 4's red-check afterward — a "
+            "rebase can shift what the tests see underneath them.\n"
+            "  - Anything else — a conflict that reaches outside "
+            f"`{ACCEPTANCE_DIRNAME}/{ms_dir}/**`, or isn't a clean additive "
+            "collision — do NOT guess a resolution. Abort the merge/rebase, "
+            "leave the branch as it was, and STOP with:\n"
+            f"      STUCK: merge conflict against {default_branch} in "
+            "<file(s)> — outside sealed-authoring scope or not a clean "
+            "additive merge\n"
+            "(same posture a `conflict-fix` session takes for a "
+            "non-rebaseable conflict — you are simply the only dispatch "
+            f"type structurally allowed to touch `{ACCEPTANCE_DIRNAME}/` "
+            "at all, so a conflict confined there is yours to resolve, not "
+            "conflict-fix's)."
+        )
 
     parts.append("")
     parts.append("---")
@@ -499,6 +547,7 @@ def dispatch_test_author(
         issue_number=issue_number,
         issue_title=issue_title,
         issue_body=issue_body,
+        default_branch=repo_cfg.default_branch or "main",
     )
 
     # #1171: milestone-mode dispatches (issue_number is None) keep a single
@@ -889,6 +938,7 @@ def dispatch_test_author_interactive(
         issue_number=issue_number,
         issue_title=issue_title,
         issue_body=issue_body,
+        default_branch=repo_cfg.default_branch or "main",
     )
 
     # Same FIXED title as the headless dispatch (see dispatch_test_author's

{code_coordinator-0.5.225 → code_coordinator-0.5.227}/tests/test_drive.py

@@ -2557,6 +2557,12 @@ def test_a_dead_end_exit_code_reaches_the_drive_exited_audit_row(
     monkeypatch.setattr(
         "coord.drive.Driver._post_escalation_comment", lambda *a, **kw: None
     )
+    # Pin `coord_argv()`'s prefix to a single element so the `c[1:3]` slice
+    # below is decided by the code under test, not by whether `coord` is on
+    # the *host's* $PATH (#2564) — off-PATH, `coord_argv()`'s documented
+    # fallback is `[sys.executable, "-m", "coord.cli"]`, three elements, which
+    # shifts every recorded argv's ["escalate", "record"] out of [1:3].
+    monkeypatch.setenv("COORD_DRIVE_COORD_BIN", "coord")
     payload = board(status="done", test_state="passed")
     payload["assignments"].append({
         "repo_name": REPO,

{code_coordinator-0.5.225 → code_coordinator-0.5.227}/tests/test_reconcile_no_agent_record.py

@@ -23,6 +23,8 @@ import subprocess
 import time
 from pathlib import Path
 
+import pytest
+
 from coord.config import Config
 from coord.models import Assignment, Board, Machine, Repo
 from coord.reconcile import (
@@ -33,6 +35,26 @@ from coord.reconcile import (
 )
 
 
+@pytest.fixture(autouse=True)
+def _no_real_gh_calls(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Safety net for #2553's branch check: every test in this module either
+    doesn't reach `_reconcile_no_agent_record`'s branch check at all, or
+    passes its own `commits_ahead_fn` stub. If a future test reaches it
+    without stubbing, this fails loudly instead of silently shelling out to
+    a real `gh` for a repo (`acme/cc`) that doesn't exist."""
+
+    def _boom(*_a, **_kw):  # pragma: no cover - only runs on regression
+        raise AssertionError(
+            "a test reached the real github_ops.branch_commits_ahead_for_"
+            "assignment default — pass commits_ahead_fn= explicitly instead "
+            "of hitting the network from a unit test"
+        )
+
+    monkeypatch.setattr(
+        "coord.github_ops.branch_commits_ahead_for_assignment", _boom
+    )
+
+
 def _config() -> Config:
     return Config(
         repos=[Repo(name="cc", github="acme/cc")],
@@ -97,6 +119,14 @@ def _status(*, active: list[dict] | None = None, completed: list[dict] | None =
     return {"active": list(active or []), "completed": list(completed or [])}
 
 
+def _zero_ahead(*_a, **_kw) -> int:
+    """Stub `commits_ahead_fn` (#2553): "nothing pushed" — the pre-#2553
+    default. Passed explicitly by every test below that doesn't itself
+    exercise the branch-has-work half, so the no-record arm never shells out
+    to a real `gh` for a repo (`acme/cc`) that doesn't exist."""
+    return 0
+
+
 # ── the fix ────────────────────────────────────────────────────────────────
 
 
@@ -113,6 +143,7 @@ def test_row_in_neither_list_is_reconciled_to_failed_with_pinned_reason() -> Non
         ),
         update_state_fn=rec,
         capture_plan=False,
+        commits_ahead_fn=_zero_ahead,
     )
 
     assert len(rec.calls) == 1
@@ -158,6 +189,7 @@ def test_never_flips_to_done() -> None:
         agent_status_fn=lambda host: _status(),
         update_state_fn=rec,
         capture_plan=False,
+        commits_ahead_fn=_zero_ahead,
     )
     assert [c["terminal_status"] for c in rec.calls] == ["failed", "failed", "failed"]
 
@@ -176,6 +208,7 @@ def test_empty_agent_reconciles_every_row_on_that_machine() -> None:
         agent_status_fn=lambda host: _status(),
         update_state_fn=rec,
         capture_plan=False,
+        commits_ahead_fn=_zero_ahead,
     )
     assert {c["assignment_id"] for c in rec.calls} == {"a1", "a2", "a3"}
     assert len(out) == 3
@@ -210,6 +243,147 @@ def test_restart_recovered_row_takes_the_ordinary_path_not_the_no_record_arm() -
     assert rec.calls[0]["exit_code"] == 1
 
 
+# ── #2553: consult the row's own branch before guessing `failed` ───────────
+#
+# coord-portal#129, assignment c2120f7206ec: a `test-author` leg pushed 948
+# lines to `test-author-ms-4-slice-129` and then the agent forgot about it.
+# The no-record arm recorded `failed` without ever looking at the branch it
+# was already holding the name of, stranding real work behind a sealed path
+# nothing else would ever pick back up.
+
+
+def test_branch_with_pushed_commits_is_advisory_not_failed() -> None:
+    """Acceptance half 1: agent forgot, but the branch has commits ahead of
+    its base → `advisory`, not `failed` — the work must not be discarded."""
+    rec = _Recorder()
+    out = reconcile_completed_assignments(
+        _config(),
+        board=_board(_running("ta1", atype="test-author", branch="test-author-ms-4-slice-129")),
+        agent_status_fn=lambda host: _status(),
+        update_state_fn=rec,
+        capture_plan=False,
+        commits_ahead_fn=lambda a, cfg: 11,
+    )
+
+    assert len(rec.calls) == 1
+    assert rec.calls[0]["terminal_status"] == "advisory"
+    assert rec.calls[0]["branch"] == "test-author-ms-4-slice-129"
+    assert rec.calls[0]["exit_code"] is None
+    reason = rec.calls[0]["failure_reason"]
+    assert reason != NO_AGENT_RECORD_REASON
+    # The operator-facing reason must name the branch — that's the whole
+    # acceptance bar: an operator reading `coord status` shouldn't have to
+    # go spelunking for which branch carries the stranded work.
+    assert "test-author-ms-4-slice-129" in reason
+    assert "11" in reason
+    assert "#2553" in reason
+    assert out[0]["to_status"] == "advisory"
+    assert out[0]["reason"] == reason
+
+
+def test_branch_with_zero_commits_ahead_is_still_failed() -> None:
+    """Acceptance half 2: agent forgot, and nothing was ever pushed → the
+    pre-#2553 `failed` + pinned reason, unchanged."""
+    rec = _Recorder()
+    out = reconcile_completed_assignments(
+        _config(),
+        board=_board(_running("w1", atype="work")),
+        agent_status_fn=lambda host: _status(),
+        update_state_fn=rec,
+        capture_plan=False,
+        commits_ahead_fn=lambda a, cfg: 0,
+    )
+
+    assert rec.calls[0]["terminal_status"] == "failed"
+    assert rec.calls[0]["failure_reason"] == NO_AGENT_RECORD_REASON
+    assert out[0]["to_status"] == "failed"
+
+
+def test_unknown_commits_ahead_fails_closed_to_failed() -> None:
+    """An unconfirmable branch state (network hiccup, unknown repo, ...)
+    must not be guessed as `advisory` — that would be manufacturing a
+    "provenance unverified" verdict on no evidence at all. Fails closed to
+    the pre-#2553 `failed`, matching this arm's existing polarity."""
+    rec = _Recorder()
+    reconcile_completed_assignments(
+        _config(),
+        board=_board(_running("w1", atype="work")),
+        agent_status_fn=lambda host: _status(),
+        update_state_fn=rec,
+        capture_plan=False,
+        commits_ahead_fn=lambda a, cfg: None,
+    )
+    assert rec.calls[0]["terminal_status"] == "failed"
+    assert rec.calls[0]["failure_reason"] == NO_AGENT_RECORD_REASON
+
+
+def test_commits_ahead_fn_raising_fails_closed_to_failed() -> None:
+    """A network error from the branch check must not crash the passive
+    daemon tick — caught and treated as unknown, same as a `None` return."""
+    rec = _Recorder()
+    reconcile_completed_assignments(
+        _config(),
+        board=_board(_running("w1", atype="work")),
+        agent_status_fn=lambda host: _status(),
+        update_state_fn=rec,
+        capture_plan=False,
+        commits_ahead_fn=lambda a, cfg: (_ for _ in ()).throw(RuntimeError("boom")),
+    )
+    assert rec.calls[0]["terminal_status"] == "failed"
+    assert rec.calls[0]["failure_reason"] == NO_AGENT_RECORD_REASON
+
+
+def test_branch_check_is_scoped_to_work_like_types() -> None:
+    """A `smoke`/`review` row's `branch` is inherited verbatim from the work
+    it rides on (see `coord.smoke.dispatch_pending_smoke`), so it is almost
+    always "ahead" for reasons that have nothing to do with what THIS leg
+    produced. The branch check must not run for these types — checked here
+    by making the stub explode if it's ever called for a non-WORK_LIKE_TYPES
+    row, which would otherwise misroute the #2208 smoke path into
+    `advisory` instead of its environmental `failed` clear."""
+
+    def _boom(a, cfg):  # pragma: no cover - only runs on regression
+        raise AssertionError(
+            f"commits_ahead_fn was called for a.type={a.type!r}, which is "
+            "not in WORK_LIKE_TYPES"
+        )
+
+    rec = _Recorder()
+    out = reconcile_completed_assignments(
+        _config(),
+        board=_board(
+            _running("smoke-1", atype="smoke", review_of="work-1"),
+            _running("review-1", atype="review"),
+        ),
+        agent_status_fn=lambda host: _status(),
+        update_state_fn=rec,
+        capture_plan=False,
+        commits_ahead_fn=_boom,
+    )
+    assert [c["terminal_status"] for c in rec.calls] == ["failed", "failed"]
+    assert [o["to_status"] for o in out] == ["failed", "failed"]
+
+
+def test_no_branch_recorded_is_still_failed() -> None:
+    """A row with no branch at all has nothing to consult — straight to the
+    pre-#2553 `failed` path without ever calling `commits_ahead_fn`."""
+
+    def _boom(a, cfg):  # pragma: no cover - only runs on regression
+        raise AssertionError("commits_ahead_fn was called with no branch")
+
+    rec = _Recorder()
+    reconcile_completed_assignments(
+        _config(),
+        board=_board(_running("w1", atype="work", branch=None)),
+        agent_status_fn=lambda host: _status(),
+        update_state_fn=rec,
+        capture_plan=False,
+        commits_ahead_fn=_boom,
+    )
+    assert rec.calls[0]["terminal_status"] == "failed"
+    assert rec.calls[0]["failure_reason"] == NO_AGENT_RECORD_REASON
+
+
 # ── guard rails ────────────────────────────────────────────────────────────
 
 
@@ -316,6 +490,7 @@ def test_grace_window_defers_a_just_dispatched_row() -> None:
         agent_status_fn=lambda host: _status(),
         update_state_fn=rec,
         capture_plan=False,
+        commits_ahead_fn=_zero_ahead,
     )
     assert rec.calls == []
     assert out == []
@@ -328,6 +503,7 @@ def test_grace_window_defers_a_just_dispatched_row() -> None:
         agent_status_fn=lambda host: _status(),
         update_state_fn=rec2,
         capture_plan=False,
+        commits_ahead_fn=_zero_ahead,
     )
     assert [c["assignment_id"] for c in rec2.calls] == ["fresh"]
 
@@ -342,6 +518,7 @@ def test_row_with_no_dispatched_at_is_eligible() -> None:
         agent_status_fn=lambda host: _status(),
         update_state_fn=rec,
         capture_plan=False,
+        commits_ahead_fn=_zero_ahead,
     )
     assert [c["assignment_id"] for c in rec.calls] == ["nodate"]
 
@@ -359,7 +536,13 @@ def test_agent_has_no_record_predicate() -> None:
 
 def test_arm_stays_passive_no_dispatch_no_github(monkeypatch) -> None:
     """#1616's contract: this function reflects state, it never advances the
-    pipeline.  The no-record arm must not become the exception."""
+    pipeline.  The no-record arm must not become the exception.
+
+    #2553's branch check is a READ (`commits_ahead_fn`), not a mutation, and
+    it only decides between two non-dispatching terminal statuses — it does
+    not violate this contract, so it is stubbed here (like `agent_status_fn`
+    always has been) rather than asserted against. What must still never
+    happen is a dispatch (`_reassign`) or a posted comment (`httpx.post`)."""
     import coord.reconcile as rec_mod
 
     def _boom(*a, **kw):  # pragma: no cover - only runs on regression
@@ -375,6 +558,7 @@ def test_arm_stays_passive_no_dispatch_no_github(monkeypatch) -> None:
         agent_status_fn=lambda host: _status(),
         update_state_fn=rec,
         capture_plan=False,
+        commits_ahead_fn=_zero_ahead,
     )
     assert rec.calls[0]["terminal_status"] == "failed"
 
@@ -526,6 +710,7 @@ def test_history_eviction_end_to_end(tmp_path: Path) -> None:
         agent_status_fn=lambda host: payload,
         update_state_fn=rec,
         capture_plan=False,
+        commits_ahead_fn=_zero_ahead,
     )
     server.shutdown()