code-coordinator 0.5.574__tar.gz → 0.5.576__tar.gz

{code_coordinator-0.5.574 → code_coordinator-0.5.576}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.574",
+  "tag": "0.5.576",
   "distance": 0,
-  "node": "g15888500b70e89c6ef17658b665ae3fb70f2b9e6",
+  "node": "g3da50042b74f92cdac51303b6f3672b6568b1a02",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-03"

{code_coordinator-0.5.574 → code_coordinator-0.5.576}/coord/dashboard/server.py

@@ -4329,6 +4329,19 @@ def build_app(
         ``dispatched_at`` is unconditionally stamped at dispatch time by
         every code path, so the bound holds even for a row whose
         ``finished_at`` never got recorded.
+
+        #1277: separately from the age-based cutoff above, a ``failed`` row
+        is also dropped (default view only — ``?include=all`` still returns
+        it) once ``PipelineView.superseded`` says a LATER work assignment
+        for the same ``(repo, issue)`` actually succeeded — a retry/fix/
+        rework attempt shipped the issue, so the earlier failed attempt is
+        pure historical noise, no matter how recent it was. This is
+        deliberately narrower than "the GitHub issue is closed": that would
+        also cover a failure resolved by hand with no coord-dispatched
+        retry, but checking it here would mean a live ``gh`` call on every
+        failed row of every ``/api/pipeline`` request — left as a follow-up
+        rather than risking the hot GET path on GitHub API latency/rate
+        limits (and `compute_pipeline`'s pure-computation contract above).
         """
         from dataclasses import asdict
 
@@ -4377,6 +4390,15 @@ def build_app(
                 ts = pv.finished_at if pv.finished_at is not None else a.dispatched_at
                 if ts is not None and ts < cutoff:
                     continue
+            # #1277: a `failed` row whose issue later shipped via a
+            # different (retry/fix/rework) assignment is pure historical
+            # noise on the default view — suppress it regardless of its own
+            # age (unlike the recency cutoff above, this doesn't depend on
+            # how recently the failure happened, only on whether a later
+            # attempt superseded it). `?include=all` still returns it — this
+            # is a display-layer filter, the DB row is untouched (#1041).
+            if cutoff is not None and pv.superseded:
+                continue
             rev_aid = review_by_work.get(a.assignment_id)
             if rev_aid:
                 found = (

{code_coordinator-0.5.574 → code_coordinator-0.5.576}/coord/pipeline.py

@@ -114,6 +114,20 @@ class PipelineView:
     # recently made progress) — see compute_pipeline for the derivation.
     # None only when nothing involved has finished yet (still coding).
     finished_at: float | None = None
+    # #1277: True when this is a `current_stage == "failed"` row AND a later
+    # work assignment for the same (repo_name, issue_number) reached a
+    # genuinely successful terminal status ("done"/"merged") — i.e. a
+    # retry/fix/rework attempt superseded this failure and the issue
+    # shipped. Always False for any other current_stage. Pure — derived
+    # entirely from the already-passed-in `board` (every work assignment
+    # ever dispatched for this issue), no I/O — so it recomputes fresh on
+    # every call rather than needing a persisted flag, and self-corrects the
+    # instant a pending retry's own status flips to "done"/"merged". The
+    # dashboard (coord/dashboard/server.py's api_pipeline) uses this to
+    # suppress stale failed rows from the default view while leaving the DB
+    # rows themselves untouched (#1041 audit trail) — `?include=all` still
+    # surfaces them.
+    superseded: bool = False
 
 
 # ── GateSpec registry (#3261 S-2) ────────────────────────────────────────────
@@ -602,6 +616,32 @@ def compute_pipeline(
         review_of_assignment_id=assignment.review_of_assignment_id,
     )
 
+    # #1277: a failed row is "superseded" once a LATER work assignment for
+    # the same (repo, issue) actually succeeded ("done"/"merged" — not
+    # merely dispatched again; an in-flight retry doesn't supersede anything
+    # until it itself lands). Ordered by `dispatched_at` — the attempt
+    # order, and per the #2066 docstring above the one timestamp every
+    # assignment is unconditionally stamped with, unlike `finished_at`.
+    # Scoped to `current_stage == "failed"` only: a review/smoke failure on
+    # the SAME work assignment (review_failed/smoke_failed) isn't this kind
+    # of "stale duplicate row" — the work assignment itself is still the
+    # live one.
+    superseded = False
+    if current_stage == "failed":
+        this_dispatched = assignment.dispatched_at
+        for other in all_assignments:
+            if (
+                other.assignment_id != aid
+                and other.type in ("work", None, "")
+                and other.repo_name == assignment.repo_name
+                and other.issue_number == assignment.issue_number
+                and other.status in ("done", "merged")
+                and other.dispatched_at is not None
+                and (this_dispatched is None or other.dispatched_at > this_dispatched)
+            ):
+                superseded = True
+                break
+
     # #1218: most-recent finished_at across the work assignment and any
     # linked review/smoke assignment — whichever last made progress. This is
     # what the dashboard sorts the collapsed "Work done" section by, so it
@@ -641,4 +681,5 @@ def compute_pipeline(
         needs_attention_reason=needs_attention_reason,
         needs_attention_detail=needs_attention_detail,
         finished_at=finished_at,
+        superseded=superseded,
     )

{code_coordinator-0.5.574 → code_coordinator-0.5.576}/coord/reports.py

@@ -1108,8 +1108,14 @@ def run_issue_activity(
 # `(generated_at, generated_at)`.  `drive_queue` has no `completed_at` and
 # `coord/drive_queue.py` emits no audit events, so there is no data source
 # for a queue *history* report — see this issue's "Out of scope".
+#
+# #1909: the rows are ordered by LIFECYCLE BAND, not by raw `position` — see
+# `_drive_queue_lifecycle_sort_key` below. `band` is a derived display column
+# (not a `drive_queue` row field) naming which of the three bands a row fell
+# into, so a client never has to infer it from `state` alone.
 
 DRIVE_QUEUE_STATUS_COLUMNS = [
+    "band",
     "position",
     "repo",
     "issue",
@@ -1128,6 +1134,12 @@ DRIVE_QUEUE_STATUS_COLUMNS = [
 
 # One entry per DRIVE_QUEUE_STATUS_COLUMNS entry, same order (#1760).
 DRIVE_QUEUE_STATUS_COLUMN_META = [
+    # #1909: the band an entry's row was sorted into — "terminal" (done and
+    # the other states in `TERMINAL_QUEUE_STATES`), "running", or "pending"
+    # (everything still waiting to launch). Named distinctly from `state`
+    # because several raw states fold into one band (`done`/`merged-partial`/
+    # `blocked`/`failed` all read `terminal`).
+    ColumnMeta(id="band", label="Band", kind="enum"),
     ColumnMeta(id="position", label="Pos", kind="int", align="right"),
     ColumnMeta(id="repo", label="Repo", kind="text"),
     ColumnMeta(id="issue", label="Issue", kind="int", align="right"),
@@ -1151,6 +1163,70 @@ DRIVE_QUEUE_STATUS_COLUMN_META = [
 # attempt is the thing an operator most wants shouted at them.
 _RETRIED_ATTEMPTS_THRESHOLD = 1
 
+# #1909: the three lifecycle bands, in display order. "terminal" (done and
+# the rest of `TERMINAL_QUEUE_STATES`) sorts first, then "running", then
+# "pending" — literally the order the issue names them in, not "what the
+# operator probably cares about most" (that question belongs to #1866's
+# live Queue panel, not this report).
+_LIFECYCLE_BAND_RANK = {"terminal": 0, "running": 1, "pending": 2}
+
+
+def _drive_queue_lifecycle_band(
+    state: str, terminal_states: frozenset[str], running_state: str
+) -> str:
+    """The #1909 band label for one row's raw ``state``.
+
+    Always one of ``"terminal"``/``"running"``/``"pending"`` — never
+    anything else — so a client can switch on it exhaustively without a
+    fallback case. ``hold_state`` (a fired deploy gate) is deliberately NOT
+    consulted here: it is orthogonal to ``state`` (see `coord/drive_queue.py`
+    around `HOLD_FIRED`) — a held entry's `state` stays `waiting`, so it
+    already lands in `pending` without any extra check, which is exactly
+    the issue's "waiting (and any held)" wording.
+    """
+    if state == running_state:
+        return "running"
+    if state in terminal_states:
+        return "terminal"
+    return "pending"
+
+
+def _drive_queue_lifecycle_sort_key(row: Mapping[str, Any]) -> tuple[int, float, int]:
+    """#1909's row ordering: ``(band rank, recency/0, position)``.
+
+    * **terminal** — most-recently-finished first. The recency proxy is
+      whichever of ``reason_at`` / ``launched_at`` / ``enqueued_at`` is
+      present, in that priority. ``reason_at`` is stamped by
+      ``_update_drive_queue_entry_local`` on every ``last_reason`` write, and
+      every call site in ``coord/drive_queue.py`` that flips a row terminal
+      writes ``last_reason`` in the SAME update (e.g. every
+      ``_merge_landed_state`` caller) — so ``reason_at`` reads as "when this
+      row last changed", which for a terminal row IS when it finished.
+      Negated so the largest (most recent) timestamp sorts first; a row
+      with none of the three (predates the columns) falls back to ``0.0``,
+      the oldest possible reading, and ties within that are broken by
+      ``position`` descending (the more recently enqueued of two
+      equally-undated rows is still the newer one).
+    * **running** — no ordering requirement from the issue; broken by
+      ``position`` ascending for determinism (typically a single row).
+    * **pending** — ``position`` ascending, exactly the order
+      ``plan_tick``'s launch walk (`_resolve_prereqs` in
+      `coord/drive_queue.py`) will reach them. This is the band the issue
+      calls "the important one".
+    """
+    band = row["band"]
+    position = int(row["position"])
+    if band == "terminal":
+        recency = row.get("reason_at")
+        if recency is None:
+            recency = row.get("launched_at")
+        if recency is None:
+            recency = row.get("enqueued_at")
+        if recency is None:
+            recency = 0.0
+        return (_LIFECYCLE_BAND_RANK[band], -float(recency), -position)
+    return (_LIFECYCLE_BAND_RANK[band], 0.0, position)
+
 
 def fold_drive_queue_status(
     entries: Iterable[Mapping[str, Any]],
@@ -1167,21 +1243,42 @@ def fold_drive_queue_status(
     caller's clock reading, reused verbatim for both ends of ``window`` since
     a live snapshot has no meaningful range.
 
-    ``entries`` arrives pre-ordered (``list_drive_queue`` is
-    ``ORDER BY position, id``) — this fold does not re-sort.
+    ``entries`` arrives pre-ordered (``list_drive_queue`` is ``ORDER BY
+    position, id``), but **this fold DOES re-sort** (#1909) — deliberately
+    relaxing the "never re-sorts" contract this docstring used to state.
+    Raw `position` order interleaves finished work with what hasn't run
+    yet, which reads as noise (see the issue's own reproduction). Output
+    rows are grouped into three lifecycle bands instead — terminal (done
+    and the rest of `TERMINAL_QUEUE_STATES`, most-recently-finished first),
+    running, then pending (everything else, ascending `position` — the
+    exact order `plan_tick`'s launch walk, `_resolve_prereqs` in
+    `coord/drive_queue.py`, will reach them). See
+    :func:`_drive_queue_lifecycle_sort_key` for the exact key. Each row
+    also carries a derived ``band`` column naming which band it landed in.
     """
+    from coord.drive_queue import (  # noqa: PLC0415
+        STATE_BLOCKED,
+        STATE_DONE,
+        STATE_FAILED,
+        STATE_RUNNING,
+        STATE_WAITING,
+        TERMINAL_QUEUE_STATES,
+    )
+
     title_map = dict(titles or {})
     rows: list[dict[str, Any]] = []
     for entry in entries:
         repo = str(entry.get("repo_name") or "")
         issue = int(entry.get("issue_number") or 0)
+        state = entry.get("state") or ""
         rows.append(
             {
+                "band": _drive_queue_lifecycle_band(state, TERMINAL_QUEUE_STATES, STATE_RUNNING),
                 "position": int(entry.get("position") or 0),
                 "repo": repo,
                 "issue": issue,
                 "title": title_map.get((repo, issue)),
-                "state": entry.get("state") or "",
+                "state": state,
                 "machine": entry.get("machine") or "",
                 "attempts": int(entry.get("attempts") or 0),
                 "deferrals": int(entry.get("deferrals") or 0),
@@ -1207,19 +1304,16 @@ def fold_drive_queue_status(
             }
         )
 
+    # #1909: lifecycle-band order, not the raw `position`/`id` order
+    # `entries` arrived in — see `_drive_queue_lifecycle_sort_key`. `position`
+    # is unique per entry, so the key never actually ties; `sort`'s stability
+    # only matters if a future band grows a coarser key.
+    rows.sort(key=_drive_queue_lifecycle_sort_key)
+
     notes: list[str] = []
     if not rows:
         notes.append("The drive queue is empty.")
     else:
-        from coord.drive_queue import (  # noqa: PLC0415
-            STATE_BLOCKED,
-            STATE_DONE,
-            STATE_FAILED,
-            STATE_RUNNING,
-            STATE_WAITING,
-            TERMINAL_QUEUE_STATES,
-        )
-
         counts: dict[str, int] = {}
         for r in rows:
             counts[r["state"]] = counts.get(r["state"], 0) + 1
@@ -4604,11 +4698,12 @@ DRIVE_QUEUE_STATUS = ReportDef(
     id="drive-queue-status",
     title="Drive Queue Status",
     description=(
-        "A live snapshot of the drive queue — one row per queued entry in "
-        "run order, with its state, machine pin, attempts/deferrals and the "
-        "tick's own last_reason. A snapshot, not a history: `drive_queue` "
-        "has no `completed_at`, so this shows what is queued now, not what "
-        "the queue has processed."
+        "A live snapshot of the drive queue — one row per queued entry, "
+        "grouped by lifecycle band (terminal, then running, then pending in "
+        "the order it will actually run), with its state, machine pin, "
+        "attempts/deferrals and the tick's own last_reason. A snapshot, not "
+        "a history: `drive_queue` has no `completed_at`, so this shows what "
+        "is queued now, not what the queue has processed."
     ),
     params=(
         ReportParam(

{code_coordinator-0.5.574 → code_coordinator-0.5.576}/tests/test_pipeline.py

@@ -524,6 +524,85 @@ class TestFinishedAtField:
         assert pv.finished_at == 100.0
 
 
+# ── #1277: superseded field (stale failed row hidden after a later success) ─
+
+
+class TestSupersededField:
+    def test_failed_with_no_sibling_is_not_superseded(self) -> None:
+        a = _work(aid="work-1", status="failed")
+        pv = compute_pipeline(a, _board(a), [], _config())
+        assert pv.current_stage == "failed"
+        assert pv.superseded is False
+
+    def test_failed_superseded_by_later_successful_retry(self) -> None:
+        """The canonical #790 shape: a failed attempt, then a later retry
+        (different assignment_id, same repo+issue) that actually succeeded."""
+        failed = _work(aid="work-1", status="failed")
+        failed.dispatched_at = 100.0
+        retry = _work(aid="work-2", status="done")
+        retry.dispatched_at = 200.0
+        board = Board(active=[], completed=[failed, retry])
+        pv = compute_pipeline(failed, board, [], _config())
+        assert pv.current_stage == "failed"
+        assert pv.superseded is True
+
+    def test_merged_retry_also_supersedes(self) -> None:
+        failed = _work(aid="work-1", status="failed")
+        failed.dispatched_at = 100.0
+        retry = _work(aid="work-2", status="merged")
+        retry.dispatched_at = 200.0
+        board = Board(active=[], completed=[failed, retry])
+        pv = compute_pipeline(failed, board, [], _config())
+        assert pv.superseded is True
+
+    def test_earlier_success_does_not_supersede_a_later_failure(self) -> None:
+        """Ordering matters: a success dispatched BEFORE this failure doesn't
+        make the failure stale — it's the live, most-recent attempt."""
+        earlier_success = _work(aid="work-1", status="done")
+        earlier_success.dispatched_at = 100.0
+        failed = _work(aid="work-2", status="failed")
+        failed.dispatched_at = 200.0
+        board = Board(active=[], completed=[earlier_success, failed])
+        pv = compute_pipeline(failed, board, [], _config())
+        assert pv.current_stage == "failed"
+        assert pv.superseded is False
+
+    def test_later_in_flight_retry_does_not_supersede_yet(self) -> None:
+        """A retry that hasn't itself succeeded (still running/pending)
+        doesn't retroactively clear the earlier failure — only an actual
+        success does."""
+        failed = _work(aid="work-1", status="failed")
+        failed.dispatched_at = 100.0
+        retry = _work(aid="work-2", status="running")
+        retry.dispatched_at = 200.0
+        board = Board(active=[retry], completed=[failed])
+        pv = compute_pipeline(failed, board, [], _config())
+        assert pv.superseded is False
+
+    def test_sibling_in_a_different_repo_does_not_supersede(self) -> None:
+        failed = _work(aid="work-1", status="failed")
+        failed.dispatched_at = 100.0
+        other_repo_success = Assignment(
+            machine_name="laptop", repo_name="other-repo",
+            issue_number=42, issue_title="Fix auth", assignment_id="work-2",
+            status="done", type="work", dispatched_at=200.0,
+        )
+        board = Board(active=[], completed=[failed, other_repo_success])
+        pv = compute_pipeline(failed, board, [], _config())
+        assert pv.superseded is False
+
+    def test_non_failed_stage_is_never_superseded(self) -> None:
+        """superseded is scoped to current_stage == 'failed' — a review/smoke
+        failure on the SAME still-live work assignment isn't this kind of
+        stale duplicate row."""
+        a = _work(status="done")
+        smk = _smoke(of_aid="work-1", status="failed")
+        board = Board(active=[], completed=[a, smk])
+        pv = compute_pipeline(a, board, [], _config())
+        assert pv.current_stage == "smoke_failed"
+        assert pv.superseded is False
+
+
 # ── #846: needs_attention field ─────────────────────────────────────────────
 
 
@@ -992,6 +1071,94 @@ class TestPipelineRetention:
         assert r.json() == []
 
 
+class TestPipelineAPISupersededFiltering:
+    """#1277: /api/pipeline suppresses a `failed` row by default once a
+    later retry/fix for the same (repo, issue) actually succeeded — one
+    current-stage row per issue, not a growing pile of dead retries."""
+
+    def test_failed_then_succeeded_yields_one_row_by_default(self) -> None:
+        """The exact scenario from the issue: two assignments for the same
+        issue — one failed, one later succeeded — yields a single
+        current-stage pipeline row, not two."""
+        import time
+
+        now = time.time()
+        failed = Assignment(
+            machine_name="laptop", repo_name="api",
+            issue_number=790, issue_title="Flaky thing",
+            assignment_id="w-fail", status="failed", type="work",
+            dispatched_at=now - 3600, finished_at=now - 3600,
+        )
+        succeeded = Assignment(
+            machine_name="laptop", repo_name="api",
+            issue_number=790, issue_title="Flaky thing",
+            assignment_id="w-retry", status="done", type="work",
+            dispatched_at=now - 1800, finished_at=now - 1800,
+        )
+        board = Board(active=[], completed=[failed, succeeded])
+        client = _dashboard_client()
+        with (
+            patch("coord.dashboard.server.read_board", return_value=board),
+            patch("coord.merge_queue.load_queue", return_value=[]),
+        ):
+            r = client.get("/api/pipeline")
+        assert r.status_code == 200
+        data = r.json()
+        ids = [pv["assignment_id"] for pv in data]
+        assert ids == ["w-retry"]
+
+    def test_include_all_still_returns_the_superseded_failed_row(self) -> None:
+        """Display-layer filter, not a delete (#1041): the full history is
+        still reachable via ?include=all."""
+        import time
+
+        now = time.time()
+        failed = Assignment(
+            machine_name="laptop", repo_name="api",
+            issue_number=790, issue_title="Flaky thing",
+            assignment_id="w-fail", status="failed", type="work",
+            dispatched_at=now - 3600, finished_at=now - 3600,
+        )
+        succeeded = Assignment(
+            machine_name="laptop", repo_name="api",
+            issue_number=790, issue_title="Flaky thing",
+            assignment_id="w-retry", status="done", type="work",
+            dispatched_at=now - 1800, finished_at=now - 1800,
+        )
+        board = Board(active=[], completed=[failed, succeeded])
+        client = _dashboard_client()
+        with (
+            patch("coord.dashboard.server.read_board", return_value=board),
+            patch("coord.merge_queue.load_queue", return_value=[]),
+        ):
+            r = client.get("/api/pipeline?include=all")
+        assert r.status_code == 200
+        ids = {pv["assignment_id"] for pv in r.json()}
+        assert ids == {"w-fail", "w-retry"}
+
+    def test_still_open_failure_with_no_later_success_stays_visible(self) -> None:
+        """#772's shape — only failed row for an issue, never retried — must
+        not be swept away by this filter."""
+        import time
+
+        failed = Assignment(
+            machine_name="laptop", repo_name="api",
+            issue_number=772, issue_title="Optional thing",
+            assignment_id="w-fail-only", status="failed", type="work",
+            dispatched_at=time.time() - 3600, finished_at=time.time() - 3600,
+        )
+        board = Board(active=[], completed=[failed])
+        client = _dashboard_client()
+        with (
+            patch("coord.dashboard.server.read_board", return_value=board),
+            patch("coord.merge_queue.load_queue", return_value=[]),
+        ):
+            r = client.get("/api/pipeline")
+        assert r.status_code == 200
+        ids = [pv["assignment_id"] for pv in r.json()]
+        assert ids == ["w-fail-only"]
+
+
 class TestPipelineActionAPI:
     def test_missing_fields_returns_400(self) -> None:
         client = _dashboard_client()

{code_coordinator-0.5.574 → code_coordinator-0.5.576}/tests/test_reports.py

@@ -749,7 +749,7 @@ class TestFoldDriveQueueStatus:
         result = fold_drive_queue_status([_dq_row(1)], 1000.0)
         assert [m.id for m in result.column_meta] == result.columns
         assert result.columns == [
-            "position", "repo", "issue", "title", "state", "machine",
+            "band", "position", "repo", "issue", "title", "state", "machine",
             "attempts", "deferrals", "last_reason", "reason_at", "enqueued_at",
             "launched_at", "hold_state", "after",
         ]
@@ -816,12 +816,110 @@ class TestFoldDriveQueueStatus:
         assert "0 entries queued" in headline
         assert "3 done" in headline
 
-    def test_run_order_preserved_from_input_not_resorted(self) -> None:
-        # list_drive_queue already returns ORDER BY position, id — the fold
-        # must not reorder it.
+    def test_same_band_rows_sorted_by_position_ascending(self) -> None:
+        # #1909: all three rows are `waiting` (same band, "pending"), so the
+        # fold's re-sort collapses to position order regardless of the
+        # input's own order — unlike the pre-#1909 "never re-sorts" fold,
+        # which would have preserved the input's [3, 1, 2].
         rows = [_dq_row(3, position=2), _dq_row(1, position=0), _dq_row(2, position=1)]
         result = fold_drive_queue_status(rows, 1000.0)
-        assert [r["issue"] for r in result.rows] == [3, 1, 2]
+        assert [r["issue"] for r in result.rows] == [1, 2, 3]
+
+    def test_lifecycle_bands_ordered_terminal_then_running_then_pending(self) -> None:
+        # #1909's own regression shape: a running item, pending entries
+        # interleaved with done ones at arbitrary positions, and a blocked
+        # (terminal) row thrown in — the fold must emit terminal rows first,
+        # then running, then pending in ascending position, regardless of
+        # the raw position/arrival order.
+        rows = [
+            _dq_row(1891, position=0, state_="running"),
+            _dq_row(1904, position=1, state_="waiting"),
+            _dq_row(9001, position=2, state_="done", reason_at=500.0),
+            _dq_row(1895, position=28, state_="waiting"),
+            _dq_row(1156, position=29, state_="waiting"),
+            _dq_row(1547, position=30, state_="blocked", reason_at=600.0),
+            _dq_row(1889, position=31, state_="done", reason_at=700.0),
+        ]
+        result = fold_drive_queue_status(rows, 1000.0)
+        bands = [r["band"] for r in result.rows]
+        issues = [r["issue"] for r in result.rows]
+        # Terminal rows (done, blocked) come first — most-recently-finished
+        # (highest reason_at) first — then the single running row, then the
+        # pending rows in ascending position.
+        assert issues == [1889, 1547, 9001, 1891, 1904, 1895, 1156]
+        assert bands == [
+            "terminal", "terminal", "terminal",
+            "running",
+            "pending", "pending", "pending",
+        ]
+
+    def test_terminal_band_most_recently_finished_first(self) -> None:
+        rows = [
+            _dq_row(1, state_="done", reason_at=100.0),
+            _dq_row(2, state_="done", reason_at=300.0),
+            _dq_row(3, state_="done", reason_at=200.0),
+        ]
+        result = fold_drive_queue_status(rows, 1000.0)
+        assert [r["issue"] for r in result.rows] == [2, 3, 1]
+
+    def test_terminal_band_falls_back_to_launched_at_when_no_reason_at(self) -> None:
+        rows = [
+            _dq_row(1, state_="done", launched_at=50.0),
+            _dq_row(2, state_="done", launched_at=90.0),
+        ]
+        result = fold_drive_queue_status(rows, 1000.0)
+        assert [r["issue"] for r in result.rows] == [2, 1]
+
+    def test_terminal_band_falls_back_to_enqueued_at_when_no_reason_at_or_launched_at(
+        self,
+    ) -> None:
+        rows = [
+            _dq_row(1, state_="done", launched_at=None, enqueued_at=10.0),
+            _dq_row(2, state_="done", launched_at=None, enqueued_at=20.0),
+        ]
+        result = fold_drive_queue_status(rows, 1000.0)
+        assert [r["issue"] for r in result.rows] == [2, 1]
+
+    def test_pending_band_order_matches_the_launch_walk(self) -> None:
+        # The issue's own framing: pending must be in ascending `position`
+        # — the order `plan_tick`'s launch walk reaches them — regardless
+        # of state (`waiting` vs `parked`) or input arrival order.
+        rows = [
+            _dq_row(30, position=3, state_="waiting"),
+            _dq_row(10, position=1, state_="parked"),
+            _dq_row(20, position=2, state_="waiting"),
+        ]
+        result = fold_drive_queue_status(rows, 1000.0)
+        assert [r["issue"] for r in result.rows] == [10, 20, 30]
+
+    def test_held_entry_still_bands_pending_not_a_fourth_band(self) -> None:
+        # `hold_state` is orthogonal to `state` — a fired deploy gate leaves
+        # `state` at `waiting`, so it already lands in `pending` with no
+        # extra handling (the issue's "waiting (and any held)" wording).
+        result = fold_drive_queue_status(
+            [_dq_row(1, state_="waiting", hold_state="fired")], 1000.0
+        )
+        assert result.rows[0]["band"] == "pending"
+
+    def test_band_column_present_for_every_row(self) -> None:
+        rows = [
+            _dq_row(1, state_="running"),
+            _dq_row(2, state_="waiting"),
+            _dq_row(3, state_="done"),
+            _dq_row(4, state_="blocked"),
+            _dq_row(5, state_="failed"),
+            _dq_row(6, state_="merged-partial"),
+            _dq_row(7, state_="parked"),
+        ]
+        result = fold_drive_queue_status(rows, 1000.0)
+        by_issue = {r["issue"]: r["band"] for r in result.rows}
+        assert by_issue[1] == "running"
+        assert by_issue[2] == "pending"
+        assert by_issue[3] == "terminal"
+        assert by_issue[4] == "terminal"
+        assert by_issue[5] == "terminal"
+        assert by_issue[6] == "terminal"
+        assert by_issue[7] == "pending"
 
     def test_attempts_ge_1_named_in_notes(self) -> None:
         rows = [