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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.495
+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.495 → 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.495
+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.495 → 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.495 → 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.495 → 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,
@@ -5248,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(
@@ -5301,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,
@@ -5338,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
@@ -5369,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
         )
@@ -5396,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.495 → 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.495 → 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

{code_coordinator-0.5.495 → code_coordinator-0.5.496}/coord/drive_queue.py

@@ -538,6 +538,64 @@ DISPATCH_FAILURE_MIN_BACKOFF_SECONDS = 660.0
 # why `render_plan` prints the per-repo breakdown and says where it came from.
 DEFAULT_MAX_PARALLEL_PER_REPO = 1
 
+# ── the global ceiling's own fleet-shape default (#3388) ────────────────────
+#
+# `--max-parallel` (the OTHER ceiling, applied before the per-repo one above)
+# used to be a constant an operator hand-set in `coord-drive-queue.service` —
+# #2012 set it to 3 (the repo count at the time), #2057 raised it to 4 when a
+# fourth repo joined and was never touched again. That was tolerable only
+# because `--max-parallel-per-repo` defaulted to 1: with one slot per repo,
+# `global == repo_count` was the whole invariant, and it was self-evidently
+# wrong the moment a repo count changed (a quick `git log` question).
+#
+# #2573 gave the per-repo ceiling its own `coordinator.yml` knob, which can
+# now be raised past 1 — and the invariant silently became
+# `global >= repo_count * max_parallel_per_repo` without any constant
+# anywhere saying so. At 14 repos and `max_parallel_per_repo=2` against a
+# `--max-parallel` still stuck at 4, two repos alone reach the global
+# ceiling and every other repo in the fleet is starved, permanently,
+# regardless of what is queued (the exact fleet state observed 2026-09-18).
+#
+# `default_max_parallel` below is that invariant computed fresh every tick
+# instead of remembered by a human: enough global room for every repo to
+# reach its OWN per-repo ceiling at once. See
+# `coord.commands.drive_queue.drive_queue_tick` for where this feeds into
+# the flag's actual resolution order (explicit flag > `coordinator.yml`
+# `pipeline.max_parallel` > this derivation > `DEFAULT_MAX_PARALLEL` as a
+# last-resort fallback when the config itself can't be read).
+DEFAULT_MAX_PARALLEL = 1
+
+
+def default_max_parallel(
+    *, repo_count: int, max_parallel_per_repo: int, max_workers_cap: int
+) -> int:
+    """Derive the drive-queue tick's global ceiling from the fleet's shape.
+
+    ``repo_count * max_parallel_per_repo`` is the smallest global ceiling
+    that lets every repo reach its own per-repo ceiling at the same time —
+    the invariant #2012/#2057 tried to maintain by hand and lost each time
+    either the fleet or the per-repo ceiling changed (see the module-level
+    comment above this function for the incident, #3388).
+
+    ``max_parallel_per_repo <= 0`` means the per-repo ceiling is itself
+    disabled (one global counter, pre-#1972 behaviour) — there is no
+    per-repo figure to multiply by, so this falls back to *max_workers_cap*
+    alone. Either way the result is clamped to *max_workers_cap*
+    (``concurrency.max_workers``, the fleet's actual worker capacity across
+    every stage, not just drive-queue launches) so a large fleet gets a
+    saner DEFAULT, not a promise the machines behind it can't keep — a
+    ``max_workers_cap`` of 0 or less is "no cap known" and is not applied.
+    Always at least 1: a derivation must never produce a ceiling that
+    admits nothing.
+    """
+    if max_parallel_per_repo > 0 and repo_count > 0:
+        derived = repo_count * max_parallel_per_repo
+    else:
+        derived = max_workers_cap
+    if max_workers_cap > 0:
+        derived = min(derived, max_workers_cap)
+    return max(1, derived)
+
 # ── the startup grace window (#1794) ─────────────────────────────────────────
 #
 # A drive is NOT established the instant `coord drive --tmux` exits 0.  #1606's

{code_coordinator-0.5.495/coord → code_coordinator-0.5.496}/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

{code_coordinator-0.5.495 → code_coordinator-0.5.496}/tests/test_cli_drive_queue.py

@@ -2331,7 +2331,14 @@ def test_back_to_back_ticks_launch_exactly_one_drive(cli, seed, launches):
     assert "died without landing the work" not in second.output
     assert "retry" not in second.output
     assert "starting" in second.output
-    assert "1/1 occupied" in second.output
+    # #3388: no `--max-parallel` given, so the global ceiling is derived from
+    # this config's fleet shape — 2 repos * the default 1/repo ceiling,
+    # clamped to `concurrency.max_workers` (2) — rather than the old
+    # hardcoded 1. One entry occupying a slot out of that derived capacity
+    # of 2 is exactly what "exactly one drive, and the ceiling did not
+    # collapse to 1 just because only one repo has anything queued" looks
+    # like; see coord.drive_queue.default_max_parallel.
+    assert "1/2 occupied" in second.output
 
 
 def test_a_still_starting_drive_is_reported_not_escalated(cli, seed, launches):