code-coordinator 0.5.494__tar.gz → 0.5.496__tar.gz

{code_coordinator-0.5.494 → code_coordinator-0.5.496}/.github/workflows/test.yml

@@ -5,6 +5,8 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  # #3392: the `postgres` job below is opt-in and runs ONLY from here.
+  workflow_dispatch:
 
 jobs:
   test:
@@ -371,6 +373,21 @@ jobs:
   # what every other job's `pip install -e ".[dev]"` pulls in.
   postgres:
     runs-on: ubuntu-latest
+    # #3392, 2026-09-18: taken out of automatic CI by operator decision -- the
+    # Postgres migration is not current work, and until it is this job is pure
+    # noise. It gates nothing (`continue-on-error: true` below, and it is not a
+    # required check in branch protection), emits ~3700
+    # ProductionDatabaseGuardError that dominate every `--log-failed` read of
+    # this workflow, and costs 65-70 min of runner time per push to main. It
+    # misdirected #3378 item 1, #3380 and #3385 -- all three were scoped as
+    # "make main green" against a job that cannot redden main.
+    #
+    # RESTORE by deleting this one `if:` line when the migration becomes active
+    # work. Everything below is unchanged and still correct. Sequence then is:
+    # remove the `if:`, work the failure list down, THEN remove
+    # `continue-on-error` -- that last step is what turns this into a real gate
+    # and it is the deliberate END of that work, not the start.
+    if: github.event_name == 'workflow_dispatch'
     continue-on-error: true
     services:
       postgres:

{code_coordinator-0.5.494 → code_coordinator-0.5.496}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.494
+Version: 0.5.496
 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.494 → code_coordinator-0.5.496}/code_coordinator.egg-info/SOURCES.txt

@@ -613,6 +613,7 @@ tests/test_drive_machine_fault.py
 tests/test_drive_queue.py
 tests/test_drive_queue_blocked_rendering.py
 tests/test_drive_queue_launch_argv.py
+tests/test_drive_queue_max_parallel_config.py
 tests/test_drive_queue_max_parallel_per_repo_config.py
 tests/test_drive_queue_roll_pending.py
 tests/test_drive_queue_self_cordon_escalation.py

{code_coordinator-0.5.494 → code_coordinator-0.5.496}/code_coordinator.egg-info/scm_file_list.json

@@ -639,6 +639,7 @@
     "tests/test_drive_queue.py",
     "tests/test_drive_queue_blocked_rendering.py",
     "tests/test_drive_queue_launch_argv.py",
+    "tests/test_drive_queue_max_parallel_config.py",
     "tests/test_drive_queue_max_parallel_per_repo_config.py",
     "tests/test_drive_queue_roll_pending.py",
     "tests/test_drive_queue_self_cordon_escalation.py",

code_coordinator-0.5.496/code_coordinator.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.496",
+  "distance": 0,
+  "node": "gdcf7e4331cfa3d1b0c95e0e3450402c3c49a6723",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-19"
+}

{code_coordinator-0.5.494 → code_coordinator-0.5.496}/coord/board_schema.py

@@ -245,6 +245,17 @@ class BoardIssue:
     synced_at: float | None = None
     milestone_number: int | None = None
     milestone_title: str | None = None
+    # #3384: GitHub's own `stateReason` — `"reopened"` when a human explicitly
+    # reopened this issue via `gh issue reopen`, `""` for an issue that has
+    # never been closed. See `coord.drive_queue.IssueFacts.reopened`.
+    #
+    # ABSENT, not `""`, on the wire when it is the empty default: it would
+    # otherwise cost ~20 bytes on every issue row of every poll to say nothing
+    # (`coord.board_wire._drop_default_state_reason`, which is also why it is
+    # not in this DTO's `required` list — it has a default). Read it as
+    # `row.get("state_reason") or ""`; the Rust side gets `#[serde(default)]`
+    # from `coord.codegen`.
+    state_reason: str = ""
 
 
 @dataclasses.dataclass(kw_only=True)

{code_coordinator-0.5.494 → code_coordinator-0.5.496}/coord/board_wire.py

@@ -65,6 +65,19 @@ Rust call site of ``OpenIssue.body`` / ``PipelineIssue.body`` first. So the
 body now leaves the collection wire for open issues too, and
 :func:`bound_issue_row` keeps only the machine-parsed *residue* a client
 cannot re-fetch in time — see :data:`ALLOWED_GLOB_MARKER`.
+
+**#3384: a defaulted flag costs its bytes on EVERY row.** The reopen witness
+``issues.state_reason`` carries a value on the handful of rows GitHub
+actually set one on, and the empty default on every other issue on the
+board — and an empty-but-present key is ~20 bytes of wire per row per poll,
+which on the #1791 guard's 3000-row seed is ~57 KB and pushed the payload
+straight through :data:`BOARD_PAYLOAD_BYTE_BUDGET`. So the default is
+dropped from the wire entirely (:func:`_drop_default_state_reason`) and the
+key is present only when it says something. This is the same additive-only
+convention the ``<field>_truncated`` flags already follow, and it is the
+rule to apply to the NEXT defaulted field somebody adds to
+``coord/board_schema.py``: an always-present default is a per-row tax on a
+payload that is polled every few seconds and whose ETag never matches.
 """
 
 from __future__ import annotations
@@ -253,9 +266,52 @@ def _machine_readable_residue(body: str) -> str:
     )
 
 
+def _drop_default_state_reason(row: dict) -> None:
+    """#3384: drop ``state_reason`` from the wire when it is the empty default.
+
+    ``issues.state_reason`` is GitHub's own ``stateReason``: ``"reopened"``
+    on an issue a human explicitly reopened, and ``''`` on every issue that
+    has never been closed — i.e. on essentially the whole board.  Shipping
+    the empty default costs ~20 bytes on EVERY issue row of EVERY poll (~57 KB
+    on the #1791 guard's 3000-row seed, enough on its own to breach
+    :data:`BOARD_PAYLOAD_BYTE_BUDGET`) to tell a client something it already
+    assumes.
+
+    Safe because absent and empty are the SAME answer to every consumer, by
+    construction rather than by luck:
+
+    * ``coord.drive_queue.build_board_view`` reads it as
+      ``str(row.get("state_reason") or "").lower() == "reopened"`` — the one
+      question anything asks of this field — so a missing key and an empty
+      one both yield ``IssueFacts.reopened is False``.  That is also what
+      keeps this wire cut from splitting the answer in two: the daemon-host
+      local path (``coord.drive_state._local_issue_rows``, which never runs
+      through this module) still carries ``''``, and both paths land on the
+      identical fact.
+    * The Rust ``OpenIssue.state_reason`` is generated with
+      ``#[serde(default)]`` (``coord.codegen._rust_auto_field``), so an
+      absent key deserializes to ``String::new()``.
+    * ``state_reason`` is not in ``BoardIssue``'s ``required`` list in
+      ``/openapi.json`` (it has a dataclass default), so omitting it stays
+      inside the published contract.
+
+    A NON-empty value is always kept — this drops the default, it does not
+    filter for ``"reopened"`` specifically, so a value GitHub starts sending
+    that we do not yet interpret still reaches clients intact.
+    """
+    if not row.get("state_reason"):
+        row.pop("state_reason", None)
+
+
 def bound_issue_row(row: dict) -> None:
     """Apply the wire policy to one ``/board`` issue row (mutates).
 
+    **The empty ``state_reason`` default is dropped from every issue row**
+    (#3384), tracking issues included — see
+    :func:`_drop_default_state_reason`.  Deliberately above the epic
+    early-return below, so the wire shape of that field does not depend on
+    which kind of issue a row happens to be.
+
     **Tracking (epic) issues are exempt from the body cap.**  The TUI's
     Milestone DAG parses ``## Work order`` out of the tracking issue's body
     *client-side* (`milestone_dag.rs::milestones_with_work_orders` — it does
@@ -282,6 +338,7 @@ def bound_issue_row(row: dict) -> None:
     exactly as for a closed issue, which is what arms that hydration
     (``pipeline.rs::issue_body_fetch_target``).
     """
+    _drop_default_state_reason(row)
     if _is_tracking_issue(row):
         return
     if _is_closed_issue(row):

{code_coordinator-0.5.494 → code_coordinator-0.5.496}/coord/commands/drive_queue.py

@@ -46,6 +46,7 @@ from coord.drive_queue import (
     APPLY_APPLIED,
     APPLY_FAILED,
     DEFAULT_MAX_ATTEMPTS,
+    DEFAULT_MAX_PARALLEL,
     DEFAULT_MAX_PARALLEL_PER_REPO,
     HOLD_FIRED,
     HOLD_RELEASED,
@@ -77,6 +78,7 @@ from coord.drive_queue import (
     add_preflight_notice,
     apply_gate_status,
     build_board_view,
+    default_max_parallel,
     detect_unreachable_waits,
     diagnose_blocked_after,
     effective_max_fix_rounds,
@@ -2815,13 +2817,21 @@ def _local_issue_rows() -> list[dict]:
 
     Fail-soft: an unreadable/absent table degrades to ``[]``, which puts the
     daemon host back on the assignment-only signals rather than aborting.
+
+    #3384: ``state_reason`` selected alongside ``state`` — this IS the
+    ``coord drive-queue tick`` daemon-host path, so without it
+    ``coord.drive_queue.IssueFacts.reopened`` would never populate on the
+    one host that actually ticks the queue, and a reopened issue's stale
+    ``merged`` witness would keep short-circuiting entries straight to
+    ``done`` there regardless of the fix in ``build_board_view``.
     """
     from coord import sql  # noqa: PLC0415
     from coord.db import get_connection  # noqa: PLC0415
 
     try:
         rows = sql.execute(
-            get_connection(), "SELECT repo_name, number, state FROM issues"
+            get_connection(),
+            "SELECT repo_name, number, state, state_reason FROM issues",
         ).fetchall()
     except Exception:  # noqa: BLE001 — see the fail-soft note above
         return []
@@ -5240,12 +5250,25 @@ def _blocked_escalation_command(entry: QueueEntry | None, key: str, reason: str)
 @click.option(
     "--max-parallel",
     type=int,
-    default=1,
-    show_default=True,
+    default=None,
     help=(
-        "Concurrency ceiling. Capacity is counted from BOARD state, not from a "
-        "session count, so a drive whose observer hit its deadline (#1660) "
-        "still occupies a slot."
+        "Global concurrency ceiling. Capacity is counted from BOARD state, "
+        "not from a session count, so a drive whose observer hit its "
+        "deadline (#1660) still occupies a slot. Omit this flag to use "
+        "pipeline.max_parallel from coordinator.yml (or, absent that, a "
+        "derivation from the fleet's own shape — repo count times the "
+        "resolved --max-parallel-per-repo, clamped to "
+        "concurrency.max_workers, see coord.drive_queue."
+        "default_max_parallel; falling back further, if the config itself "
+        f"can't be read, to {DEFAULT_MAX_PARALLEL}, #3388) — passing it "
+        "explicitly always wins over both. #3388: a hardcoded constant here "
+        "(coord-drive-queue.service used to pin --max-parallel 4) silently "
+        "starves every repo but the first couple once "
+        "--max-parallel-per-repo can exceed 1 — prefer the config setting "
+        "over a systemd drop-in for the same reason #2573 gives for "
+        "--max-parallel-per-repo: a drop-in has to restate the packaged "
+        "unit's whole ExecStart= to change just this flag, and that copy "
+        "silently drifts from the packaged unit's other flags over time."
     ),
 )
 @click.option(
@@ -5293,7 +5316,7 @@ def _blocked_escalation_command(entry: QueueEntry | None, key: str, reason: str)
 )
 @_CONFIG_OPTION
 def drive_queue_tick(
-    max_parallel: int,
+    max_parallel: int | None,
     max_parallel_per_repo: int | None,
     dry_run: bool,
     reconcile_only: bool,
@@ -5330,6 +5353,20 @@ def drive_queue_tick(
     reverted #2314's pinned-venv `ExecStart=` right back to a
     worker-overwritable path as an unnoticed side effect).
 
+    #3388: `--max-parallel` resolves the SAME way, one level up — the flag on
+    THIS invocation, when given; else `pipeline.max_parallel` from
+    `coordinator.yml`; else `coord.drive_queue.default_max_parallel`'s
+    derivation from the fleet's own shape (repo count times the
+    ALREADY-RESOLVED `--max-parallel-per-repo` above, clamped to
+    `concurrency.max_workers`); else, only if the config itself could not be
+    read at all, `coord.drive_queue.DEFAULT_MAX_PARALLEL` (1). A hardcoded
+    `--max-parallel` on the deployed systemd unit is exactly the failure mode
+    this closes: #2012 set it to the repo count when `--max-parallel-per-repo`
+    always defaulted to 1, #2057 raised it once by hand for a fifth repo, and
+    neither update survived #2573 letting the per-repo ceiling exceed 1 — two
+    repos alone then reach a stale global ceiling and starve every other repo
+    in the fleet, forever, however deep their own queues are.
+
     `--max-parallel 0` (or `--reconcile-only`, the readable spelling of the
     same thing — #2110) reconciles every `running` entry against the board and
     then stops: no capacity walk, no deferrals, no queue-level alert, no
@@ -5361,24 +5398,37 @@ def drive_queue_tick(
     from coord.filelock import FileLock, LockBusy, drive_queue_lock_path  # noqa: PLC0415
     from coord.state import list_drive_queue, update_drive_queue_entry  # noqa: PLC0415
 
-    if max_parallel < 0:
-        raise click.ClickException(
-            "--max-parallel must be at least 0 (0 = reconcile-only, launch "
-            "nothing this run — see --reconcile-only)"
-        )
+    # Loaded at most once, shared by both ceilings' config-default resolution
+    # below (#3388's `max_parallel` derivation needs the same config
+    # `max_parallel_per_repo` already reads, plus `repos`/`concurrency`) —
+    # `None` on the documented fail-open path, same posture as every other
+    # best-effort config read on this path (an unreadable config must never
+    # abort the tick).
+    _resolved_config: Config | None = None
+    _config_load_attempted = False
+
+    def _config_for_defaults() -> Config | None:
+        nonlocal _resolved_config, _config_load_attempted
+        if not _config_load_attempted:
+            _config_load_attempted = True
+            try:
+                from coord.commands._common import _load_config  # noqa: PLC0415
+
+                _resolved_config = _load_config(config_path)
+            except Exception:  # noqa: BLE001 — an unreadable config must not abort the tick
+                _resolved_config = None
+        return _resolved_config
 
     # #2573: an explicit `--max-parallel-per-repo` always wins; otherwise
     # fall back to the fleet-wide `pipeline.max_parallel_per_repo` in
     # coordinator.yml, and only then to the hardcoded default. Resolved
-    # BEFORE validation below so a bad value from either source is caught
-    # the same way regardless of which one supplied it.
+    # BEFORE `--max-parallel` (#3388's derivation multiplies BY this
+    # already-resolved value) and before validation below, so a bad value
+    # from either source is caught the same way regardless of which one
+    # supplied it.
     if max_parallel_per_repo is None:
-        try:
-            from coord.commands._common import _load_config  # noqa: PLC0415
-
-            config_default = _load_config(config_path).pipeline.max_parallel_per_repo
-        except Exception:  # noqa: BLE001 — an unreadable config must not abort the tick
-            config_default = None
+        _cfg = _config_for_defaults()
+        config_default = None if _cfg is None else _cfg.pipeline.max_parallel_per_repo
         max_parallel_per_repo = (
             DEFAULT_MAX_PARALLEL_PER_REPO if config_default is None else config_default
         )
@@ -5388,6 +5438,35 @@ def drive_queue_tick(
             "--max-parallel-per-repo must be 0 (no per-repo ceiling) or more"
         )
 
+    # #3388: an explicit `--max-parallel` always wins; otherwise
+    # `pipeline.max_parallel` from coordinator.yml; otherwise derive it from
+    # the fleet's own shape (repo count * the per-repo ceiling just resolved
+    # above, clamped to the fleet's real worker capacity) rather than fall
+    # back to a hand-maintained constant that goes stale the moment either
+    # side changes — see `coord.drive_queue.default_max_parallel`. Only when
+    # the config itself could not be read at all (so neither the fleet
+    # default nor the fleet shape is known) does this fall back to the
+    # hardcoded `DEFAULT_MAX_PARALLEL`.
+    if max_parallel is None:
+        _cfg = _config_for_defaults()
+        config_max_parallel = None if _cfg is None else _cfg.pipeline.max_parallel
+        if config_max_parallel is not None:
+            max_parallel = config_max_parallel
+        elif _cfg is not None:
+            max_parallel = default_max_parallel(
+                repo_count=len(_cfg.repos),
+                max_parallel_per_repo=max_parallel_per_repo,
+                max_workers_cap=_cfg.concurrency.max_workers,
+            )
+        else:
+            max_parallel = DEFAULT_MAX_PARALLEL
+
+    if max_parallel < 0:
+        raise click.ClickException(
+            "--max-parallel must be at least 0 (0 = reconcile-only, launch "
+            "nothing this run — see --reconcile-only)"
+        )
+
     # #2110: `--reconcile-only` and `--max-parallel 0` are the same request —
     # one flag is a mnemonic for the other rather than a second code path, so
     # there is exactly one way this behaves, not two that could drift apart.

{code_coordinator-0.5.494 → code_coordinator-0.5.496}/coord/config.py

@@ -1232,6 +1232,21 @@ class PipelineConfig:
     :data:`_DEFAULT_STALL_THRESHOLDS` for the shape and the evidence behind
     its two seeded entries, and :meth:`stall_threshold_secs` for how a type
     absent from the table falls back to the drive's flat ``--stall`` value.
+
+    ``max_parallel`` (#3388) is the fleet-wide default for ``coord
+    drive-queue tick``'s GLOBAL concurrency ceiling (``--max-parallel``) —
+    the sibling of ``max_parallel_per_repo`` above, added for the same
+    reason: a systemd unit's hardcoded ``--max-parallel 4`` encoded a fact
+    about the fleet (repo count times per-repo ceiling) that nobody revisited
+    when either side changed, and two repos alone starved the other twelve
+    once ``max_parallel_per_repo`` could exceed 1 (#2012, #2057, #2573).
+    ``None`` (the default) leaves the ceiling at
+    ``coord.drive_queue.default_max_parallel``'s derivation — ``repo_count *
+    max_parallel_per_repo``, clamped to ``concurrency.max_workers`` — rather
+    than a hand-maintained constant. An explicit ``coord drive-queue tick
+    --max-parallel N`` on the command line always wins over this, exactly
+    mirroring ``max_parallel_per_repo``'s own resolution order — see
+    ``coord.commands.drive_queue.drive_queue_tick``.
     """
 
     default_gates: list[str] = field(default_factory=lambda: ["test", "review", "merge"])
@@ -1267,6 +1282,9 @@ class PipelineConfig:
     stall_thresholds: dict[str, float] = field(
         default_factory=lambda: dict(_DEFAULT_STALL_THRESHOLDS)
     )
+    # #3388 — None means "derive from the fleet shape", see
+    # coord.drive_queue.default_max_parallel. See the class docstring.
+    max_parallel: int | None = None
 
     def attention_threshold_for(
         self,
@@ -3641,6 +3659,17 @@ def _parse_pipeline(raw: Any) -> PipelineConfig:
             )
         cfg.max_parallel_per_repo = value
 
+    if "max_parallel" in raw:
+        value = raw["max_parallel"]
+        if value is not None and (
+            not isinstance(value, int) or isinstance(value, bool) or value < 0
+        ):
+            raise ConfigError(
+                "pipeline.max_parallel must be a non-negative integer or "
+                "null (0 = reconcile-only, launch nothing)"
+            )
+        cfg.max_parallel = value
+
     if "stall_thresholds" in raw:
         value = raw["stall_thresholds"]
         if not isinstance(value, dict):

{code_coordinator-0.5.494 → code_coordinator-0.5.496}/coord/db.py

@@ -1049,7 +1049,16 @@ def retry_on_locked(
 # ("confirmed"/"unconfirmed"/"refuted"/"baseline_red") for a `test_state`
 # write, alongside `coord.state._record_test_verdict_local`. See
 # coord.models.Assignment.test_confirmation.
-_DB_SCHEMA_VERSION = 18
+#
+# #3384: bumped 18 -> 19 for the new `issues.state_reason` column appended
+# to `_migrate_add_columns` below — carries GitHub's own `stateReason`
+# (`"reopened"` when a human explicitly reopened a closed issue) so
+# `coord.drive_queue.IssueFacts.reopened`/`.landed` can tell "this issue was
+# reopened for incomplete work" apart from "this issue never closed in the
+# first place" (a quadraui-style merge into a non-default branch) — both
+# read identically as `merged=True, issue_state="open"` otherwise. See
+# `coord.drive_queue.IssueFacts.landed`'s docstring.
+_DB_SCHEMA_VERSION = 19
 
 
 def _read_schema_version(conn: sqlite3.Connection) -> int:
@@ -2490,6 +2499,17 @@ _MIGRATE_ADD_COLUMNS: list[str] = [
     # See coord.models.Assignment.test_confirmation and
     # coord.confirm_test.TEST_CONFIRMATION_VALUES for the exhaustive set.
     "ALTER TABLE assignments ADD COLUMN test_confirmation TEXT",
+    # #3384: GitHub's own `stateReason` for this issue — `''`/NULL for every
+    # row predating this migration and for an issue that has never closed,
+    # `"reopened"` (lowercased on write — see
+    # `coord.state._upsert_open_issues_local`) when a human explicitly
+    # reopened a previously-closed issue via `gh issue reopen`. This is the
+    # ONLY witness that lets `coord.drive_queue.IssueFacts.landed` tell a
+    # genuine reopen (the work is NOT done, no matter what an earlier PR
+    # merge recorded) apart from a quadraui-style repo whose merged PRs never
+    # auto-close the linked issue at all — both look identical as
+    # `merged=True, issue_state="open"` without it.
+    "ALTER TABLE issues ADD COLUMN state_reason TEXT NOT NULL DEFAULT ''",
 ]
 
 

{code_coordinator-0.5.494 → code_coordinator-0.5.496/coord}/deploy/coord-drive-queue.service

@@ -165,46 +165,58 @@ KillMode=process
 # stays so nobody re-derives the (wrong) theory that narrowing THIS PATH
 # would have prevented it.
 Environment=PATH=%h/.coord-venv/bin:%h/.cargo/bin:%h/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin
-# --max-parallel 4 (#2012, raised from 3 in #2057) — the global ceiling,
-# ONE SLOT PER REPO IN THE FLEET: claude-coordinator, quadraui, vimcode,
-# coord-portal. It was 3 because the fleet had three repos when #2012 set
-# it; coord-portal joined afterwards and the number was never revisited, so
-# the fourth repo could never drive concurrently no matter what was queued.
-#
-# KEEP THIS EQUAL TO THE REPO COUNT. It is not a tuning knob for how hard
-# the fleet works — that is what the per-repo ceiling and machine capacity
-# decide. Set it lower and a repo silently loses its lane; set it higher
-# and it does nothing, because the per-repo ceiling still admits only one
-# drive per repo.
-#
-# #1972 added the SECOND ceiling, --max-parallel-per-repo (default 1),
-# which is what keeps two drives off the same repo; without raising this
-# outer one the per-repo ceiling can never bind, because the walk stops at
-# the global limit first and never reaches an entry from a different repo.
-#
-# Raise this ONLY on a host whose coord actually enforces the per-repo
-# ceiling (>= the release carrying #1972). A higher global ceiling on an
-# older coord launches two same-repo drives, which stale each other's
-# Test verdicts (#1479) — the exact collision #1972 exists to prevent.
+# --max-parallel USED TO be hardcoded here (#2012 set it to 3 — the repo
+# count at the time, one slot per repo; #2057 raised it to 4 when a fourth
+# repo joined and it was never revisited again). #3388: that invariant
+# (global == repo count) only held while --max-parallel-per-repo always
+# defaulted to 1. Once #2573 gave the per-repo ceiling its own
+# coordinator.yml knob and an operator raised it past 1, the real invariant
+# became `global >= repo_count * max_parallel_per_repo` — and at 14 repos
+# with max_parallel_per_repo=2 against a global ceiling still stuck at 4,
+# TWO repos alone reached the global ceiling and every other repo in the
+# fleet was starved, permanently, no matter what was queued (2026-09-18).
+#
+# So --max-parallel is deliberately ABSENT below, the same way
+# --max-parallel-per-repo already is (#2573's rationale, restated below
+# applies verbatim here). Omitting it lets `coord drive-queue tick` resolve
+# it itself, in this order: an explicit --max-parallel on this ExecStart=
+# (none is set here on purpose) > `pipeline.max_parallel` in
+# ~/.coord/coordinator.yml, if an operator wants to pin a fleet-wide value >
+# `coord.drive_queue.default_max_parallel`'s DERIVATION from the fleet's own
+# shape — repo count times the (already-resolved) per-repo ceiling, clamped
+# to `concurrency.max_workers` — which is self-maintaining across repo
+# additions instead of a constant nobody remembers to revisit. See
+# `coord.commands.drive_queue.drive_queue_tick` for the exact order and
+# `coord.config.PipelineConfig.max_parallel` for the field.
+#
+# #1972's SECOND ceiling, --max-parallel-per-repo, is what keeps two drives
+# off the same repo once the global ceiling admits more than one launch at
+# once; the derived global ceiling above only ever multiplies BY whatever
+# that ceiling resolves to, so raising --max-parallel-per-repo in
+# coordinator.yml raises this fleet's derived global ceiling right along
+# with it — no separate edit needed here.
+#
+# Raise pipeline.max_parallel_per_repo (or let it stay derived) ONLY on a
+# fleet whose coord actually enforces the per-repo ceiling (>= the release
+# carrying #1972). A higher global ceiling on an older coord launches two
+# same-repo drives, which stale each other's Test verdicts (#1479) — the
+# exact collision #1972 exists to prevent.
 #
 # #2573: the per-repo ceiling deliberately does NOT appear as a
-# --max-parallel-per-repo flag below. It has a THIRD source now — set it as
-# `pipeline.max_parallel_per_repo` in ~/.coord/coordinator.yml instead of a
-# `systemctl --user edit` drop-in. A drop-in has to restate this entire
+# --max-parallel-per-repo flag below either, for the identical reason: set it
+# as `pipeline.max_parallel_per_repo` in ~/.coord/coordinator.yml instead of
+# a `systemctl --user edit` drop-in. A drop-in has to restate this entire
 # ExecStart= line to change one flag on it, and that restated copy silently
 # drifts from THIS file forever after — dellserver's live drop-in, built
 # solely to carry --max-parallel-per-repo 2, was found resetting ExecStart=
 # back to %h/.local/bin/coord, silently reverting #2314's pinned-venv path
 # above as an unnoticed side effect (see docs/DRIVE_QUEUE.md §9 and #2573).
-# coordinator.yml has no such coupling — it is read fresh by the flag's own
-# resolution (an explicit --max-parallel-per-repo on this ExecStart= would
-# still win, but none is set here on purpose) — see
-# `coord.commands.drive_queue.drive_queue_tick` for the exact order and
-# `coord.config.PipelineConfig.max_parallel_per_repo` for the field. If a
-# `coord-drive-queue.service.d/override.conf` still exists on a host purely
-# to carry --max-parallel-per-repo, move that value into coordinator.yml and
-# delete the drop-in — an empty override directory cannot drift.
-ExecStart=%h/.coord-venv/bin/coord drive-queue tick --max-parallel 4 --config %h/.coord/coordinator.yml
+# coordinator.yml has no such coupling — it is read fresh by each flag's own
+# resolution. If a `coord-drive-queue.service.d/override.conf` still exists
+# on a host purely to carry --max-parallel/--max-parallel-per-repo, move
+# that value into coordinator.yml and delete the drop-in — an empty
+# override directory cannot drift.
+ExecStart=%h/.coord-venv/bin/coord drive-queue tick --config %h/.coord/coordinator.yml
 # Generous relative to the tick's own ~120s launch-subprocess timeout
 # (_LAUNCH_TIMEOUT_SECONDS in coord/commands/drive_queue.py), but well below
 # the timer's 15-minute cadence (coord-drive-queue.timer) so a genuinely