code-coordinator 0.5.505__tar.gz → 0.5.506__tar.gz

{code_coordinator-0.5.505 → code_coordinator-0.5.506}/PKG-INFO

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

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

@@ -563,6 +563,7 @@ tests/test_config.py
 tests/test_config_acceptance.py
 tests/test_config_audit.py
 tests/test_config_drift_check.py
+tests/test_config_effective.py
 tests/test_config_pricing.py
 tests/test_config_snapshot_noncanonical_2208.py
 tests/test_config_usage_gate.py

{code_coordinator-0.5.505 → code_coordinator-0.5.506}/code_coordinator.egg-info/scm_file_list.json

@@ -589,6 +589,7 @@
     "tests/test_config_acceptance.py",
     "tests/test_config_audit.py",
     "tests/test_config_drift_check.py",
+    "tests/test_config_effective.py",
     "tests/test_config_pricing.py",
     "tests/test_config_snapshot_noncanonical_2208.py",
     "tests/test_config_usage_gate.py",

{code_coordinator-0.5.505 → code_coordinator-0.5.506}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.505",
+  "tag": "0.5.506",
   "distance": 0,
-  "node": "g5436dee520cfae2bc68cea2d0b9b08cbd47510d9",
+  "node": "g10b3e0961d928aad40e02740533266e5814d0edd",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-20"

{code_coordinator-0.5.505 → code_coordinator-0.5.506}/coord/commands/drive_queue.py

@@ -79,7 +79,6 @@ 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,
@@ -87,6 +86,7 @@ from coord.drive_queue import (
     entry_key,
     find_cycle,
     fired_holds,
+    flag_shadows_config_warning,
     is_dispatch_failure_reason,
     is_merge_gate_block_reason,
     is_permanent_block_reason,
@@ -101,6 +101,8 @@ from coord.drive_queue import (
     plan_tick,
     remaining_fix_rounds,
     render_plan,
+    resolve_max_parallel,
+    resolve_max_parallel_per_repo,
     total_fix_round_budget,
     unreachable_wait_alert,
     validate_apply_gate,
@@ -6210,26 +6212,40 @@ def drive_queue_tick(
                 _resolved_config = None
         return _resolved_config
 
-    # #2573: an explicit `--max-parallel-per-repo` always wins; otherwise
+    # #2573/#3408: 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 `--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:
-        _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
-        )
+    # supplied it. `resolve_max_parallel_per_repo` is the SAME function
+    # `coord config --effective` calls to report this ceiling's provenance
+    # (#3408) — one resolution order lives in `coord.drive_queue`, not two
+    # that could drift apart (#2085's "one question, one answer").
+    _cfg = _config_for_defaults()
+    _config_max_parallel_per_repo = (
+        None if _cfg is None else _cfg.pipeline.max_parallel_per_repo
+    )
+    _shadow_warning = flag_shadows_config_warning(
+        flag_name="max-parallel-per-repo",
+        override_value=max_parallel_per_repo,
+        config_key="pipeline.max_parallel_per_repo",
+        config_value=_config_max_parallel_per_repo,
+    )
+    if _shadow_warning:
+        click.echo(_shadow_warning)
+    max_parallel_per_repo = resolve_max_parallel_per_repo(
+        override_value=max_parallel_per_repo,
+        override_source="--max-parallel-per-repo flag",
+        config_value=_config_max_parallel_per_repo,
+    ).value
 
     if max_parallel_per_repo < 0:
         raise click.ClickException(
             "--max-parallel-per-repo must be 0 (no per-repo ceiling) or more"
         )
 
-    # #3388: an explicit `--max-parallel` always wins; otherwise
+    # #3388/#3408: 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
@@ -6237,20 +6253,26 @@ def drive_queue_tick(
     # 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
+    # hardcoded `DEFAULT_MAX_PARALLEL`. Same shared function `coord config
+    # --effective` reports through (#3408) — see the note above.
+    _config_max_parallel = None if _cfg is None else _cfg.pipeline.max_parallel
+    _shadow_warning = flag_shadows_config_warning(
+        flag_name="max-parallel",
+        override_value=max_parallel,
+        config_key="pipeline.max_parallel",
+        config_value=_config_max_parallel,
+    )
+    if _shadow_warning:
+        click.echo(_shadow_warning)
+    max_parallel = resolve_max_parallel(
+        override_value=max_parallel,
+        override_source="--max-parallel flag",
+        config_value=_config_max_parallel,
+        repo_count=0 if _cfg is None else len(_cfg.repos),
+        max_parallel_per_repo=max_parallel_per_repo,
+        max_workers_cap=0 if _cfg is None else _cfg.concurrency.max_workers,
+        config_readable=_cfg is not None,
+    ).value
 
     if max_parallel < 0:
         raise click.ClickException(

{code_coordinator-0.5.505 → code_coordinator-0.5.506}/coord/commands/setup.py

@@ -9,6 +9,7 @@ import socket
 import subprocess
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import click
 import httpx
@@ -18,6 +19,10 @@ from coord import __version__
 from coord.commands._common import _CONFIG_OPTION, _load_config
 import json
 
+if TYPE_CHECKING:  # pragma: no cover — typing only
+    from coord.config import Config
+    from coord.drive_queue import CeilingResolution
+
 
 @click.command(help="Print the coord version.")
 def version() -> None:
@@ -78,9 +83,55 @@ def store_backend_cmd() -> None:
 
 
 @click.command("config", help="Load coordinator.yml and pretty-print the parsed config.")
+@click.option(
+    "--effective",
+    "effective",
+    is_flag=True,
+    default=False,
+    help=(
+        "Print every concurrency ceiling's EFFECTIVE value and provenance "
+        "instead of the parsed config (#3408): which source won (a "
+        "machine-local systemd unit's hardcoded flag, an explicit CLI "
+        "flag, coordinator.yml, or a derived default), what any losing "
+        "source said, and current usage against each ceiling. Answers "
+        "'why isn't this issue being worked' without an SSH in, a "
+        "`systemctl --user cat`, and a coordinator.yml grep."
+    ),
+)
+@click.option(
+    "--max-parallel",
+    "sim_max_parallel",
+    type=int,
+    default=None,
+    help=(
+        "Only with --effective: report as though `coord drive-queue tick` "
+        "were invoked with this explicit --max-parallel (wins outright, "
+        "even over a detected systemd override) -- 'what would tick "
+        "resolve to if I passed this flag'. Resolves nothing by itself."
+    ),
+)
+@click.option(
+    "--max-parallel-per-repo",
+    "sim_max_parallel_per_repo",
+    type=int,
+    default=None,
+    help="Only with --effective: the same simulation for --max-parallel-per-repo.",
+)
 @_CONFIG_OPTION
-def config_cmd(config_path: Path) -> None:
+def config_cmd(
+    config_path: Path,
+    effective: bool,  # noqa: FBT001
+    sim_max_parallel: int | None,
+    sim_max_parallel_per_repo: int | None,
+) -> None:
     cfg = _load_config(config_path)
+    if effective:
+        _print_effective_concurrency(
+            cfg,
+            sim_max_parallel=sim_max_parallel,
+            sim_max_parallel_per_repo=sim_max_parallel_per_repo,
+        )
+        return
     click.echo(f"# {cfg.path}")
     click.echo("")
     click.echo("Repos:")
@@ -105,6 +156,150 @@ def config_cmd(config_path: Path) -> None:
             click.echo(f"  ! {w}")
 
 
+def _print_effective_concurrency(
+    cfg: "Config",
+    *,
+    sim_max_parallel: int | None,
+    sim_max_parallel_per_repo: int | None,
+) -> None:
+    """`coord config --effective` (#3408): print every concurrency ceiling
+    coord actually enforces, its resolved value, which source won, and what
+    any losing source said. This is the whole point — a bare effective
+    number would not have told #3408's operator that pushing
+    `pipeline.max_parallel` to `coord-settings` was futile while a
+    machine-local systemd unit's hardcoded ``--max-parallel`` outranks it.
+
+    Calls the SAME `coord.drive_queue.resolve_max_parallel`/
+    `resolve_max_parallel_per_repo` functions
+    `coord.commands.drive_queue.drive_queue_tick` uses to decide what it
+    actually launches, so this can never show a different answer than the
+    tick that enforces it (#2085's "one question, one answer").
+
+    *sim_max_parallel*/*sim_max_parallel_per_repo* let an operator ask "what
+    would tick resolve to if I passed this flag" without actually running
+    one — they win outright, even over a detected systemd override, exactly
+    as an explicit CLI flag would on the real `coord drive-queue tick`
+    invocation. Left `None` (the default), this instead reports the real
+    machine's own installed systemd unit, if any.
+    """
+    from coord.drive_queue import (  # noqa: PLC0415
+        flag_shadows_config_warning,
+        read_systemd_max_parallel_flags,
+        resolve_max_parallel,
+        resolve_max_parallel_per_repo,
+    )
+
+    systemd_flags = read_systemd_max_parallel_flags()
+
+    per_repo_override = sim_max_parallel_per_repo
+    per_repo_source = "--max-parallel-per-repo flag"
+    if per_repo_override is None and "max_parallel_per_repo" in systemd_flags:
+        per_repo_override = systemd_flags["max_parallel_per_repo"]
+        per_repo_source = "systemd ExecStart --max-parallel-per-repo"
+
+    per_repo_resolution = resolve_max_parallel_per_repo(
+        override_value=per_repo_override,
+        override_source=per_repo_source,
+        config_value=cfg.pipeline.max_parallel_per_repo,
+    )
+    per_repo_warning = flag_shadows_config_warning(
+        flag_name="max-parallel-per-repo",
+        override_value=per_repo_override,
+        config_key="pipeline.max_parallel_per_repo",
+        config_value=cfg.pipeline.max_parallel_per_repo,
+    )
+
+    max_parallel_override = sim_max_parallel
+    max_parallel_source = "--max-parallel flag"
+    if max_parallel_override is None and "max_parallel" in systemd_flags:
+        max_parallel_override = systemd_flags["max_parallel"]
+        max_parallel_source = "systemd ExecStart --max-parallel"
+
+    global_resolution = resolve_max_parallel(
+        override_value=max_parallel_override,
+        override_source=max_parallel_source,
+        config_value=cfg.pipeline.max_parallel,
+        repo_count=len(cfg.repos),
+        max_parallel_per_repo=per_repo_resolution.value,
+        max_workers_cap=cfg.concurrency.max_workers,
+    )
+    global_warning = flag_shadows_config_warning(
+        flag_name="max-parallel",
+        override_value=max_parallel_override,
+        config_key="pipeline.max_parallel",
+        config_value=cfg.pipeline.max_parallel,
+    )
+
+    click.echo(f"# {cfg.path}")
+    click.echo("")
+    click.echo("Effective concurrency ceilings (#3408):")
+    _echo_ceiling(global_resolution)
+    if global_warning:
+        click.echo(f"  {global_warning}")
+    _echo_ceiling(per_repo_resolution)
+    if per_repo_warning:
+        click.echo(f"  {per_repo_warning}")
+    click.echo(
+        f"  {'concurrency.max_workers':<24} {cfg.concurrency.max_workers}"
+        "  <- coordinator.yml concurrency.max_workers"
+    )
+    click.echo("")
+    click.echo(_effective_usage_line(cfg, global_resolution, per_repo_resolution))
+
+
+def _echo_ceiling(resolution: "CeilingResolution") -> None:
+    line = f"  {resolution.name:<24} {resolution.value}  <- {resolution.source}"
+    if resolution.losing:
+        losers = ", ".join(f"{name}: {value}" for name, value in resolution.losing)
+        line += f"  (losing: {losers})"
+    click.echo(line)
+
+
+def _effective_usage_line(
+    cfg: "Config",
+    global_resolution: "CeilingResolution",
+    per_repo_resolution: "CeilingResolution",
+) -> str:
+    """Current in-flight usage against the two resolved ceilings above
+    (#3408 acceptance: "a queue at its global ceiling reports N/N rather
+    than rendering as idle"). Best-effort — a board/queue read needs a
+    reachable daemon or a readable local DB, neither of which this command
+    otherwise depends on, so any failure here is reported inline rather
+    than failing the whole command; the ceilings above are the answer that
+    matters most and must still print.
+
+    Uses `coord.drive_queue.compute_running_occupancy`, the SAME
+    "is this entry still occupying a slot" verdict `plan_tick` itself
+    computes (via `_reconcile_running`) — not a second, independently
+    counted number that could disagree with it (#2085).
+    """
+    try:
+        from coord.commands.drive_queue import _fetch_board_view_with_retry  # noqa: PLC0415
+        from coord.drive_queue import (  # noqa: PLC0415
+            DEFAULT_MAX_ATTEMPTS,
+            compute_running_occupancy,
+            entries_from_rows,
+        )
+        from coord.state import list_drive_queue  # noqa: PLC0415
+
+        board = _fetch_board_view_with_retry()
+        entries = entries_from_rows(list_drive_queue())
+        occupied, repo_occupied = compute_running_occupancy(
+            entries, board, DEFAULT_MAX_ATTEMPTS
+        )
+    except Exception as exc:  # noqa: BLE001 — best-effort; ceilings above still print
+        return f"in flight  unavailable ({exc})"
+
+    line = f"in flight  {occupied}/{global_resolution.value} global"
+    per_repo_bits = " · ".join(
+        f"{repo} {count}/{per_repo_resolution.value}"
+        for repo, count in sorted(repo_occupied.items())
+    )
+    if per_repo_bits:
+        line += f" · {per_repo_bits}"
+    return line
+
+
 def _ensure_coord_permissions(cwd: Path) -> None:
     """Check .claude/settings.local.json for Bash(coord *) / Bash(coord) entries.
 

{code_coordinator-0.5.505 → code_coordinator-0.5.506}/coord/drive_queue.py

@@ -86,7 +86,9 @@ a replacement for it.
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass, field, replace
+from pathlib import Path
 from typing import Any, Iterable, Mapping, Sequence
 
 from coord.drive_state import TERMINAL_STATUSES, WORK_LIKE
@@ -596,6 +598,264 @@ def default_max_parallel(
         derived = min(derived, max_workers_cap)
     return max(1, derived)
 
+
+# ── #3408: EFFECTIVE ceilings, with provenance ───────────────────────────────
+#
+# `default_max_parallel` above computes a NUMBER. It does not say which of
+# the three possible sources produced it, or what the losing sources said —
+# and that second question is the one #3408 exists to answer. The reported
+# incident: an operator pushed `pipeline.max_parallel` to `coord-settings`,
+# watched it land in `coord config`, and watched the fleet's behaviour not
+# change — because a hardcoded `--max-parallel 4` on the systemd unit that
+# actually invokes `coord drive-queue tick` outranks it, and nothing said so.
+#
+# `CeilingResolution` and the two `resolve_*` functions below are the SAME
+# resolution order `coord.commands.drive_queue.drive_queue_tick` applies to
+# decide what it actually launches — that command calls these directly
+# rather than re-deriving the order inline, so `coord config --effective`
+# (`coord.commands.setup.config_cmd`) can never show a different answer than
+# the tick that enforces it (#2085's "one question, one answer"). The only
+# difference between the two call sites is WHERE `override_value` comes
+# from: an explicit CLI flag on `drive_queue_tick`'s own invocation, or a
+# systemd unit's hardcoded flag for the report (`read_systemd_max_parallel_flags`
+# below) — both are "a value that wins over `coordinator.yml` outright",
+# which is exactly what `override_source` exists to label.
+@dataclass(frozen=True)
+class CeilingResolution:
+    """One concurrency ceiling's effective value, and where it came from.
+
+    *losing* lists every OTHER source that had an opinion but did not win —
+    e.g. ``(("coordinator.yml pipeline.max_parallel", 8),)`` when a flag or
+    systemd override beat a `coordinator.yml` value of 8. Empty when nothing
+    else was configured at all. This is deliberately not just "the winning
+    value" — a bare number would not have told #3408's operator that pushing
+    to `coord-settings` was futile; the losing value is the whole point.
+    """
+
+    name: str
+    value: int
+    source: str
+    losing: tuple[tuple[str, int], ...] = ()
+
+
+def resolve_max_parallel_per_repo(
+    *,
+    override_value: int | None,
+    override_source: str,
+    config_value: int | None,
+) -> CeilingResolution:
+    """Resolve `--max-parallel-per-repo` (#2573): *override_value* (an
+    explicit CLI flag, or a systemd unit's hardcoded flag — see the module
+    note above) wins outright when given; else *config_value*
+    (`coordinator.yml` `pipeline.max_parallel_per_repo`); else
+    :data:`DEFAULT_MAX_PARALLEL_PER_REPO`. Mirrors
+    `coord.commands.drive_queue.drive_queue_tick`'s own resolution exactly.
+    """
+    if override_value is not None:
+        losing = (
+            (("coordinator.yml pipeline.max_parallel_per_repo", config_value),)
+            if config_value is not None
+            else ()
+        )
+        return CeilingResolution(
+            "max_parallel_per_repo", override_value, override_source, losing
+        )
+    if config_value is not None:
+        return CeilingResolution(
+            "max_parallel_per_repo",
+            config_value,
+            "coordinator.yml pipeline.max_parallel_per_repo",
+        )
+    return CeilingResolution(
+        "max_parallel_per_repo",
+        DEFAULT_MAX_PARALLEL_PER_REPO,
+        "default (DEFAULT_MAX_PARALLEL_PER_REPO)",
+    )
+
+
+def resolve_max_parallel(
+    *,
+    override_value: int | None,
+    override_source: str,
+    config_value: int | None,
+    repo_count: int,
+    max_parallel_per_repo: int,
+    max_workers_cap: int,
+    config_readable: bool = True,
+) -> CeilingResolution:
+    """Resolve `--max-parallel` (#3388), one level above
+    :func:`resolve_max_parallel_per_repo` in the SAME order: *override_value*
+    wins outright when given; else *config_value* (`coordinator.yml`
+    `pipeline.max_parallel`); else :func:`default_max_parallel`'s derivation
+    from the fleet's own shape (*repo_count* times the ALREADY-RESOLVED
+    *max_parallel_per_repo*, clamped to *max_workers_cap*); else, only when
+    *config_readable* is ``False`` (the config itself could not be loaded at
+    all), :data:`DEFAULT_MAX_PARALLEL`. Mirrors
+    `coord.commands.drive_queue.drive_queue_tick`'s own resolution exactly.
+    """
+    if override_value is not None:
+        losing = (
+            (("coordinator.yml pipeline.max_parallel", config_value),)
+            if config_value is not None
+            else ()
+        )
+        return CeilingResolution("max_parallel", override_value, override_source, losing)
+    if config_value is not None:
+        return CeilingResolution(
+            "max_parallel", config_value, "coordinator.yml pipeline.max_parallel"
+        )
+    if config_readable:
+        derived = default_max_parallel(
+            repo_count=repo_count,
+            max_parallel_per_repo=max_parallel_per_repo,
+            max_workers_cap=max_workers_cap,
+        )
+        return CeilingResolution(
+            "max_parallel",
+            derived,
+            "derived (repo_count × max_parallel_per_repo, clamped to "
+            "concurrency.max_workers)",
+        )
+    return CeilingResolution(
+        "max_parallel",
+        DEFAULT_MAX_PARALLEL,
+        "default (DEFAULT_MAX_PARALLEL, config unreadable)",
+    )
+
+
+def flag_shadows_config_warning(
+    *,
+    flag_name: str,
+    override_value: int | None,
+    config_key: str,
+    config_value: int | None,
+) -> str | None:
+    """#3408 item 2: a latent-surprise combination — an explicit override
+    (a CLI flag on `coord drive-queue tick`'s own invocation, or a systemd
+    unit's hardcoded flag reported by `coord config --effective`) is set
+    WHILE the corresponding `pipeline.*` key is ALSO set in
+    `coordinator.yml`. Both flag-only and config-only are ordinary,
+    unremarkable configurations and return ``None`` — only the combination,
+    where the config value is silently dead weight, is worth a warning.
+    """
+    if override_value is None or config_value is None:
+        return None
+    return (
+        f"warning: --{flag_name} {override_value} always wins, but "
+        f"{config_key} is also set to {config_value} in coordinator.yml — "
+        "that value has no effect while the flag is given."
+    )
+
+
+# The unit whose ExecStart= is the one documented case (#3388) of a
+# machine-local override that outranks `coordinator.yml` outright — see
+# deploy/coord-drive-queue.service's own header for the full incident.
+DRIVE_QUEUE_UNIT_NAME = "coord-drive-queue.service"
+
+
+def default_systemd_user_unit_path(unit_name: str = DRIVE_QUEUE_UNIT_NAME) -> Path:
+    """Where a systemd *user* unit would be installed on THIS machine, if
+    it exists — ``~/.config/systemd/user/<unit_name>``. A bare path
+    computation; never asserts the file exists (see
+    :func:`read_systemd_max_parallel_flags`, the only caller that reads it).
+    """
+    return Path.home() / ".config" / "systemd" / "user" / unit_name
+
+
+def parse_max_parallel_flags_from_execstart(unit_text: str) -> dict[str, int]:
+    """Extract a hardcoded ``--max-parallel``/``--max-parallel-per-repo``
+    integer from a systemd unit's ``ExecStart=`` line (or, harmlessly, from
+    the whole unit file's text) (#3408). Pure and independently testable —
+    the sole reason this is split out from :func:`read_systemd_max_parallel_flags`,
+    which does the actual (unstubbable) file read.
+
+    ``--max-parallel-per-repo`` is checked before ``--max-parallel``: both
+    regexes require the character right after the flag name to be a space
+    or ``=``, so ``--max-parallel-per-repo 2`` is never misread as
+    ``--max-parallel`` with a stray ``-per-repo`` suffix — but per-repo is
+    still matched first here for readability, not correctness.
+
+    Returns ``{}`` when neither flag appears — indistinguishable, on
+    purpose, from "this text was not a real unit at all"; the caller
+    (:func:`read_systemd_max_parallel_flags`) folds an unreadable/missing
+    file into the same empty result, since both mean "no override known" to
+    every consumer of this function.
+    """
+    result: dict[str, int] = {}
+    per_repo_match = re.search(r"--max-parallel-per-repo[ =](\d+)", unit_text)
+    if per_repo_match:
+        result["max_parallel_per_repo"] = int(per_repo_match.group(1))
+    # `--max-parallel` must not also match the `--max-parallel-per-repo`
+    # occurrence above — requiring a space/`=` right after `max-parallel`
+    # means the character there is `-` for the per-repo flag, never a match.
+    max_parallel_match = re.search(r"--max-parallel[ =](\d+)", unit_text)
+    if max_parallel_match:
+        result["max_parallel"] = int(max_parallel_match.group(1))
+    return result
+
+
+def read_systemd_max_parallel_flags(unit_path: Path | None = None) -> dict[str, int]:
+    """Best-effort read of a locally-INSTALLED systemd user unit's hardcoded
+    ``--max-parallel``/``--max-parallel-per-repo`` (#3408) — the one source
+    that outranks `coordinator.yml` outright (#3388) and, before this, was
+    visible only via an SSH in and `systemctl --user cat`.
+
+    *unit_path* defaults to :func:`default_systemd_user_unit_path` (this
+    machine's own `~/.config/systemd/user/coord-drive-queue.service`);
+    passing an explicit path is how a test stubs this without touching a
+    real home directory or a real systemd install. Returns ``{}`` for
+    "absent", "unreadable" and "present but carries neither flag" alike —
+    every caller already treats an empty result as "no override known",
+    which is correct for a machine that simply is not the daemon host.
+    """
+    path = unit_path if unit_path is not None else default_systemd_user_unit_path()
+    try:
+        text = path.read_text()
+    except OSError:
+        return {}
+    return parse_max_parallel_flags_from_execstart(text)
+
+
+def compute_running_occupancy(
+    entries: Sequence["QueueEntry"],
+    board: "BoardView",
+    max_attempts: int,
+    *,
+    now: float | None = None,
+    local_host: str | None = None,
+) -> tuple[int, dict[str, int]]:
+    """Global and per-repo slot occupancy for the drive-queue's `running`
+    entries — the exact same "is this entry still occupying a slot?"
+    verdict :func:`plan_tick` itself uses (via :func:`_reconcile_running`),
+    factored out so a REPORT (`coord config --effective`'s "in flight"
+    line, #3408) can ask the identical question a launch decision asks,
+    rather than a second, independently-maintained count that could drift
+    from it (#2085's "one question, one answer").
+
+    Returns ``(global_occupied, {repo: occupied})``, matching
+    :attr:`TickPlan.occupied`/:attr:`TickPlan.repo_occupied`'s shape exactly
+    (this does not build a full :class:`TickPlan` — no reconciliation
+    writes, no launch walk — it only asks the occupancy question for each
+    currently-`running` entry).
+    """
+    occupied = 0
+    repo_occupied: dict[str, int] = {}
+    for entry in entries:
+        if entry.state != STATE_RUNNING:
+            continue
+        reconcile, _block = _reconcile_running(
+            entry,
+            board,
+            max_attempts,
+            now=now,
+            local_host=local_host,
+        )
+        if reconcile.occupies:
+            occupied += 1
+            repo_occupied[entry.repo] = repo_occupied.get(entry.repo, 0) + 1
+    return occupied, repo_occupied
+
+
 # ── the startup grace window (#1794) ─────────────────────────────────────────
 #
 # A drive is NOT established the instant `coord drive --tmux` exits 0.  #1606's