code-coordinator 0.5.511__tar.gz → 0.5.513__tar.gz

{code_coordinator-0.5.511 → code_coordinator-0.5.513}/PKG-INFO

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

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

@@ -76,6 +76,7 @@ coord/dr_promote.py
 coord/dr_verify.py
 coord/drive.py
 coord/drive_queue.py
+coord/drive_sessions_snapshot.py
 coord/drive_state.py
 coord/events.py
 coord/failure_class.py
@@ -509,6 +510,7 @@ tests/test_cli_issue_comment.py
 tests/test_cli_issue_create_label.py
 tests/test_cli_issue_reopen.py
 tests/test_cli_issue_view_list.py
+tests/test_cli_issues.py
 tests/test_cli_merge.py
 tests/test_cli_milestone_assign.py
 tests/test_cli_milestone_capture.py
@@ -622,6 +624,7 @@ 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
+tests/test_drive_sessions_snapshot.py
 tests/test_drive_state.py
 tests/test_drive_tmux.py
 tests/test_epic_up_capability_detection.py

{code_coordinator-0.5.511 → code_coordinator-0.5.513}/code_coordinator.egg-info/scm_file_list.json

@@ -136,6 +136,7 @@
     "coord/dr_verify.py",
     "coord/drive.py",
     "coord/drive_queue.py",
+    "coord/drive_sessions_snapshot.py",
     "coord/drive_state.py",
     "coord/events.py",
     "coord/failure_class.py",
@@ -535,6 +536,7 @@
     "tests/test_cli_issue_create_label.py",
     "tests/test_cli_issue_reopen.py",
     "tests/test_cli_issue_view_list.py",
+    "tests/test_cli_issues.py",
     "tests/test_cli_merge.py",
     "tests/test_cli_milestone_assign.py",
     "tests/test_cli_milestone_capture.py",
@@ -648,6 +650,7 @@
     "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",
+    "tests/test_drive_sessions_snapshot.py",
     "tests/test_drive_state.py",
     "tests/test_drive_tmux.py",
     "tests/test_epic_up_capability_detection.py",

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

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.513",
+  "distance": 0,
+  "node": "g62d2f7e1d36394c598063480dfdc2028204abbf1",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-21"
+}

{code_coordinator-0.5.511 → code_coordinator-0.5.513}/coord/board_schema.py

@@ -62,6 +62,11 @@ import typing
 from collections.abc import Mapping
 from typing import Any, Union
 
+# #3428: the `concurrency` block's `occupancy_state` value set — owned by the
+# snapshot module that produces it (see `BoardConcurrency` below).  Safe at
+# module scope: that module imports nothing from `coord` at import time.
+from coord.drive_sessions_snapshot import OCCUPANCY_UNOBSERVED
+
 #: What the read path actually hands the projection.  ``sqlite3.Row`` is *not*
 #: a ``Mapping`` (see :func:`_as_dict`), so it has to be named explicitly.
 RowLike = Union[Mapping[str, Any], sqlite3.Row]
@@ -310,6 +315,236 @@ class BoardDriveQueueEntry:
     apply_verdict_at: float | None = None
 
 
+# ── #3428 (#3408 item 3): concurrency ceilings + provenance + occupancy ──────
+#
+# The three dataclasses below are NOT a table projection — there is no
+# `concurrency` table — so they are absent from `BOARD_PROJECTIONS` and
+# `decode_row()` never touches them. They exist to give the *computed*
+# `coord.drive_queue.CeilingResolution` (already resolved on the daemon host
+# by `coord config --effective`'s own machinery — see that command's
+# docstring) an explicit wire shape, the same way `BoardAssignment` etc. give
+# one to a raw DB row. `coord/serve_app.py`'s `board()` handler builds a
+# `BoardConcurrency` per request (never persisted) and adds it to the
+# `/board` payload as the sibling key ``concurrency`` — same posture as
+# ``roll_pending``/``goal_header``: additive, absent-tolerant, never required.
+#
+# Deliberately does NOT import `coord.drive_queue` at module scope:
+# `coord.drive_queue` transitively imports THIS module (via
+# `coord.merge_queue` -> `coord.state` -> `coord.board_schema`), so a
+# top-level `from coord.drive_queue import CeilingResolution` here would be a
+# real import cycle, not just an ugly one. `CeilingResolution` is referenced
+# only for typing (`from __future__ import annotations` makes the annotation
+# itself lazy) and duck-typed at runtime by :func:`board_ceiling_from_resolution`.
+# (`coord.drive_sessions_snapshot`, which owns the `occupancy_state` value
+# set `BoardConcurrency` below defaults to, is by contrast imported at the
+# TOP of this file: it imports nothing from `coord` at module scope — its own
+# tmux/queue imports are deferred into `refresh()` — so it cannot close a
+# cycle back through here.)
+if typing.TYPE_CHECKING:  # pragma: no cover — typing only
+    from coord.drive_queue import CeilingResolution
+
+
+#: `BoardCeiling.source_kind` / `BoardCeilingSource.source_kind`'s closed
+#: value set (#3428) — a machine-readable classification of
+#: `CeilingResolution.source`'s free-text prose (written for `coord config
+#: --effective`'s human-readable output), so a client can style/filter a
+#: ceiling's provenance without string-matching wording that is free to
+#: change. See :func:`classify_ceiling_source` for the mapping.
+CEILING_SOURCE_KIND_SYSTEMD_FLAG = "systemd_flag"
+CEILING_SOURCE_KIND_CLI_FLAG = "cli_flag"
+CEILING_SOURCE_KIND_COORDINATOR_YML_REPO = "coordinator_yml_repo"
+CEILING_SOURCE_KIND_COORDINATOR_YML_PIPELINE = "coordinator_yml_pipeline"
+CEILING_SOURCE_KIND_COORDINATOR_YML_CONCURRENCY = "coordinator_yml_concurrency"
+CEILING_SOURCE_KIND_DERIVED = "derived"
+CEILING_SOURCE_KIND_DEFAULT = "default"
+#: A `CeilingResolution.source` this classifier doesn't recognise — should
+#: never actually appear on a real `/board` payload (every source string
+#: `coord.drive_queue`'s resolvers produce is covered below), but a client
+#: must still be able to parse it rather than choke: unlike the DTOs above,
+#: `source_kind` degrading to "unknown" is a display nit, not a #632-class
+#: parse failure.
+CEILING_SOURCE_KIND_UNKNOWN = "unknown"
+
+CEILING_SOURCE_KINDS: frozenset[str] = frozenset(
+    {
+        CEILING_SOURCE_KIND_SYSTEMD_FLAG,
+        CEILING_SOURCE_KIND_CLI_FLAG,
+        CEILING_SOURCE_KIND_COORDINATOR_YML_REPO,
+        CEILING_SOURCE_KIND_COORDINATOR_YML_PIPELINE,
+        CEILING_SOURCE_KIND_COORDINATOR_YML_CONCURRENCY,
+        CEILING_SOURCE_KIND_DERIVED,
+        CEILING_SOURCE_KIND_DEFAULT,
+        CEILING_SOURCE_KIND_UNKNOWN,
+    }
+)
+
+
+def classify_ceiling_source(source: str) -> str:
+    """Map one `CeilingResolution.source` (or one of its `losing` entries'
+    source names) prose string to a :data:`CEILING_SOURCE_KINDS` enum value.
+
+    Ordered by specificity, matching the exact strings
+    `coord.drive_queue`'s resolvers / `coord.commands.setup._print_effective_
+    concurrency` actually construct today:
+
+    * ``"systemd ExecStart --max-parallel..."`` (`read_systemd_max_parallel_
+      flags` via `coord.commands.setup`'s ``per_repo_source``/
+      ``max_parallel_source``) -> ``systemd_flag`` — the #3408 incident
+      source: a machine-local flag a thin client can never see for itself.
+    * ``"--max-parallel[-per-repo] flag"`` (an explicit CLI override on
+      `coord drive-queue tick`'s own invocation) -> ``cli_flag``.
+    * ``"coordinator.yml repos[<name>].max_parallel"`` (#3423 per-repo
+      override) -> ``coordinator_yml_repo``.
+    * ``"coordinator.yml pipeline.max_parallel..."`` -> ``coordinator_yml_pipeline``.
+    * ``"coordinator.yml concurrency.max_workers"`` (this module's own
+      synthetic resolution for the fleet worker cap — see
+      :func:`board_ceiling_from_resolution`'s caller in `coord/serve_app.py`)
+      -> ``coordinator_yml_concurrency``.
+    * ``"derived (...)"`` (`default_max_parallel`'s repo-shape derivation)
+      -> ``derived``.
+    * ``"default (...)"`` (the hardcoded fallback, config unreadable) ->
+      ``default``.
+    * anything else -> ``unknown`` (fail-soft; see that constant's docstring).
+    """
+    if source.startswith("systemd ExecStart"):
+        return CEILING_SOURCE_KIND_SYSTEMD_FLAG
+    if source.startswith("coordinator.yml repos["):
+        return CEILING_SOURCE_KIND_COORDINATOR_YML_REPO
+    if source.startswith("coordinator.yml pipeline."):
+        return CEILING_SOURCE_KIND_COORDINATOR_YML_PIPELINE
+    if source.startswith("coordinator.yml concurrency."):
+        return CEILING_SOURCE_KIND_COORDINATOR_YML_CONCURRENCY
+    if source.startswith("derived"):
+        return CEILING_SOURCE_KIND_DERIVED
+    if source.startswith("default"):
+        return CEILING_SOURCE_KIND_DEFAULT
+    if source.startswith("--") and source.endswith("flag"):
+        return CEILING_SOURCE_KIND_CLI_FLAG
+    return CEILING_SOURCE_KIND_UNKNOWN
+
+
+@dataclasses.dataclass(kw_only=True)
+class BoardCeilingSource:
+    """One LOSING source's own opinion for a :class:`BoardCeiling` (#3428) —
+    the wire twin of one ``(name, value)`` pair in a
+    `coord.drive_queue.CeilingResolution.losing` tuple. This is the whole
+    point of shipping provenance at all: it is what tells an operator that
+    editing ``coordinator.yml``/``coord-settings`` is futile while a
+    machine-local systemd flag outranks it (#3408's reported incident).
+    """
+
+    source: str
+    source_kind: str
+    value: int
+
+
+@dataclasses.dataclass(kw_only=True)
+class BoardCeiling:
+    """One resolved concurrency ceiling + provenance (#3428) — the `/board`
+    wire twin of `coord.drive_queue.CeilingResolution`, the exact resolution
+    `coord config --effective` and `coord drive-queue tick` itself already
+    use (#2085 "one question, one answer": this block is never a second,
+    independently-derived answer).
+
+    ``source`` carries the same free-text `CeilingResolution.source` a human
+    reads in `coord config --effective`'s output; ``source_kind`` is the
+    machine-readable classification of it (:func:`classify_ceiling_source`)
+    a client should actually branch on. ``losing`` is ``None`` (not ``[]``)
+    when nothing else was configured, matching `CeilingResolution.losing`'s
+    own "empty means nobody else had an opinion" contract.
+    """
+
+    name: str
+    value: int
+    source: str
+    source_kind: str
+    losing: list[BoardCeilingSource] | None = None
+
+
+def board_ceiling_from_resolution(resolution: "CeilingResolution") -> BoardCeiling:
+    """`coord.drive_queue.CeilingResolution` -> its `/board` wire shape.
+
+    Duck-typed on purpose (reads ``.name``/``.value``/``.source``/``.losing``
+    rather than importing the real class) — see the module note above this
+    section for why `coord.drive_queue` cannot be imported here at runtime.
+    """
+    losing = [
+        BoardCeilingSource(
+            source=name, source_kind=classify_ceiling_source(name), value=value
+        )
+        for name, value in resolution.losing
+    ] or None
+    return BoardCeiling(
+        name=resolution.name,
+        value=resolution.value,
+        source=resolution.source,
+        source_kind=classify_ceiling_source(resolution.source),
+        losing=losing,
+    )
+
+
+@dataclasses.dataclass(kw_only=True)
+class BoardConcurrency:
+    """The `/board` payload's ``concurrency`` block (#3428, #3408 item 3):
+    every ceiling `coord drive-queue tick` actually enforces, resolved on
+    THIS (the daemon) host, plus current occupancy against each.
+
+    **Resolved server-side, always** — the systemd-flag source
+    (:data:`CEILING_SOURCE_KIND_SYSTEMD_FLAG`) is machine-local and invisible
+    to a thin client (a Rust TUI, a phone webapp) by construction; a client
+    deriving ceilings from its own cached ``coordinator.yml`` would
+    confidently print the config value while a host-local flag silently
+    outranked it — the exact #3408 failure this block exists to end.
+
+    ``repo_overrides`` carries only the repos whose OWN ``repos[].max_parallel``
+    (#3423) actually differs from ``max_parallel_per_repo``'s fleet-wide
+    value — mirroring `coord.drive_queue.effective_repo_capacities`'s own
+    "only the repos that disagree" trim (see that function's docstring):
+    listing every repo would bury the ones that matter and make an
+    all-default fleet look like something was overridden everywhere.
+
+    ``occupied``/``repo_occupied`` are `coord.drive_queue.
+    compute_running_occupancy`'s own output, verbatim — the SAME "is this
+    entry still occupying a slot" verdict `plan_tick` enforces, never a
+    second, independently-recounted number (#2085 "one question, one
+    answer").
+
+    **Occupancy is nullable, and says why (#2096).** That verdict's first
+    question about a `running` entry is "is its drive session live?", which
+    only a ``tmux list-sessions`` reading can answer — and that reading is a
+    SUBPROCESS, so it is taken on the daemon's tick cadence
+    (`coord.drive_sessions_snapshot`), never inline off this read path (the
+    `/board` invariant 1 that `tests/test_board_read_path.py` enforces). When
+    the daemon has not taken a reading yet, or its refresh loop has stalled
+    (#2862) and the last one is too old to be evidence about now,
+    ``occupied``/``repo_occupied`` are ``None`` and ``occupancy_state`` says
+    which — never a confidently-wrong ``0`` that a client would render as
+    "all slots free". ``occupancy_observed_at`` is the wall-clock moment of
+    the reading behind the numbers (``None`` when there has never been one),
+    so a client can show — and age out — the numbers itself.
+
+    The CEILINGS are unaffected by any of that: they are resolved from
+    config + this host's systemd unit on every build, so they stay populated
+    even when occupancy is unknown.
+
+    Absent-tolerant in both directions (#3428 acceptance): an older daemon
+    simply omits the ``concurrency`` key entirely (never ships it as e.g. an
+    empty object), and a newer client must not require the key to parse an
+    otherwise-valid board.
+    """
+
+    max_parallel: BoardCeiling
+    max_parallel_per_repo: BoardCeiling
+    max_workers: BoardCeiling
+    repo_overrides: dict[str, BoardCeiling]
+    #: ``None`` unless ``occupancy_state`` is
+    #: :data:`~coord.drive_sessions_snapshot.OCCUPANCY_OBSERVED`.
+    occupied: int | None = None
+    repo_occupied: dict[str, int] | None = None
+    #: One of :data:`~coord.drive_sessions_snapshot.OCCUPANCY_STATES`.
+    occupancy_state: str = OCCUPANCY_UNOBSERVED
+    occupancy_observed_at: float | None = None
+
 
 #: ``table name`` → the DTO that defines its ``/board`` wire shape.  These are
 #: exactly the seven projections ``coord/serve_app.py`` publishes under

{code_coordinator-0.5.511 → code_coordinator-0.5.513}/coord/commands/issues.py

@@ -418,7 +418,13 @@ def issue_comment_cmd(
         "instead of a single freeform paragraph, so a later contract.md "
         "author (hand or agent) doesn't have to re-derive them from prose. "
         "All four are required together, and mutually exclusive with "
-        "--body/--body-file."
+        "--body/--body-file.\n\n"
+        "--milestone (number or title, resolved the same way as `coord "
+        "milestone assign`) attaches the new issue to a milestone in the "
+        "same step, routed through the same daemon seam "
+        "(`POST /issue-milestone`) so the local issues cache is updated "
+        "immediately. An unresolvable milestone is reported *before* the "
+        "issue is created (#3432)."
     ),
 )
 @click.argument("repo")
@@ -436,6 +442,16 @@ def issue_comment_cmd(
     multiple=True,
     help="Label to add (repeatable). The label must already exist in the repo.",
 )
+@click.option(
+    "--milestone",
+    default=None,
+    help=(
+        "Milestone number or title to attach the new issue to. Resolved "
+        "before the issue is created — an unresolvable milestone (bad "
+        "number, unmatched or ambiguous title) is an error and no issue is "
+        "created."
+    ),
+)
 @click.option(
     "--expected", default=None,
     help="Bug-lane intake field: what should happen, in observable terms.",
@@ -462,6 +478,7 @@ def issue_create_cmd(
     body: str | None,
     body_file: Path | None,
     labels: tuple[str, ...],
+    milestone: str | None,
     expected: str | None,
     actual: str | None,
     repro: str | None,
@@ -496,6 +513,26 @@ def issue_create_cmd(
     slug = _resolve_repo_slug(cfg, repo)
     if body_file is not None:
         body = sys.stdin.read() if str(body_file) == "-" else Path(body_file).read_text()
+
+    # Resolve --milestone *before* creating the issue (#3432) — creating the
+    # issue and then failing to attach it would silently reproduce the bug
+    # this closes (an issue that looks healthy but is unreachable from
+    # `coord.plans.aggregate_repo_plans`, which keys on milestone
+    # membership).
+    milestone_number: int | None = None
+    milestone_title: str | None = None
+    if milestone is not None:
+        from coord.commands.milestone import (  # noqa: PLC0415
+            MilestoneResolutionError,
+            resolve_milestone_ref,
+        )
+
+        try:
+            milestone_number, milestone_title = resolve_milestone_ref(slug, milestone)
+        except MilestoneResolutionError as e:
+            click.echo(f"error: {e}", err=True)
+            sys.exit(1)
+
     from coord.state import create_issue as _create_issue  # noqa: PLC0415
 
     try:
@@ -509,6 +546,31 @@ def issue_create_cmd(
         sys.exit(1)
     click.echo(f"#{result['number']} ({slug}) created")
 
+    if milestone_number is not None:
+        from coord.state import assign_issue_milestone  # noqa: PLC0415
+
+        try:
+            assign_issue_milestone(
+                repo,
+                result["number"],
+                milestone_number,
+                milestone_title=milestone_title,
+                repo_github=slug,
+            )
+        except Exception as e:  # noqa: BLE001
+            click.echo(
+                f"error: issue #{result['number']} created but milestone "
+                f"assign failed: {e}",
+                err=True,
+            )
+            sys.exit(1)
+        ms_label = (
+            f"{milestone_title!r} (#{milestone_number})"
+            if milestone_title
+            else f"#{milestone_number}"
+        )
+        click.echo(f"#{result['number']} ({slug}) assigned to milestone {ms_label}")
+
 
 @issue_group.command(
     "label",

{code_coordinator-0.5.511 → code_coordinator-0.5.513}/coord/commands/milestone.py

@@ -165,6 +165,52 @@ def milestone_edit_cmd(
     click.echo(f"milestone #{number} updated ({repo_entry.github})")
 
 
+class MilestoneResolutionError(Exception):
+    """Raised by :func:`resolve_milestone_ref` when MILESTONE can't be
+    resolved to a number."""
+
+
+def resolve_milestone_ref(repo_github: str, milestone: str) -> tuple[int, str | None]:
+    """Resolve a milestone CLI argument (number or title) to ``(number,
+    title)`` against ``repo_github``'s open milestones.
+
+    Shared by `coord milestone assign` and `coord issue create --milestone`
+    (#3432) so there is exactly one place milestone-reference resolution
+    happens — raises :class:`MilestoneResolutionError` (never exits) on any
+    failure: an unfetchable numeric milestone, an unmatched title, or an
+    ambiguous title. Callers decide how to report/exit.
+    """
+    from coord import github_ops  # noqa: PLC0415
+
+    try:
+        milestone_number = int(milestone)
+    except ValueError:
+        try:
+            all_ms = github_ops.get_repo_milestones(repo_github)
+        except RuntimeError as e:
+            raise MilestoneResolutionError(f"could not list milestones: {e}") from e
+        matches = [m for m in all_ms if m.get("title") == milestone]
+        if not matches:
+            raise MilestoneResolutionError(
+                f"no open milestone with title {milestone!r} in {repo_github}"
+            )
+        if len(matches) > 1:
+            raise MilestoneResolutionError(
+                f"multiple open milestones match {milestone!r} — use the "
+                "milestone number instead"
+            )
+        return matches[0]["number"], matches[0].get("title")
+
+    # Resolve the title from the number so the cache can store it.
+    try:
+        ms_data = github_ops.get_milestone(repo_github, milestone_number)
+    except RuntimeError as e:
+        raise MilestoneResolutionError(
+            f"could not fetch milestone #{milestone_number}: {e}"
+        ) from e
+    return milestone_number, ms_data.get("title")
+
+
 @milestone_group.command(
     "assign",
     help=(
@@ -194,47 +240,15 @@ def milestone_assign_cmd(
         click.echo(f"error: unknown repo {repo!r}", err=True)
         sys.exit(2)
 
-    from coord import github_ops  # noqa: PLC0415
     from coord.state import assign_issue_milestone  # noqa: PLC0415
 
-    # Resolve milestone argument: numeric → number, string → title lookup.
-    milestone_number: int
-    milestone_title: str | None
-
     try:
-        milestone_number = int(milestone)
-        # Resolve the title from the number so the cache can store it.
-        try:
-            ms_data = github_ops.get_milestone(repo_entry.github, milestone_number)
-            milestone_title = ms_data.get("title")
-        except RuntimeError as e:
-            click.echo(
-                f"error: could not fetch milestone #{milestone_number}: {e}", err=True
-            )
-            sys.exit(1)
-    except ValueError:
-        # Treat the argument as a title and resolve to a number.
-        try:
-            all_ms = github_ops.get_repo_milestones(repo_entry.github)
-        except RuntimeError as e:
-            click.echo(f"error: could not list milestones: {e}", err=True)
-            sys.exit(1)
-        matches = [m for m in all_ms if m.get("title") == milestone]
-        if not matches:
-            click.echo(
-                f"error: no open milestone with title {milestone!r} in {repo_entry.github}",
-                err=True,
-            )
-            sys.exit(1)
-        if len(matches) > 1:
-            click.echo(
-                f"error: multiple open milestones match {milestone!r} — "
-                "use the milestone number instead",
-                err=True,
-            )
-            sys.exit(1)
-        milestone_number = matches[0]["number"]
-        milestone_title = matches[0].get("title")
+        milestone_number, milestone_title = resolve_milestone_ref(
+            repo_entry.github, milestone
+        )
+    except MilestoneResolutionError as e:
+        click.echo(f"error: {e}", err=True)
+        sys.exit(1)
 
     try:
         assign_issue_milestone(

{code_coordinator-0.5.511 → code_coordinator-0.5.513}/coord/drive_queue.py

@@ -988,6 +988,109 @@ def compute_running_occupancy(
     return occupied, repo_occupied
 
 
+@dataclass(frozen=True)
+class ConcurrencyReport:
+    """Every concurrency ceiling `coord drive-queue tick` enforces, resolved
+    together in the SAME order + SAME primitives ``coord config --effective``
+    (`coord.commands.setup._print_effective_concurrency`) already applies
+    (#3408), plus current occupancy against each — the one call a daemon-host
+    caller should make rather than re-deriving the wiring itself (#3428,
+    #2085 "one question, one answer").
+
+    ``repo_resolutions`` is EVERY repo's own :class:`CeilingResolution`
+    (#3423), keyed by name — :func:`resolve_repo_ceilings`'s full table.
+    ``repo_overrides`` is the trimmed subset that actually differs from
+    ``max_parallel_per_repo``'s fleet-wide value —
+    :func:`effective_repo_capacities`'s own shape, and also what
+    ``max_parallel``'s own resolution is computed against (a repo with no
+    override contributes the fleet figure to that sum, not its own name).
+    """
+
+    max_parallel: CeilingResolution
+    max_parallel_per_repo: CeilingResolution
+    max_workers: CeilingResolution
+    repo_resolutions: dict[str, CeilingResolution]
+    repo_overrides: dict[str, int]
+    occupied: int
+    repo_occupied: dict[str, int]
+
+
+def resolve_concurrency_report(
+    *,
+    repo_overrides: Mapping[str, int | None],
+    pipeline_max_parallel: int | None,
+    pipeline_max_parallel_per_repo: int | None,
+    max_workers_cap: int,
+    systemd_flags: Mapping[str, int] | None = None,
+    entries: Sequence["QueueEntry"] = (),
+    board: "BoardView | None" = None,
+    max_attempts: int = DEFAULT_MAX_ATTEMPTS,
+    now: float | None = None,
+    local_host: str | None = None,
+) -> ConcurrencyReport:
+    """Resolve every concurrency ceiling in one call (#3428).
+
+    *repo_overrides* is ``{repo_name: repos[].max_parallel or None}`` for
+    EVERY repo in the fleet (not just the overridden ones — see
+    :func:`resolve_repo_ceilings`). *systemd_flags* defaults to a fresh
+    :func:`read_systemd_max_parallel_flags` read of THIS machine's own
+    installed unit when not given (a caller with an already-read dict, e.g.
+    a test, passes it explicitly rather than touching the filesystem).
+
+    *board*/*entries* are `compute_running_occupancy`'s own arguments;
+    *board* left ``None`` (the default) skips occupancy entirely
+    (``occupied=0``, ``repo_occupied={}``) rather than raising — a caller
+    that only wants the ceilings (no live queue state) does not need to
+    fabricate an empty :class:`BoardView`.
+    """
+    flags = systemd_flags if systemd_flags is not None else read_systemd_max_parallel_flags()
+
+    per_repo_resolution = resolve_max_parallel_per_repo(
+        override_value=flags.get("max_parallel_per_repo"),
+        override_source="systemd ExecStart --max-parallel-per-repo",
+        config_value=pipeline_max_parallel_per_repo,
+    )
+    repo_resolutions = resolve_repo_ceilings(repo_overrides, fleet=per_repo_resolution)
+    effective_repo_overrides = effective_repo_capacities(
+        repo_resolutions, fleet_value=per_repo_resolution.value
+    )
+
+    global_resolution = resolve_max_parallel(
+        override_value=flags.get("max_parallel"),
+        override_source="systemd ExecStart --max-parallel",
+        config_value=pipeline_max_parallel,
+        repo_count=len(repo_overrides),
+        max_parallel_per_repo=per_repo_resolution.value,
+        max_workers_cap=max_workers_cap,
+        repo_overrides=effective_repo_overrides,
+    )
+    # `concurrency.max_workers` has exactly one source today — nothing can
+    # beat `coordinator.yml`'s own value — but the wire/report shape stays
+    # uniform across all three ceilings (#3428's own contract), so it is
+    # wrapped in the same `CeilingResolution` shape the other two use, with
+    # an always-empty `losing`.
+    max_workers_resolution = CeilingResolution(
+        "max_workers", max_workers_cap, "coordinator.yml concurrency.max_workers"
+    )
+
+    if board is not None:
+        occupied, repo_occupied = compute_running_occupancy(
+            entries, board, max_attempts, now=now, local_host=local_host
+        )
+    else:
+        occupied, repo_occupied = 0, {}
+
+    return ConcurrencyReport(
+        max_parallel=global_resolution,
+        max_parallel_per_repo=per_repo_resolution,
+        max_workers=max_workers_resolution,
+        repo_resolutions=repo_resolutions,
+        repo_overrides=effective_repo_overrides,
+        occupied=occupied,
+        repo_occupied=repo_occupied,
+    )
+
+
 # ── the startup grace window (#1794) ─────────────────────────────────────────
 #
 # A drive is NOT established the instant `coord drive --tmux` exits 0.  #1606's