code-coordinator 0.5.507__tar.gz → 0.5.509__tar.gz

{code_coordinator-0.5.507 → code_coordinator-0.5.509}/CLAUDE.md

@@ -2,20 +2,21 @@
 
 CLI tool + per-machine agent server that coordinates Claude Code workers across multiple machines and repos over Tailscale.
 
-> **Scope of this file (#2195).** This is the **worker- and reviewer-facing** rulebook: it is
-> loaded into every worker leg, every review leg, and every coordinator session — and re-read on
-> every turn of each — so it holds only what someone *editing this repo* must act on. Operator
-> runbooks live in [`docs/`](docs/), indexed by
-> [`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md). Settled design rationale lives in
-> [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
-> Keep it that way: **if a new rule does not change what a worker does, it belongs in `docs/`.**
-> Operator sessions — the "dispatch, don't do" rule now lives in
-> [`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md); read it before hand-editing any tracked
-> repo. If you're a worker or reviewer leg, that one isn't for you.
-
-## Current Goal — read first
-
-**[`GOAL.md`](GOAL.md) holds the current north-star objective** — the living, cross-repo / cross-machine goal that should bias all planning, triage, and dispatch. It is meta-level (above any single issue, repo, or session) and changes as priorities evolve: read it first, plan against it, and keep it current. `coordinator.yml` is the source of truth for *topology*; `GOAL.md` is the source of truth for *intent*.
+> **Scope of this file (#2195, #2817).** This is the **worker- and reviewer-facing**
+> rulebook: it is loaded into every worker leg, every review leg and every coordinator
+> session — and re-read on **every turn** of each, so every byte here is a recurring
+> fleet-wide cost. It holds only what someone *editing this repo* must act on.
+> **If a new rule does not change what a worker does, it belongs in [`docs/`](docs/).**
+> `tests/test_claude_md_budget.py` enforces that with a byte cap — move a section out
+> rather than raise it.
+>
+> Not here: operator runbooks ([`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md)) ·
+> settled design rationale
+> ([`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale)) ·
+> the `coord` command reference (`coord <cmd> --help`) · operator cost rules and
+> "dispatch, don't do" ([`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md)) ·
+> the current north-star objective ([`GOAL.md`](GOAL.md) — read it in a coordinator
+> session when planning or triaging; a worker or reviewer leg does not need it).
 
 ## Codebase navigation — query the graph first
 
@@ -64,22 +65,11 @@ Query the **graphify graph** (`graphify-out/`) for the full module map + relatio
 
 ## Commands
 
-`coord <cmd> --help` documents every command + flags. The core loop:
-
-```bash
-coord plan                 # Brain proposes assignments for idle machines
-coord approve 1,3          # Dispatch approved proposals (comma-separated IDs)
-coord assign <machine> <repo> <issue> [--briefing TEXT | --briefing-file F] [--dry-run]  # Direct dispatch
-coord status [--freshness] # Machines, assignments, connectivity (+ repo freshness vs GitHub HEADs)
-coord log <id> [-f] [--machine NAME]            # claude -p output (remote logs need --machine)
-coord notify               # Poll agents, post completion/failure comments to GitHub
-coord test --passed|--fail|--skipped <id>       # Record the Test-gate verdict (bare `coord test <id>` builds+tests locally)
-coord merge [--dry-run] [--repo NAME] [--method rebase|squash|merge] [--order IDs] [--force-merge]
-coord reconcile-merges     # Backfill missing branches + record out-of-band merges (#609/#611)
-coord retry|stop|resume <id>                    # Recovery; `coord done` ends the session
-```
-
-Setup / diagnostics (discoverable via `--help`): `coord init`, `coord config`, `coord agent`, `coord serve`, `coord web`, `coord diagnose`, `coord sessions [--remote]`, `coord split`, `coord notifier`, `coord repo add` / `coord repo doctor`.
+`coord <cmd> --help` documents every command and flag — that is the reference, not this
+file. The operator-facing core loop (`plan`/`approve`/`assign`/`status`/`merge`/...) is in
+[`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md#the-core-loop). The one `coord` command
+a **worker** runs is `coord acceptance run --issue N`, in an oracle-loop round (see Testing
+below).
 
 ## Development
 
@@ -133,34 +123,22 @@ computes the routing without actually building or testing anything.
 
 ## Key Design Decisions
 
-One line each — the reasoning behind them is in
-[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
-
-- **No API key needed.** Everything uses `claude -p`, which runs on a Max/Pro subscription via OAuth.
-- **Agent servers are dumb dispatchers.** They spawn `claude -p` and track the subprocess; all intelligence is in the coordinator brain.
-- **GitHub issue comments are the message bus.** Briefings, completion notices and failure reports are comments, carrying `<!-- coord:... -->` markers for machine parsing.
-- **`coordinator.yml` is the single source of truth** for repo topology, machine capabilities, dependencies, concurrency limits, review settings, smoke-test rules, and the pipeline gate order (`pipeline.default_gates`). It lives in `~/.coord/`, **not** the repo checkout.
-- **User approves everything.** `coord plan` proposes, the user reviews, `coord approve` dispatches. No autonomous dispatch.
-- **Claim detection prevents duplicate work.** Before dispatching, the coordinator checks the board for active assignments and the remote for `issue-{N}-*` branches.
-- **Conflict rules are inferred, not configured.** There is no `file_groups`/`exclusive_files` config and never will be. `coord drive-queue add` compares an issue's own `## Files` declaration against the **real diffs** of in-flight branches in that repo (`coord/overlap_predict.py`, #2247) and, on an overlap, chains the newcomer `--after` the incumbent. **It ORDERS, never refuses** — a false positive costs latency, a refusal costs work. Accuracy is measured, not assumed: `coord drive-queue overlap-report`.
-- **Adversarial reviews are rule-enforcing, not rubber-stamping.** On worker completion a fresh `claude -p` session on a *different* machine reviews the PR diff against this file and the review checklist, with zero shared context with the worker — that's the whole point.
-- **The pipeline order is `Work → Test → Review → Merge`.** Test precedes Review; the headless auto-loop holds review dispatch until there is a `passed`/`skipped` test verdict.
-- **Merge is gated on CI checks (#240).** `coord merge` refuses when a check failed or is still running — and a PR with *zero* reported checks is not automatically clear either (#1904).
-- **Mechanical merge conflicts auto-rebase (#241).** A `type="conflict-fix"` worker rebases and resolves additive merges; semantic conflicts are left for a human.
-- **Smoke tests validate on capable hardware.** `smoke_tests.capability_rules` map changed files to required machine capabilities (e.g. GTK changes → a machine with GTK).
-- **Progress streaming from workers.** Workers emit `STATUS:` and `STUCK:` lines; the coordinator parses these for real-time progress in `coord status` and the dashboard.
-- **The notifier tells you when NOBODY IS COMING — and nothing else (#1632).** Advisory, isolated, off by default; it is not an error channel and not a progress feed.
-
-## Review Prompt Assembly
-
-The reviewer gets a prompt built from:
-1. **Repo's CLAUDE.md** — the project rules (source of truth, not duplicated)
-2. **Generic checklist** — "did you add tests?", "did you stay in file scope?", "any security issues?"
-3. **Repo overrides** — project-specific patterns from `coordinator.yml` `reviews.repo_overrides`
-4. **The diff** — `gh pr diff` of the worker's branch vs base
-5. **The issue** — title and body for intent verification
-
-The reviewer reads the rules and enforces them against the diff. It does not have the worker's session context — genuinely independent.
+These are the ones a **diff** can violate. The full set, with the reasoning behind each, is
+in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
+
+- **`coordinator.yml` is the single source of truth** for repo topology, machine
+  capabilities, dependencies, concurrency limits, review settings, smoke-test rules and the
+  pipeline gate order (`pipeline.default_gates`). It lives in `~/.coord/`, **not** the repo
+  checkout.
+- **Conflict rules are inferred, not configured.** There is no `file_groups` /
+  `exclusive_files` config and never will be — `coord drive-queue add` compares an issue's
+  own `## Files` declaration against the **real diffs** of in-flight branches
+  (`coord/overlap_predict.py`, #2247). **It ORDERS, never refuses.** Do not add such config.
+- **The pipeline order is `Work → Test → Review → Merge`.** Test precedes Review; the
+  headless auto-loop holds review dispatch until there is a `passed`/`skipped` verdict.
+- **Adversarial reviews are rule-enforcing, not rubber-stamping.** A fresh `claude -p`
+  session on a *different* machine reviews your diff against this file, with **zero shared
+  context with you** — so your diff and final message must stand on their own.
 
 ## Rules for workers
 
@@ -212,7 +190,5 @@ versus keep in the coordinator session, and the coordinator session's own
 
 ## Operating the fleet — operator-facing
 
-**Not needed to work on this repo.** A worker or reviewer can stop reading here. Every operator
-runbook — the pre-flight gotchas, agent installs and releases, the drive queue, the customer
-portal, and the two deploy facts that bite most often — is indexed in
+**Not needed to work on this repo.** Every operator runbook is indexed in
 [`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md).

{code_coordinator-0.5.507 → code_coordinator-0.5.509}/PKG-INFO

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

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

@@ -788,6 +788,7 @@ tests/test_repo_add.py
 tests/test_repo_dormancy.py
 tests/test_repo_edit_2220.py
 tests/test_repo_graph_fleet_2237.py
+tests/test_repo_max_parallel_3423.py
 tests/test_repo_onboard_2220.py
 tests/test_report_result_push.py
 tests/test_reports.py

{code_coordinator-0.5.507 → code_coordinator-0.5.509}/code_coordinator.egg-info/scm_file_list.json

@@ -814,6 +814,7 @@
     "tests/test_repo_dormancy.py",
     "tests/test_repo_edit_2220.py",
     "tests/test_repo_graph_fleet_2237.py",
+    "tests/test_repo_max_parallel_3423.py",
     "tests/test_repo_onboard_2220.py",
     "tests/test_report_result_push.py",
     "tests/test_reports.py",

{code_coordinator-0.5.507 → code_coordinator-0.5.509}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.507",
+  "tag": "0.5.509",
   "distance": 0,
-  "node": "g77eaf6af7d9e29387584dbfe661ea201eb62e524",
+  "node": "gace3f38afa44e85a17064892c36412cab13d0d34",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-20"

{code_coordinator-0.5.507 → code_coordinator-0.5.509}/coord/agent.py

@@ -5062,6 +5062,136 @@ def _claude_md_system_prompt_suffix(repo_path: str) -> str:
     return "\n\n## Project rules (from CLAUDE.md)\n\n" + claude_md.strip() + "\n"
 
 
+# #3420: every `claude -p` leg loads the full JSON schema for all built-in
+# tools regardless of `--allowedTools`, which is a *permission* filter, not a
+# tool-surface one — a leg with `Read,Bash` in `--allowedTools` still pays
+# the prompt-token cost of the `Workflow`/`Skill`/etc. schemas it can never
+# call. Measured with controlled `claude -p` probes on this repo's own
+# `default_worker_command` flags (Claude Code 2.1.278, `type="work"`): the
+# schemas for these tools cost 12,134 tokens/turn (44% of the static
+# prefix), re-read at cache-read rates on every turn of every leg. None of
+# them has a legitimate use from a headless coord leg:
+#   - `Workflow`: requires explicit user opt-in; a headless leg has no user.
+#   - `Skill`: all `coord` skills are operator-only runbooks.
+#   - `ScheduleWakeup`: every leg is one-shot (WORKER_SYSTEM_PROMPT's
+#     ONE-SHOT section, #1394) — there is no future turn to wake up into.
+#   - `Task`: CLAUDE.md mandates `graphify query` + grep for navigation
+#     instead of spawning a subagent.
+#   - `ReportFindings`, `ListAgents`: unreferenced by any coord system
+#     prompt; no fleet-messaging or review-findings-reporting surface is
+#     exposed to a leg.
+#   - The remainder (`Cron*`, `DesignSync`, `EnterWorktree`/`ExitWorktree`,
+#     `NotebookEdit`, `PushNotification`, `RemoteTrigger`, `SendMessage`):
+#     operator/coordinator-session tools with no worker-leg counterpart —
+#     already deferred behind `ToolSearch` so each costs only ~6-9 tokens,
+#     but included for a consistent, minimal tool surface.
+#
+# Deliberately EXCLUDED, despite being equally unusable:
+#   - `Monitor`: 0 marginal token cost, and WORKER_SYSTEM_PROMPT's ONE-SHOT
+#     polling guidance depends on it (it's the sanctioned way to await a
+#     backgrounded command in bounded steps).
+#   - `ToolSearch`: cheap on its own, and removing it is untested — it's the
+#     mechanism that resolves every deferred tool name at all.
+#   - `TaskOutput`/`TaskStop`: look like `Task`'s output/cancel pair at
+#     first glance, but WORKER_SYSTEM_PROMPT's ONE-SHOT section and
+#     coord/smoke.py's SMOKE_SYSTEM_PROMPT both explicitly teach
+#     `TaskOutput` as the bounded-poll alternative to `Monitor` for a
+#     backgrounded Bash command (`run_in_background`) — disallowing it
+#     would make that documented guidance a dead end. `TaskStop` is kept
+#     alongside it since it's the same background-job-management pair.
+#   - `WebFetch`/`WebSearch`: ~6 tokens each either way (negligible), and a
+#     worker may legitimately need to look up library docs or an error
+#     message mid-task — kept allowed rather than trading real capability
+#     for a rounding error in prompt size.
+UNUSABLE_TOOL_SCHEMAS: list[str] = [
+    "Workflow",
+    "Skill",
+    "ScheduleWakeup",
+    "Task",
+    "ReportFindings",
+    "ListAgents",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "DesignSync",
+    "EnterWorktree",
+    "ExitWorktree",
+    "NotebookEdit",
+    "PushNotification",
+    "RemoteTrigger",
+    "SendMessage",
+]
+
+
+def worker_disallowed_tools(spec: AssignmentSpec, allowed_tools: str) -> list[str]:
+    """Return the ordered ``--disallowedTools`` entries for *spec*.
+
+    **Single source of truth.** Both argv builders that emit
+    ``--disallowedTools`` — :func:`default_worker_command` and
+    :meth:`coord.providers.claude.ClaudeProvider.build_command` — call
+    this, rather than each reimplementing the same four-layer stack. The
+    two previously transcribed the logic independently, which is exactly
+    how #3420's ``UNUSABLE_TOOL_SCHEMAS`` layer landed in one and not the
+    other; the parity suite in ``tests/test_providers.py`` caught it, but
+    a shared function makes the divergence unrepresentable instead of
+    merely detectable.
+
+    Layers, in argv order (each skips entries an earlier layer already
+    added, so the result is de-duplicated but order-stable):
+
+    1. #3420 ``UNUSABLE_TOOL_SCHEMAS`` — unconditional, every spec type.
+    2. #1315 sealed-oracle write guard, from ``spec.files_forbidden``.
+    3. #1642 base-checkout write guard — only when *allowed_tools*
+       actually grants ``Edit``; for the Read/Bash-only chat types the
+       guard would be a no-op cluttering the argv.
+    4. #2461 ``REVIEW_DENY_COMMANDS`` — only for ``spec.type ==
+       "review"``, wiring the mutating-command deny list into the
+       CLI-enforced flag and not just the soft prompt reminder.
+
+    Args:
+        spec: The assignment being dispatched.
+        allowed_tools: The ``--allowedTools`` value computed for this
+            spec — inspected for ``Edit`` to decide layer 3. Passing the
+            caller's own computed value (rather than re-deriving it here)
+            keeps the two flags consistent even when a caller overrides
+            ``--allowedTools`` explicitly, as ``build_command`` allows.
+
+    Returns:
+        A fresh list; callers may mutate it. Empty only in the
+        impossible case where every layer contributes nothing — since
+        #3420, layer 1 is unconditional, so in practice this is always
+        non-empty and ``--disallowedTools`` is always emitted.
+    """
+    # #3420: strip the unusable-tool schemas from every spec type, including
+    # the Read/Bash-only chat legs (plan, refinement, test-chat,
+    # new-issue-chat, smoke, review) — they carry the same
+    # Workflow/Skill/Task/etc. schemas as a work leg and benefit identically.
+    # This is FIRST so the guards below, which each append to this same
+    # list, keep working unchanged.
+    disallowed_tools = list(UNUSABLE_TOOL_SCHEMAS)
+    # #1315: structural sealing enforcement — see _sealed_write_guard_tools.
+    for pattern in _sealed_write_guard_tools(spec.files_forbidden):
+        if pattern not in disallowed_tools:
+            disallowed_tools.append(pattern)
+    # #1642: block Edit/Write on the shared base checkout for any spec.type
+    # that actually gets Edit/Write in --allowedTools — the Read/Bash-only
+    # chat types can't touch files regardless, and adding the guard there
+    # would be a no-op cluttering their argv for nothing.
+    if "Edit" in allowed_tools:
+        for pattern in _base_checkout_write_guard_tools(spec.repo_path):
+            if pattern not in disallowed_tools:
+                disallowed_tools.append(pattern)
+    # #2461: review gets its mutating-command deny list wired into
+    # --disallowedTools too, not just the soft system-prompt reminder from
+    # build_deny_prompt — the CLI enforces this one even if the model
+    # decides to ignore its own prompt.
+    if spec.type == "review":
+        for pattern in REVIEW_DENY_COMMANDS:
+            if pattern not in disallowed_tools:
+                disallowed_tools.append(pattern)
+    return disallowed_tools
+
+
 def default_worker_command(spec: AssignmentSpec, *, binary: str = DEFAULT_WORKER_BINARY) -> list[str]:
     """Build the argv for invoking the worker on this assignment.
 
@@ -5347,24 +5477,10 @@ def default_worker_command(spec: AssignmentSpec, *, binary: str = DEFAULT_WORKER
     ]
     if spec.model:
         argv.extend(["--model", spec.model])
-    # #1315: structural sealing enforcement — see _sealed_write_guard_tools.
-    disallowed_tools = _sealed_write_guard_tools(spec.files_forbidden)
-    # #1642: block Edit/Write on the shared base checkout for any spec.type
-    # that actually gets Edit/Write in --allowedTools — the Read/Bash-only
-    # chat types above can't touch files regardless, and adding the guard
-    # there would be a no-op cluttering their argv for nothing.
-    if "Edit" in allowed_tools:
-        for pattern in _base_checkout_write_guard_tools(spec.repo_path):
-            if pattern not in disallowed_tools:
-                disallowed_tools.append(pattern)
-    # #2461: review gets its mutating-command deny list wired into
-    # --disallowedTools too, not just the soft system-prompt reminder from
-    # build_deny_prompt above — the CLI enforces this one even if the model
-    # decides to ignore its own prompt.
-    if spec.type == "review":
-        for pattern in REVIEW_DENY_COMMANDS:
-            if pattern not in disallowed_tools:
-                disallowed_tools.append(pattern)
+    # #3420 / #1315 / #1642 / #2461: all four --disallowedTools layers live
+    # in worker_disallowed_tools, shared with ClaudeProvider.build_command so
+    # the two argv builders cannot drift apart (see that function's docstring).
+    disallowed_tools = worker_disallowed_tools(spec, allowed_tools)
     if disallowed_tools:
         argv.extend(["--disallowedTools", ",".join(disallowed_tools)])
     # #315: when resuming a prior chat session, load the prior conversation so

{code_coordinator-0.5.507 → code_coordinator-0.5.509}/coord/commands/drive_queue.py

@@ -101,8 +101,10 @@ from coord.drive_queue import (
     plan_tick,
     remaining_fix_rounds,
     render_plan,
+    effective_repo_capacities,
     resolve_max_parallel,
     resolve_max_parallel_per_repo,
+    resolve_repo_ceilings,
     total_fix_round_budget,
     unreachable_wait_alert,
     validate_apply_gate,
@@ -6226,25 +6228,45 @@ def drive_queue_tick(
     _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(
+    _flag_max_parallel_per_repo = max_parallel_per_repo
+    _per_repo_resolution = 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
+    )
+    max_parallel_per_repo = _per_repo_resolution.value
 
     if max_parallel_per_repo < 0:
         raise click.ClickException(
             "--max-parallel-per-repo must be 0 (no per-repo ceiling) or more"
         )
 
+    # #3423: each repo's OWN ceiling (`repos[].max_parallel`), layered on the
+    # fleet-wide answer just resolved. Only the repos that actually DIFFER
+    # are carried into the tick, so a fleet with no overrides produces the
+    # identical `TickPlan` (and identical `render_plan` output) it did
+    # before. `resolve_repo_ceilings` is the SAME function `coord config
+    # --effective` reports through, for the same reason as the two ceilings
+    # above: one resolution order, not two that could drift (#2085).
+    _repo_ceilings = resolve_repo_ceilings(
+        {} if _cfg is None else {r.name: r.max_parallel for r in _cfg.repos},
+        fleet=_per_repo_resolution,
+    )
+    repo_max_parallel = effective_repo_capacities(
+        _repo_ceilings, fleet_value=max_parallel_per_repo
+    )
+    # Emitted after the per-repo table exists so the #3408 warning can name
+    # the repos whose own ceiling beats the flag anyway (#3423).
+    _shadow_warning = flag_shadows_config_warning(
+        flag_name="max-parallel-per-repo",
+        override_value=_flag_max_parallel_per_repo,
+        config_key="pipeline.max_parallel_per_repo",
+        config_value=_config_max_parallel_per_repo,
+        overridden_repos=sorted(repo_max_parallel),
+    )
+    if _shadow_warning:
+        click.echo(_shadow_warning)
+
     # #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
@@ -6272,6 +6294,11 @@ def drive_queue_tick(
         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,
+        # #3423: the derivation must sum the per-repo ceilings, not multiply
+        # by the fleet default — raising one repo to 2 without widening the
+        # global ceiling to match re-creates exactly the starvation #3388
+        # was opened for.
+        repo_overrides=repo_max_parallel,
     ).value
 
     if max_parallel < 0:
@@ -6522,6 +6549,7 @@ def drive_queue_tick(
             board,
             effective_capacity,
             max_parallel_per_repo=max_parallel_per_repo,
+            repo_max_parallel=repo_max_parallel,
             probes=probes,
             now=now,
             local_host=_local_host_id(),

{code_coordinator-0.5.507 → code_coordinator-0.5.509}/coord/commands/setup.py

@@ -20,6 +20,8 @@ from coord.commands._common import _CONFIG_OPTION, _load_config
 import json
 
 if TYPE_CHECKING:  # pragma: no cover — typing only
+    from collections.abc import Mapping
+
     from coord.config import Config
     from coord.drive_queue import CeilingResolution
 
@@ -183,10 +185,12 @@ def _print_effective_concurrency(
     machine's own installed systemd unit, if any.
     """
     from coord.drive_queue import (  # noqa: PLC0415
+        effective_repo_capacities,
         flag_shadows_config_warning,
         read_systemd_max_parallel_flags,
         resolve_max_parallel,
         resolve_max_parallel_per_repo,
+        resolve_repo_ceilings,
     )
 
     systemd_flags = read_systemd_max_parallel_flags()
@@ -202,11 +206,26 @@ def _print_effective_concurrency(
         override_source=per_repo_source,
         config_value=cfg.pipeline.max_parallel_per_repo,
     )
+    # #3423: each repo's own `repos[].max_parallel`, layered on the
+    # fleet-wide answer above. Reported per repo below — a single
+    # `max_parallel_per_repo` line stopped being the whole truth the moment
+    # one repo could disagree with it, and "which ceiling actually applies
+    # to MY repo" is the same question #3408 was opened to answer.
+    repo_resolutions = resolve_repo_ceilings(
+        {r.name: r.max_parallel for r in cfg.repos}, fleet=per_repo_resolution
+    )
+    repo_overrides = effective_repo_capacities(
+        repo_resolutions, fleet_value=per_repo_resolution.value
+    )
     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,
+        # #3423: computed after the per-repo table above so the warning can
+        # name the repos that beat the flag — "always wins" would otherwise
+        # be contradicted by the very next line this function prints.
+        overridden_repos=sorted(repo_overrides),
     )
 
     max_parallel_override = sim_max_parallel
@@ -222,6 +241,7 @@ def _print_effective_concurrency(
         repo_count=len(cfg.repos),
         max_parallel_per_repo=per_repo_resolution.value,
         max_workers_cap=cfg.concurrency.max_workers,
+        repo_overrides=repo_overrides,
     )
     global_warning = flag_shadows_config_warning(
         flag_name="max-parallel",
@@ -239,16 +259,26 @@ def _print_effective_concurrency(
     _echo_ceiling(per_repo_resolution)
     if per_repo_warning:
         click.echo(f"  {per_repo_warning}")
+    # #3423: only the repos that actually override the fleet default are
+    # listed. Printing all fourteen would bury the two that differ, which is
+    # the opposite of what this report is for.
+    for name in sorted(repo_overrides):
+        _echo_ceiling(repo_resolutions[name], indent="    ")
     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))
+    click.echo(
+        _effective_usage_line(
+            cfg, global_resolution, per_repo_resolution, repo_overrides
+        )
+    )
 
 
-def _echo_ceiling(resolution: "CeilingResolution") -> None:
-    line = f"  {resolution.name:<24} {resolution.value}  <- {resolution.source}"
+def _echo_ceiling(resolution: "CeilingResolution", *, indent: str = "  ") -> None:
+    width = 26 - len(indent)
+    line = f"{indent}{resolution.name:<{width}} {resolution.value}  <- {resolution.source}"
     if resolution.losing:
         losers = ", ".join(f"{name}: {value}" for name, value in resolution.losing)
         line += f"  (losing: {losers})"
@@ -259,6 +289,7 @@ def _effective_usage_line(
     cfg: "Config",
     global_resolution: "CeilingResolution",
     per_repo_resolution: "CeilingResolution",
+    repo_overrides: "Mapping[str, int] | None" = None,
 ) -> str:
     """Current in-flight usage against the two resolved ceilings above
     (#3408 acceptance: "a queue at its global ceiling reports N/N rather
@@ -291,8 +322,11 @@ def _effective_usage_line(
         return f"in flight  unavailable ({exc})"
 
     line = f"in flight  {occupied}/{global_resolution.value} global"
+    # #3423: count each repo against ITS OWN ceiling — against the fleet
+    # default, an overridden repo reports "2/1" and reads as a bug.
+    overrides = repo_overrides or {}
     per_repo_bits = " · ".join(
-        f"{repo} {count}/{per_repo_resolution.value}"
+        f"{repo} {count}/{overrides.get(repo, per_repo_resolution.value)}"
         for repo, count in sorted(repo_occupied.items())
     )
     if per_repo_bits:

{code_coordinator-0.5.507 → code_coordinator-0.5.509}/coord/config.py

@@ -2536,6 +2536,7 @@ _KNOWN_REPO_KEYS = frozenset(
         "uat_live_preview",
         "uat_checks",
         "requires",
+        "max_parallel",
     }
 )
 
@@ -2831,6 +2832,28 @@ def _parse_repos(raw: Any) -> tuple[list[Repo], list[str]]:
         if not isinstance(requires, list) or not all(isinstance(r, str) for r in requires):
             raise ConfigError(f"repos[{i}].requires must be a list of strings")
 
+        # #3423: max_parallel — THIS repo's own drive-queue concurrency
+        # ceiling, overriding the fleet-wide `pipeline.max_parallel_per_repo`.
+        # Absent (None) means "no opinion", i.e. exactly the pre-#3423
+        # behaviour for that repo. See `Repo.max_parallel`'s docstring for
+        # why this one override outranks an explicit CLI/systemd flag, and
+        # `coord.drive_queue.resolve_repo_max_parallel` for the resolution.
+        # `bool` is rejected explicitly: YAML's `max_parallel: true` parses
+        # as a bool, which `isinstance(x, int)` would otherwise wave through
+        # as 1 — a silently-wrong ceiling rather than a config error.
+        repo_max_parallel = entry.get("max_parallel")
+        if repo_max_parallel is not None:
+            if isinstance(repo_max_parallel, bool) or not isinstance(repo_max_parallel, int):
+                raise ConfigError(
+                    f"repos[{i}].max_parallel must be an integer "
+                    "(omit the key entirely to use pipeline.max_parallel_per_repo)"
+                )
+            if repo_max_parallel < 0:
+                raise ConfigError(
+                    f"repos[{i}].max_parallel must be 0 (no per-repo ceiling "
+                    "for this repo) or more"
+                )
+
         repos.append(
             Repo(
                 name=name,
@@ -2853,6 +2876,7 @@ def _parse_repos(raw: Any) -> tuple[list[Repo], list[str]]:
                 uat_live_preview=uat_live_preview_raw,
                 uat_checks=uat_checks,
                 requires=list(requires),
+                max_parallel=repo_max_parallel,
             )
         )
     return repos, warnings