code-coordinator 0.5.72__tar.gz → 0.5.74__tar.gz

{code_coordinator-0.5.72 → code_coordinator-0.5.74}/CLAUDE.md

@@ -84,6 +84,8 @@ coord retry|stop|resume <id>                    # Recovery; `coord done` ends th
 ```
 Setup / diagnostics (discoverable via `--help`): `coord init`, `coord config`, `coord agent`, `coord serve`, `coord web`, `coord diagnose`, `coord sessions [--remote]`, `coord split`, `coord notifier` ([`docs/NOTIFIER.md`](docs/NOTIFIER.md)).
 
+**Onboarding a repo is five layers, and every one fails silently (#2220).** `coord repo add <name> --github <owner/repo> --machines a,b,c` does the safely-automatable parts (reads the *real* default branch from GitHub, writes the entry into the coord-settings checkout, adds it to each machine, creates the `coord`/tier labels) and then prints the residue it deliberately did **not** do. `coord repo doctor <name>` is the part that matters: it probes all five layers from **live state, not config** — each agent's `/health` repo list, the clone on each machine, the labels that exist, whether any workflow triggers on `pull_request`, `CLAUDE.md`, graph freshness — and exits non-zero on any CRIT. `coord doctor` folds in the live-state layer for every repo, so a half-onboarded one shows up in the fleet report without anyone remembering to ask. See [`docs/AGENT_OPERATIONS.md`](docs/AGENT_OPERATIONS.md).
+
 ## Development
 
 Always work in a virtualenv. Agent workers are spawned with the agent's own

{code_coordinator-0.5.72 → code_coordinator-0.5.74}/PKG-INFO

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

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

@@ -111,6 +111,8 @@ coord/release_cordon.py
 coord/release_propagate.py
 coord/release_verify.py
 coord/release_window.py
+coord/repo_edit.py
+coord/repo_onboard.py
 coord/reports.py
 coord/revalidate.py
 coord/review.py
@@ -153,6 +155,7 @@ coord/commands/plan_followup.py
 coord/commands/plans.py
 coord/commands/portal.py
 coord/commands/release.py
+coord/commands/repo.py
 coord/commands/report.py
 coord/commands/review.py
 coord/commands/scorecard.py
@@ -459,6 +462,7 @@ tests/test_cli_assign.py
 tests/test_cli_assign_interactive_oracle_gate.py
 tests/test_cli_assign_interactive_remote.py
 tests/test_cli_assign_provider.py
+tests/test_cli_assign_repo_drift_2219.py
 tests/test_cli_audit.py
 tests/test_cli_chat_continue.py
 tests/test_cli_diagnose_config_provenance.py
@@ -496,6 +500,7 @@ tests/test_cli_refine_board.py
 tests/test_cli_release_preflight.py
 tests/test_cli_release_propagate.py
 tests/test_cli_release_window.py
+tests/test_cli_repo_2220.py
 tests/test_cli_scorecard.py
 tests/test_cli_set_review_findings.py
 tests/test_cli_status_advisory_terminal.py
@@ -665,6 +670,8 @@ tests/test_release_verify.py
 tests/test_release_window.py
 tests/test_remote_auto_prune.py
 tests/test_remote_interactive_reaper.py
+tests/test_repo_edit_2220.py
+tests/test_repo_onboard_2220.py
 tests/test_report_result_push.py
 tests/test_reports.py
 tests/test_retry.py

{code_coordinator-0.5.72 → code_coordinator-0.5.74}/code_coordinator.egg-info/scm_file_list.json

@@ -64,6 +64,7 @@
     "coord/commands/plans.py",
     "coord/commands/portal.py",
     "coord/commands/release.py",
+    "coord/commands/repo.py",
     "coord/commands/report.py",
     "coord/commands/review.py",
     "coord/commands/scorecard.py",
@@ -289,6 +290,8 @@
     "coord/release_propagate.py",
     "coord/release_verify.py",
     "coord/release_window.py",
+    "coord/repo_edit.py",
+    "coord/repo_onboard.py",
     "coord/reports.py",
     "coord/revalidate.py",
     "coord/review.py",
@@ -489,6 +492,7 @@
     "tests/test_cli_assign_interactive_oracle_gate.py",
     "tests/test_cli_assign_interactive_remote.py",
     "tests/test_cli_assign_provider.py",
+    "tests/test_cli_assign_repo_drift_2219.py",
     "tests/test_cli_audit.py",
     "tests/test_cli_chat_continue.py",
     "tests/test_cli_diagnose_config_provenance.py",
@@ -526,6 +530,7 @@
     "tests/test_cli_release_preflight.py",
     "tests/test_cli_release_propagate.py",
     "tests/test_cli_release_window.py",
+    "tests/test_cli_repo_2220.py",
     "tests/test_cli_scorecard.py",
     "tests/test_cli_set_review_findings.py",
     "tests/test_cli_status_advisory_terminal.py",
@@ -695,6 +700,8 @@
     "tests/test_release_window.py",
     "tests/test_remote_auto_prune.py",
     "tests/test_remote_interactive_reaper.py",
+    "tests/test_repo_edit_2220.py",
+    "tests/test_repo_onboard_2220.py",
     "tests/test_report_result_push.py",
     "tests/test_reports.py",
     "tests/test_retry.py",

{code_coordinator-0.5.72 → code_coordinator-0.5.74}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.72",
+  "tag": "0.5.74",
   "distance": 0,
-  "node": "gf89a7326b4afe98af0d76d9cbafabea51928013f",
+  "node": "g6932f7816982a66f6e4945073a12324dd56fc91b",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-14"

{code_coordinator-0.5.72 → code_coordinator-0.5.74}/coord/cli.py

@@ -141,6 +141,9 @@ from coord.commands.lifecycle import done, housekeeping, notify, resume, serve,
 from coord.commands.milestone import milestone_group
 from coord.commands.plans import plans_cmd
 from coord.commands.release import release_group, release_preflight
+# #2220: `coord repo add` / `coord repo doctor` — onboarding a repo, and
+# verifying it actually happened across all five layers.
+from coord.commands.repo import repo_group
 from coord.commands.plan_followup import (
     _dispatch_followup,  # noqa: F401 — re-exported for tests
     approve_plan,
@@ -449,6 +452,8 @@ main.add_command(release_preflight)
 # the flat command above), grouped so the pre-tag and post-release halves of
 # the release story are discoverable together.
 main.add_command(release_group)
+# #2220: repo onboarding + its verifier.
+main.add_command(repo_group)
 main.add_command(tui_group)
 
 

{code_coordinator-0.5.72 → code_coordinator-0.5.74}/coord/commands/dispatch.py

@@ -9,6 +9,7 @@ import dataclasses
 import socket
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import click
 import httpx
@@ -31,6 +32,9 @@ from coord.commands.dispatch_workers import (
     _dispatch_troubleshoot,
 )
 
+if TYPE_CHECKING:
+    from coord.models import Machine
+
 
 def _stdin_is_tty() -> bool:
     """Seam over ``sys.stdin.isatty()`` — see ``_require_interactive_tty``
@@ -89,6 +93,88 @@ def _require_interactive_tty(dry_run: bool) -> None:
     )
 
 
+def _repo_capability_refusal(
+    machine_obj: Machine, repo: str, *, timeout: float = 3.0
+) -> str | None:
+    """Cross-check *repo* against the target agent's LIVE ``/health`` repo
+    list, returning a refusal message when the two disagree — or ``None``
+    when they agree, the agent is unreachable, or the agent is config-free
+    (#2219).
+
+    ``assign()``'s ``machine_obj.can_work_on(repo)`` check (just above this
+    call site) only ever reads ``coordinator.yml`` — which the operator can
+    edit any time — never the agent process actually running on that
+    machine. A repo added to config after the agent started stays invisible
+    to it until a full ``systemctl --user restart coord-agent`` (there is no
+    partial re-read today). Every pre-flight surface an operator would
+    check before spending a dispatch reads config too: ``coord config``,
+    ``coord status``, and — worst of all — ``coord assign ... --dry-run``,
+    which is the documented way to sanity-check a dispatch before paying
+    for it. All three said this was fine while the live agent rejected it
+    outright, and a drive queue burned both retry attempts discovering that
+    by trial before landing terminally ``blocked`` (#2219). This is the
+    same ``/health`` read ``coord status``/``coord doctor`` already make
+    (``coord.network.check_machine``) — reused, not duplicated.
+
+    ``/health``'s ``repos`` field is NOT what ``AgentServer.assign()``
+    itself gates on, though — it's ``AgentServer._servable_repos()``'s
+    FILTERED list (``coord/agent.py``, #1527), which drops any repo with no
+    ``repo_paths`` entry or whose configured path is missing on disk.
+    ``assign()``'s own gate (``coord/agent.py``: ``if self.repos and
+    spec.repo_name not in self.repos``) checks the UNFILTERED
+    ``self.repos``. The two disagree exactly when a repo is configured on
+    that machine but degraded (``/health``'s ``degraded`` dict, #1527): in
+    that case ``assign()`` would NOT reject with "does not handle repo" —
+    it proceeds and fails later with the distinct "repo path does not
+    exist" — so this helper checks ``degraded`` FIRST and reports that
+    reason (with no restart advice, since restarting coord-agent cannot
+    repair a missing/misconfigured ``repo_paths`` entry) before ever
+    falling back to the "hasn't re-read config since *repo* was added"
+    story, which is only accurate when *repo* is absent from ``/health``
+    entirely — not merely degraded.
+
+    Deliberately narrow otherwise: only refuses when the agent is
+    reachable, ANSWERED with a real ``/health`` body, is not running
+    config-free (#1801 — a config-free agent's repos come from the dispatch
+    payload, not its own config, so an empty/mismatched list there is not a
+    capability gap), and either lists *repo* as degraded or published a
+    NON-empty repo list that plainly excludes it. Every other case
+    (offline, timeout, old agent with no ``repos`` key, empty list) falls
+    through to ``None`` — today's behavior, where the POST itself is left
+    to surface a real problem — so this never turns a transient network
+    hiccup into a new dispatch failure mode.
+    """
+    from coord.network import check_machine
+
+    status = check_machine(machine_obj, timeout=timeout)
+    if not status.is_online or status.health is None:
+        return None
+    health = status.health
+    if health.get("config_free"):
+        return None
+    degraded = health.get("degraded") or {}
+    if repo in degraded:
+        return (
+            f"{machine_obj.name!r} lists {repo!r} in coordinator.yml, and "
+            f"the live agent agrees it's configured, but the repo is "
+            f"DEGRADED there, not just unrefreshed: {degraded[repo]} "
+            f"(#1527). This is not the #2219 stale-config case — "
+            f"restarting coord-agent will not fix a missing or "
+            f"misconfigured repo_paths entry. Repair repo_paths[{repo!r}] "
+            f"on {machine_obj.name!r} instead, then retry."
+        )
+    live_repos = health.get("repos")
+    if not live_repos or repo in live_repos:
+        return None
+    return (
+        f"{machine_obj.name!r} rejected the assignment: this agent does "
+        f"not handle repo {repo!r} (supported: {live_repos}) — "
+        f"coordinator.yml lists it, but the live agent process hasn't "
+        f"re-read its config since {repo!r} was added (#2219). Restart "
+        f"coord-agent on {machine_obj.name!r} to pick it up, then retry."
+    )
+
+
 @click.command(help="Brain proposes assignments for idle machines.")
 @_CONFIG_OPTION
 @click.option("--dry-run", is_flag=True, help="Plan without saving proposals.")
@@ -951,6 +1037,18 @@ def assign(
         )
         sys.exit(2)
 
+    # #2219: config says this machine handles `repo` — but the LIVE agent
+    # process may not (yet) agree, if `repo` was added to coordinator.yml
+    # after that agent started. Refuse with the agent's real reason here,
+    # before any claim/worktree/network work — including under --dry-run,
+    # which is exactly the surface that used to green-light this. See
+    # _repo_capability_refusal's docstring for the full rationale and what
+    # it deliberately does NOT block on (offline/unreachable/config-free).
+    capability_refusal = _repo_capability_refusal(machine_obj, repo)
+    if capability_refusal is not None:
+        click.echo(f"error: {capability_refusal}", err=True)
+        sys.exit(2)
+
     # Refuse direct assignment to a paused machine — `coord pause` exists
     # so the user can explicitly steer work away.  If they meant to dispatch
     # anyway they should `coord unpause` first.  #1862: also refuses inside

code_coordinator-0.5.74/coord/commands/repo.py

@@ -0,0 +1,368 @@
+"""``coord repo add`` / ``coord repo doctor`` — onboarding a repo, and
+checking that it actually happened (#2220).
+
+Onboarding a repo is ~14 steps across five layers (config, three machines,
+GitHub, the repo's own contents, the graph) with no command, no checklist and
+no verifier — reconstructed from memory each time, and **every layer fails
+silently**. ``stick-demo`` sat two-thirds onboarded until ``stick-demo#1`` died
+of it, having burned both drive attempts, while ``coord config``, ``coord
+status`` and ``coord assign --dry-run`` all reported the dispatch as fine.
+
+Of the two commands here the **second is the one that matters**. A runbook is
+the weakest available answer and this codebase already has the proof:
+``docs/GRAPHIFY_SETUP.md`` is exactly that shape, and graphify has still fallen
+by the wayside more than once because nothing checks it. What holds is a
+checkable gate — ``coord diagnose --graph``, ``coord doctor``, ``coord release
+verify`` all work because they answer *is it true right now*, not *did you
+remember*.
+
+``coord repo add`` therefore does only the mechanical, safely-automatable parts
+and **prints the residue it deliberately did not do**, rather than pretending
+completeness. The parts it skips (clone, agent restart, CLAUDE.md, CI workflow)
+are the ones a wrong guess makes worse, and they are exactly what ``coord repo
+doctor`` then verifies.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from coord.commands._common import _CONFIG_OPTION, _load_config
+
+# Reuse the fleet's own definition of where the tracked config lives (#1779) —
+# `~/src/coord-settings/coord/coordinator.yml`, NOT the `~/.coord/` symlink
+# (#1832): edits must land in the checkout so they can be committed, reviewed
+# and pulled onto the daemon host.
+from coord.fleet_config_health import TRACKED_CONFIG_REL, default_settings_dir
+
+
+@click.group("repo", help="Add a repo to the fleet, and verify it is actually onboarded.")
+def repo_group() -> None:
+    """Repo onboarding (#2220)."""
+
+
+def _resolve_write_target(explicit: Path | None) -> Path:
+    """Where ``coord repo add`` writes.
+
+    Defaults to the coord-settings checkout's tracked file rather than
+    whatever ``resolve_config_path()`` returns, because the live
+    ``~/.coord/coordinator.yml`` is a *symlink* into that checkout: writing
+    through the symlink produces an untracked, uncommitted change to the
+    fleet's governing config with nothing to review and nothing to pull
+    (#1779/#1832). Refuses rather than falling back when the checkout is
+    absent — a machine with no coord-settings checkout is deliberately not
+    allowed to edit the fleet's config.
+    """
+    if explicit is not None:
+        return explicit
+    tracked = default_settings_dir() / TRACKED_CONFIG_REL
+    if not tracked.exists():
+        raise click.ClickException(
+            f"no coord-settings checkout at {default_settings_dir()} (expected "
+            f"{tracked}). `coord repo add` writes the TRACKED config so the "
+            "change can be committed, reviewed and pulled — it will not write "
+            "through the ~/.coord symlink (#1832). Clone coord-settings, set "
+            "$COORD_SETTINGS_DIR, or pass --config explicitly."
+        )
+    return tracked
+
+
+@repo_group.command(
+    "add",
+    help=(
+        "Write a new repo's coordinator.yml entry into the coord-settings "
+        "checkout, add it to the named machines, create the `coord` and tier "
+        "labels — then print the residue it deliberately did NOT do."
+    ),
+)
+@click.argument("name")
+@click.option("--github", "github_slug", required=True, help="owner/repo on GitHub.")
+@click.option(
+    "--machines", "machines_csv", default=None,
+    help="Comma-separated machine names that should serve this repo.",
+)
+@click.option(
+    "--repo-path", "repo_path_tmpl", default=None,
+    help=(
+        "Path to the clone on each machine. Default: ~/src/<name> — the fleet "
+        "convention, and the worker WORKTREE BASE, not a convenience checkout."
+    ),
+)
+@click.option(
+    "--default-branch", "default_branch_override", default=None,
+    help=(
+        "Override the default branch instead of reading the real one from "
+        "GitHub. Use only when GitHub is unreachable — a default_branch that "
+        "disagrees with the repo's real default silently routes worker PRs to "
+        "the wrong base."
+    ),
+)
+@click.option("--build-command", default=None, help="repos[].build_command.")
+@click.option("--test-command", default=None, help="repos[].test_command.")
+@click.option(
+    "--labels/--no-labels", "do_labels", default=True, show_default=True,
+    help="Create the `coord` and tier:small/tier:large labels on GitHub.",
+)
+@click.option(
+    "--dry-run", is_flag=True, default=False,
+    help="Print the edited config and the residue without writing anything.",
+)
+@click.option(
+    "--config", "config_path", type=click.Path(path_type=Path), default=None,
+    help="coordinator.yml to edit. Default: the coord-settings tracked file.",
+)
+def repo_add(  # noqa: PLR0913 — one option per thing the command can set
+    name: str,
+    github_slug: str,
+    machines_csv: str | None,
+    repo_path_tmpl: str | None,
+    default_branch_override: str | None,
+    build_command: str | None,
+    test_command: str | None,
+    do_labels: bool,  # noqa: FBT001
+    dry_run: bool,  # noqa: FBT001
+    config_path: Path | None,
+) -> None:
+    from coord.config import load as load_config  # noqa: PLC0415
+    from coord.repo_edit import (  # noqa: PLC0415
+        RepoEditError,
+        add_repo_to_machine,
+        insert_repo_entry,
+        render_repo_entry,
+    )
+    from coord.repo_onboard import COORD_LABEL, TIER_LABELS  # noqa: PLC0415
+
+    target = _resolve_write_target(config_path)
+    original = target.read_text(encoding="utf-8")
+
+    try:
+        cfg = load_config(target)
+    except Exception as exc:  # noqa: BLE001
+        raise click.ClickException(f"{target} does not currently load: {exc}") from exc
+
+    if cfg.repo(name) is not None:
+        raise click.ClickException(
+            f"repo {name!r} already has a repos[] entry in {target} — use "
+            f"`coord repo doctor {name}` to find what is actually missing."
+        )
+
+    known = {m.name for m in cfg.machines}
+    machines = [m.strip() for m in (machines_csv or "").split(",") if m.strip()]
+    unknown = [m for m in machines if m not in known]
+    if unknown:
+        raise click.ClickException(
+            f"unknown machine(s) {unknown} — coordinator.yml has {sorted(known)}"
+        )
+
+    # ── The real default branch, read from GitHub rather than trusted ────
+    if default_branch_override:
+        default_branch = default_branch_override
+        branch_source = "--default-branch (NOT verified against GitHub)"
+    else:
+        from coord import github_ops  # noqa: PLC0415
+
+        try:
+            default_branch = github_ops.get_repo_default_branch(github_slug)
+        except Exception as exc:  # noqa: BLE001
+            raise click.ClickException(
+                f"could not read {github_slug}'s default branch from GitHub: "
+                f"{exc}. Fix `gh` auth, or pass --default-branch explicitly "
+                "(and know that an unverified value silently routes worker PRs "
+                "to the wrong base)."
+            ) from exc
+        branch_source = f"read from GitHub ({github_slug})"
+
+    entry = render_repo_entry(
+        name, github_slug, default_branch,
+        build_command=build_command, test_command=test_command,
+    )
+    try:
+        updated = insert_repo_entry(original, entry)
+        path_tmpl = repo_path_tmpl or f"~/src/{name}"
+        for machine in machines:
+            updated = add_repo_to_machine(updated, machine, name, path_tmpl)
+    except RepoEditError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    # ── Seatbelt: the edit must produce a config that LOADS and contains
+    # what we think it contains. A line-level edit that "worked" but left a
+    # repo unroutable is worse than no command at all (#2220's whole thesis).
+    import tempfile  # noqa: PLC0415
+
+    with tempfile.NamedTemporaryFile(
+        "w", suffix=".yml", delete=False, encoding="utf-8"
+    ) as fh:
+        fh.write(updated)
+        probe_path = Path(fh.name)
+    try:
+        new_cfg = load_config(probe_path)
+    except Exception as exc:  # noqa: BLE001
+        raise click.ClickException(
+            f"refusing to write: the edited config does not parse ({exc}). "
+            f"{target} is unchanged."
+        ) from exc
+    finally:
+        probe_path.unlink(missing_ok=True)
+
+    if new_cfg.repo(name) is None:
+        raise click.ClickException(
+            f"refusing to write: the edit parsed but repo {name!r} is not in "
+            f"the result. {target} is unchanged."
+        )
+    landed = [m.name for m in new_cfg.machines if name in (m.repos or [])]
+    missing = [m for m in machines if m not in landed]
+    if missing:
+        raise click.ClickException(
+            f"refusing to write: the edit parsed but machine(s) {missing} do "
+            f"not list {name!r}. {target} is unchanged."
+        )
+
+    if dry_run:
+        click.echo(f"--dry-run: would write {target}")
+        click.echo(updated)
+    else:
+        target.write_text(updated, encoding="utf-8")
+        click.echo(f"✓ wrote repos[{name}] to {target}")
+        click.echo(f"  default_branch: {default_branch}  ({branch_source})")
+        if landed:
+            click.echo(f"  machines: {', '.join(landed)}")
+
+    # ── Labels ───────────────────────────────────────────────────────────
+    created: list[str] = []
+    label_failures: list[str] = []
+    if do_labels and not dry_run:
+        from coord import github_ops  # noqa: PLC0415
+
+        for label, colour, desc in (
+            (COORD_LABEL, "0e8a16", "Managed by the coord Pipeline"),
+            (TIER_LABELS[0], "c2e0c6", "Route to the small/cheap model"),
+            (TIER_LABELS[1], "5319e7", "Route to the large model"),
+        ):
+            try:
+                github_ops.create_label(
+                    github_slug, label, color=colour, description=desc
+                )
+                created.append(label)
+            except Exception as exc:  # noqa: BLE001
+                label_failures.append(f"{label}: {exc}")
+        if created:
+            click.echo(f"✓ labels ensured on {github_slug}: {', '.join(created)}")
+        for failure in label_failures:
+            click.echo(f"⚠ label creation failed — {failure}", err=True)
+
+    # ── Residue: what this command deliberately did NOT do ───────────────
+    click.echo("")
+    click.echo("NOT DONE — these need a human, and `coord repo doctor` checks each:")
+    tracked = default_settings_dir() / TRACKED_CONFIG_REL
+    if target == tracked:
+        click.echo(
+            f"  1. commit + push in {default_settings_dir()}, then `git pull` on "
+            "the daemon host — the fleet runs the COMMITTED config"
+        )
+    else:
+        click.echo(
+            f"  1. commit + push {target} wherever it is tracked, then `git "
+            "pull` on the daemon host — the fleet runs the COMMITTED config"
+        )
+    for machine in machines or ["<each machine>"]:
+        click.echo(
+            f"  2. clone the repo to {repo_path_tmpl or f'~/src/{name}'} on "
+            f"{machine} — this is the worker WORKTREE BASE"
+        )
+    click.echo(
+        "  3. RESTART coord-agent on each of those machines. The repo list is "
+        "frozen at process start (#2219), so a running agent will refuse every "
+        "dispatch for this repo while config says it is supported. This cannot "
+        "run while headless workers are live."
+    )
+    click.echo(
+        "  4. add a CLAUDE.md to the repo — the Test agent auto-loads it and "
+        "the adversarial review prompt is assembled from it; without one, "
+        "reviews enforce nothing."
+    )
+    click.echo(
+        "  5. make sure at least one CI workflow triggers on `pull_request`. "
+        "If none does, expects_checks() reads 'CI exists' while zero checks "
+        "arrive and `checks_absent` blocks EVERY merge in this repo, forever."
+    )
+    click.echo(
+        "  6. set `test_command`/`ci_command`, `smoke_tests.capability_rules` "
+        "for this repo's paths, and (if it joins the oracle loop) "
+        "`acceptance.drivers`."
+    )
+    click.echo(
+        "  7. graphify build + `graphify hook install` + `core.hooksPath`, in "
+        "that order, per machine (docs/GRAPHIFY_SETUP.md)."
+    )
+    click.echo("")
+    click.echo(f"Then: coord repo doctor {name}")
+
+
+@repo_group.command(
+    "doctor",
+    help=(
+        "Probe all five onboarding layers for a repo and report per-layer "
+        "status. Reads LIVE state — each agent's /health repo list, the labels "
+        "that exist on GitHub, whether any workflow triggers on pull_request — "
+        "not config. Exits non-zero on any CRIT so it can gate."
+    ),
+)
+@click.argument("name")
+@_CONFIG_OPTION
+@click.option(
+    "--timeout", default=3.0, show_default=True, type=float,
+    help="Per-machine /health timeout (seconds).",
+)
+@click.option(
+    "--github/--no-github", "probe_github", default=True, show_default=True,
+    help="Probe GitHub (labels, workflows, CLAUDE.md). Off makes this offline.",
+)
+@click.option(
+    "--verbose", "-v", is_flag=True, default=False,
+    help="Show passing checks too, not just the residue.",
+)
+def repo_doctor(
+    name: str,
+    config_path: Path,
+    timeout: float,
+    probe_github: bool,  # noqa: FBT001
+    verbose: bool,  # noqa: FBT001
+) -> None:
+    from coord import repo_onboard  # noqa: PLC0415
+    from coord.network import check_all  # noqa: PLC0415
+
+    cfg = _load_config(config_path)
+
+    repo = cfg.repo(name)
+    if repo is None:
+        known = [r.name for r in cfg.repos]
+        click.echo(
+            f"error: repo {name!r} is not in coordinator.yml (have: {known})",
+            err=True,
+        )
+        # Still render the report — "config.repo_missing" IS the finding, and
+        # a caller gating on this deserves the same structured output.
+        facts = repo_onboard.RepoFacts(name=name, configured=False)
+        for line in repo_onboard.format_report(
+            repo_onboard.evaluate(facts), verbose=verbose
+        ):
+            click.echo(line)
+        sys.exit(1)
+
+    machines = [m for m in cfg.machines if name in (m.repos or [])]
+    statuses = check_all(machines, timeout=timeout) if machines else []
+
+    facts = repo_onboard.gather_facts(
+        cfg, name,
+        statuses=statuses,
+        probe_github=probe_github,
+        local_clone=repo_onboard.local_clone_path(cfg, name),
+    )
+    report = repo_onboard.evaluate(facts)
+    for line in repo_onboard.format_report(report, verbose=verbose):
+        click.echo(line)
+    if not report.ok:
+        sys.exit(1)