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

{code_coordinator-0.5.73 → 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.73 → code_coordinator-0.5.74}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.73
+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.73 → 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.73
+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.73 → 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
@@ -497,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
@@ -666,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.73 → 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",
@@ -527,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",
@@ -696,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.73 → code_coordinator-0.5.74}/code_coordinator.egg-info/scm_version.json

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

{code_coordinator-0.5.73 → 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.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)

{code_coordinator-0.5.73 → code_coordinator-0.5.74}/coord/commands/status.py

@@ -954,6 +954,42 @@ def _dispatch_blocker_lines_for_config_free(machine, cfg) -> list[tuple[bool, st
     return out
 
 
+def _repo_onboarding_lines(cfg, statuses) -> list[tuple[bool, str]]:
+    """Render every configured repo's onboarding residue as ``coord doctor``
+    lines (:mod:`coord.repo_onboard`, #2220).
+
+    This is the wiring #2220 asks for: a half-onboarded repo shows up in the
+    fleet report *without anyone remembering to ask*. ``stick-demo`` sat
+    two-thirds onboarded for days and the only thing that ever noticed was a
+    queue entry dying of it.
+
+    Runs with ``probe_github=False`` and no graph probe, so it costs **zero**
+    extra round trips — it re-reads the ``/health`` bodies this command has
+    already fetched. That is enough for the finding that actually bit: the
+    #2219 agent/config repo skew is visible from ``/health`` alone. The GitHub
+    and repo-contents layers need ``coord repo doctor <name>``, which the
+    footer below points at.
+
+    Mirrors :func:`_unit_drift_lines`/:func:`_release_lag_lines`: same
+    computation as the dedicated command (#2096's "two surfaces, one
+    function" rule), projected into doctor's output. Best-effort — a repo whose
+    facts can't be gathered is skipped rather than breaking the fleet report.
+    """
+    from coord import repo_onboard  # noqa: PLC0415
+
+    out: list[tuple[bool, str]] = []
+    for repo in getattr(cfg, "repos", None) or []:
+        try:
+            facts = repo_onboard.gather_facts(
+                cfg, repo.name, statuses=statuses, probe_github=False
+            )
+            report = repo_onboard.evaluate(facts)
+        except Exception:  # noqa: BLE001 — never break the fleet report
+            continue
+        out.extend(repo_onboard.doctor_summary_lines(report))
+    return out
+
+
 def _release_lag_lines(report) -> list[tuple[bool, str]]:
     """Render a :class:`coord.release_verify.VerifyReport`'s findings as
     ``coord doctor`` lines (#2082).
@@ -1135,6 +1171,26 @@ def doctor(
             for reason in reasons:
                 click.echo(f"  ✗ capability {cap!r} claimed but unmet — {reason}")
 
+    # #2220: is any repo only half-onboarded? Costs nothing extra — reuses the
+    # `/health` bodies fetched above. Skipped under `--machine`, where the
+    # per-machine slice would report every OTHER machine's repos as
+    # "unreachable" purely because this run never probed them.
+    if not machine_filter:
+        onboarding_lines = _repo_onboarding_lines(cfg, statuses)
+        if onboarding_lines:
+            click.echo("")
+            click.echo("repo onboarding (coord repo doctor):")
+            for is_problem, line in onboarding_lines:
+                click.echo(line)
+                if is_problem:
+                    any_problem = True
+            click.echo(
+                "  → this is the LIVE-state layer only. GitHub labels, the "
+                "pull_request trigger, CLAUDE.md, the Test-stage command and "
+                "graph freshness are NOT checked here: run "
+                "`coord repo doctor <name>`"
+            )
+
     # #2082: is the fleet actually running the released version? On
     # 2026-08-10 it was eleven releases behind (v0.5.15 vs PyPI's v0.5.26)
     # and nothing routine said so — `coord release verify` already computed

{code_coordinator-0.5.73 → code_coordinator-0.5.74}/coord/github_ops.py

@@ -1166,6 +1166,88 @@ def check_branch_exists(repo: str, branch: str) -> bool:
         return False
 
 
+def get_repo_default_branch(repo: str) -> str:
+    """The repo's REAL default branch, from GitHub (#2220).
+
+    ``coord repo add`` reads this rather than trusting a ``--default-branch``
+    flag, and ``coord repo doctor`` compares it against the configured value:
+    a ``default_branch`` that disagrees with the repo's actual default routes
+    every worker PR to the wrong base, and nothing else in the fleet notices.
+
+    Raises (``RuntimeError``/:class:`GhError`) on any read failure rather than
+    guessing ``"main"`` — a caller that cannot tell "the default is main" from
+    "I could not ask" must not treat the second as the first.
+    """
+    data = _gh_json("api", f"repos/{repo}", default=None)
+    if not isinstance(data, dict) or not data.get("default_branch"):
+        raise RuntimeError(f"gh api repos/{repo}: no default_branch in response")
+    return str(data["default_branch"])
+
+
+def list_repo_labels(repo: str) -> list[str]:
+    """Every label name defined in *repo* (#2220).
+
+    Backs the ``coord`` / ``tier:*`` label checks in ``coord repo doctor``:
+    without the ``coord`` label an issue is live on GitHub but invisible to
+    the Pipeline, which is indistinguishable from "nobody has filed anything
+    yet". Raises on read failure — see :func:`get_repo_default_branch`.
+    """
+    data = _gh_json(
+        "api", "--paginate", "--slurp", f"repos/{repo}/labels", default=None
+    )
+    # `--paginate --slurp` yields a list of per-page arrays; a single
+    # unpaginated read yields a flat array. Accept both rather than depending
+    # on how many labels the repo happens to have.
+    if not isinstance(data, list):
+        raise RuntimeError(f"gh api repos/{repo}/labels: malformed response")
+    out: list[str] = []
+    for entry in data:
+        if isinstance(entry, list):
+            out.extend(str(e.get("name")) for e in entry if isinstance(e, dict) and e.get("name"))
+        elif isinstance(entry, dict) and entry.get("name"):
+            out.append(str(entry["name"]))
+    return out
+
+
+def list_repo_workflows(repo: str) -> list[dict]:
+    """The GitHub Actions workflow definitions GitHub knows about for *repo*.
+
+    Sibling of :func:`get_repo_workflow_count` (which only needs the count for
+    ``expects_checks``); this returns the entries themselves so ``coord repo
+    doctor`` can go on and read each one's ``on:`` triggers. Each dict carries
+    at least ``name`` and ``path``.
+
+    Raises on read failure rather than returning ``[]`` — same reasoning as
+    :func:`get_repo_workflow_count`: "no workflows" and "couldn't check" have
+    opposite consequences for the merge gate.
+    """
+    data = _gh_json("api", f"repos/{repo}/actions/workflows", default=None)
+    if not isinstance(data, dict) or not isinstance(data.get("workflows"), list):
+        raise RuntimeError(
+            f"gh api repos/{repo}/actions/workflows: malformed response"
+        )
+    return [w for w in data["workflows"] if isinstance(w, dict)]
+
+
+def repo_file_exists(repo: str, path: str, branch: str) -> bool:
+    """True when *path* exists on *branch* of *repo* (#2220).
+
+    Thin, explicitly-branch-taking wrapper over the Contents API —
+    :func:`get_repo_file` defaults to ``develop``, which is wrong for the
+    majority of repos this is asked about. Returns ``False`` only for a real
+    "not found"; every other failure propagates, so a caller never reads an
+    auth error as a missing ``CLAUDE.md``.
+    """
+    try:
+        _gh("api", f"repos/{repo}/contents/{path}?ref={branch}")
+        return True
+    except RuntimeError as exc:
+        msg = str(exc).lower()
+        if "not found" in msg or "404" in msg:
+            return False
+        raise
+
+
 def list_remote_branch_names(repo: str) -> set[str]:
     """Return the set of branch names that currently exist on `repo` (owner/name).