code-coordinator 0.5.207__tar.gz → 0.5.210__tar.gz

{code_coordinator-0.5.207 → code_coordinator-0.5.210}/.gitignore

@@ -18,3 +18,8 @@ tui/*.out
 # tui/cargo-config-local-quadraui.toml.example) — never commit a
 # machine-local co-development override.
 tui/.cargo/config.toml
+
+# scratch $HOME created inside disposable worktrees by the CI-mode
+# acceptance runner (scripts/coord-test-runner.sh) — never meant to
+# leave the throwaway worktree, let alone land in git history (#2527).
+.coord-ci-home/

{code_coordinator-0.5.207 → code_coordinator-0.5.210}/CLAUDE.md

@@ -10,6 +10,20 @@ CLI tool + per-machine agent server that coordinates Claude Code workers across
 > [`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: dispatch, don't do.** If you're the interactive coordinator session —
+> not a dispatched `type=work`/`review` leg — and the user asks for a change in any repo listed
+> in `coordinator.yml`, don't edit that repo's tree yourself: file a GitHub issue and `coord
+> drive-queue add` it. That gets the change tested, independently reviewed, merged, and
+> deployed; hand-editing it here skips all four. (Doc-only edits to *this* repo are the
+> documented exception for *who* does the work — see
+> [`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md) — **not** for *how* it lands: every commit
+> on `main`, doc-only ones included, is squash-merged from a branch's PR, never pushed to `main`
+> directly. Use `EnterWorktree`, branch, commit, push, open the PR, let it merge, then
+> `ExitWorktree`.) Caught 2026-08-21: this exact rule used to live inline here, got moved to
+> that linked doc by #2195, and was then skipped — an operator session hand-implemented a
+> natal-chart feature directly instead of dispatching it. If you're a worker or reviewer leg,
+> this paragraph 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*.

{code_coordinator-0.5.207 → code_coordinator-0.5.210}/PKG-INFO

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.207
+Version: 0.5.210
 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.207 → code_coordinator-0.5.210}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.207",
+  "tag": "0.5.210",
   "distance": 0,
-  "node": "gc33012740fef085a15f6c4a34f631d39225f18b3",
+  "node": "gd5dc3b7d2bb67fd517cd7ac495abb3076f2017e4",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-21"

{code_coordinator-0.5.207 → code_coordinator-0.5.210}/coord/confirm_test.py

@@ -82,7 +82,12 @@ saying so:
   that lesson is not re-learned here;
 * a timeout (:data:`~coord.revalidate.KIND_TIMEOUT`) — a hung or merely slow
   suite says nothing about the branch. Classifying a timeout as a refutation
-  would let a too-tight ceiling fail every branch in the fleet, so it does not.
+  would let a too-tight ceiling fail every branch in the fleet, so it does not;
+* an external signal killing the confirmation subprocess (:data:`KIND_SIGNAL`,
+  #2527) — a negative ``returncode`` from `subprocess.run` (e.g. ``-15`` for
+  SIGTERM), most often a `coord-agent`/`coord-serve` restart landing mid-run.
+  The command never ran to completion, exactly like a timeout, so it gets the
+  identical inconclusive treatment rather than being read as "ran and failed".
 
 That asymmetry is the safety property: the worst case of a broken confirmation
 environment is that the Test stage behaves exactly as it did before this module
@@ -181,6 +186,17 @@ DISABLE_ENV_VAR = "COORD_CONFIRM_TEST_VERDICT"
 _FALSEY = frozenset({"0", "false", "no", "off", ""})
 _TRUTHY = frozenset({"1", "true", "yes", "on"})
 
+#: #2527: a confirmation subprocess terminated by an external signal (a
+#: coord-agent/coord-serve restart, a manual ``kill``, anything that delivers
+#: a signal rather than letting the command run to completion) — not
+#: :data:`KIND_TIMEOUT` (this module's own deadline) but the same shape from
+#: the branch's point of view: the suite never got a chance to finish, so
+#: nothing was learned about it. `subprocess.run` surfaces this as a negative
+#: ``returncode`` (``-signal.SIGTERM`` == ``-15``) through its normal return
+#: path rather than raising, which is exactly what let it slip past the
+#: existing ``TimeoutExpired`` carve-out and get misread as "ran and failed".
+KIND_SIGNAL = "signal"
+
 #: The only kinds that may overturn a PASS claim: a build or test command that
 #: ran to completion and returned nonzero. Nothing weaker. See the module
 #: docstring's fail-direction section — this frozenset IS that safety property.
@@ -188,7 +204,7 @@ REFUTING_KINDS = frozenset({KIND_BUILD, KIND_SUITE})
 
 #: Kinds meaning "the check could not reach a verdict". The caller falls back to
 #: the worker's own claim on any of these, which is pre-#2464 behaviour.
-INCONCLUSIVE_KINDS = frozenset({KIND_SETUP, KIND_INFRA, KIND_TIMEOUT})
+INCONCLUSIVE_KINDS = frozenset({KIND_SETUP, KIND_INFRA, KIND_TIMEOUT, KIND_SIGNAL})
 
 
 # ── Per-pass budget (#2464-review) ──────────────────────────────────────────
@@ -477,10 +493,35 @@ def _classify_failure(
 ) -> ConfirmationResult:
     """Turn a nonzero build/test exit into the right kind.
 
-    Order matters and mirrors :func:`coord.revalidate.revalidate`: infra first
-    (the suite never ran), then baseline-red (it ran, but the branch is not at
-    fault), and only what is left over is a genuine refutation.
+    Order matters and mirrors :func:`coord.revalidate.revalidate`: signal-kill
+    first (#2527 — the command never ran to completion at all, so there is
+    nothing left to classify), then infra (the suite never ran), then
+    baseline-red (it ran, but the branch is not at fault), and only what is
+    left over is a genuine refutation.
     """
+    if returncode < 0:
+        # #2527: a negative returncode means `subprocess.run` reports the
+        # child was killed BY a signal, not that it ran and exited nonzero —
+        # e.g. `-15` for SIGTERM from a `coord-agent`/`coord-serve` restart
+        # landing mid-confirmation, or a manual `kill`. Same fail-direction
+        # as `subprocess.TimeoutExpired` just above this function's callers:
+        # a command that never finished says nothing about the branch, so
+        # this must stay inconclusive — never `REFUTING_KINDS` — no matter
+        # how "nonzero" the raw exit code looks.
+        return ConfirmationResult(
+            kind=KIND_SIGNAL,
+            reason=(
+                f"confirmation {stage} command was killed by signal "
+                f"{-returncode} (exit {returncode}) rather than running to "
+                "completion — like a timeout, a command that never finished "
+                "says nothing about the branch, so this is not a refutation "
+                "(#2527)"
+            ),
+            output=_tail(output),
+            command=command,
+            returncode=returncode,
+            worktree=worktree,
+        )
     infra = is_infrastructure_failure(returncode, output)
     baseline = not infra and is_baseline_red_failure(returncode, output)
     if infra:
@@ -780,6 +821,7 @@ __all__ = [
     "CONFIRM_PASS_BUDGET_SECONDS",
     "DISABLE_ENV_VAR",
     "INCONCLUSIVE_KINDS",
+    "KIND_SIGNAL",
     "NOTIFY_BASE_CLIENT_TIMEOUT_SECONDS",
     "REFUTING_KINDS",
     "ConfirmationResult",

{code_coordinator-0.5.207 → code_coordinator-0.5.210}/coord/dashboard/fixture.py

@@ -36,6 +36,8 @@ Fixture schema (every key optional except ``board``)::
       "machines":        [ {...GET /api/machines entry...} ],
       "sessions":        [ {...GET /api/sessions entry...} ],
       "drive_queue":     [ {...coord.state._decode_drive_queue_row shape...} ],
+      "report_catalogue": {"reports": [ {...coord.reports.ReportDef.to_dict()...} ]},
+      "report_results":  {"issue-activity": {...coord.reports.ReportResult.to_dict()...}},
       "review_findings": {"rev-1": {"verdict": "approve", "body": "..."}},
       "diffs":           {"work-1": "diff --git ..."},
       "chat_reply":      "canned /api/chat response text",
@@ -60,6 +62,7 @@ from __future__ import annotations
 
 import copy
 import json
+from collections.abc import Mapping
 from dataclasses import MISSING, asdict, dataclass, field, fields
 from pathlib import Path
 from typing import Any
@@ -156,6 +159,12 @@ class FixtureServer:
     machines_raw: list = field(default_factory=list)
     sessions_raw: list = field(default_factory=list)
     drive_queue_raw: list = field(default_factory=list)
+    #: #2492 RPT-1: `GET /api/report`'s catalogue. `None` (the default) falls
+    #: back to the real `coord.reports.catalogue()` — see `report_catalogue()`.
+    report_catalogue_raw: dict | None = None
+    #: #2492 RPT-1: seeded `GET /api/report/{id}` results, keyed by report id
+    #: — see `report_result()`.
+    report_results_raw: dict = field(default_factory=dict)
     review_findings_raw: dict = field(default_factory=dict)
     diffs: dict = field(default_factory=dict)
     chat_reply: str = "fixture mode: the coordinator assistant is not wired up."
@@ -210,6 +219,51 @@ class FixtureServer:
             rows = [r for r in rows if r.get("repo_name") == repo_name]
         return rows
 
+    def report_catalogue(self) -> dict[str, Any]:
+        """The seeded ``GET /api/report`` catalogue (#2492 RPT-1).
+
+        Unlike the board/drive-queue, ``coord.reports.catalogue()`` is pure
+        in-process metadata (report ids/titles/param definitions) — never a
+        DB read — so it is already deterministic without seeding. A fixture
+        overrides it only when a test wants a different catalogue than
+        production's (e.g. a smaller one for a focused scenario); absent an
+        override, this falls back to the real registry so `report_result()`
+        below (which validates against seeded results, not the catalogue)
+        stays the only place a report fixture is actually required.
+        """
+        if self.report_catalogue_raw is not None:
+            return copy.deepcopy(self.report_catalogue_raw)
+        from coord import reports as _reports  # noqa: PLC0415
+
+        return _reports.catalogue()
+
+    def report_result(
+        self, report_id: str, params: Mapping[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """The seeded ``ReportResult``-shaped dict for *report_id* (#2492 RPT-1).
+
+        Keyed by report id only — one canned result per id, mirroring how
+        ``diffs`` is one canned string per assignment id rather than
+        branching on request details. ``params`` is accepted only for
+        signature symmetry with ``coord.reports.run_report(report_id,
+        params)``; a fixture that needs a param-sensitive variant seeds a
+        distinct fixture file per scenario, same as every other accessor
+        here.
+
+        Raises the real :class:`coord.reports.UnknownReportError` for a
+        report id with no seeded result, so ``GET /api/report/{id}`` returns
+        the byte-identical 404 shape in fixture and live mode.
+        """
+        from coord import reports as _reports  # noqa: PLC0415
+
+        entry = self.report_results_raw.get(report_id)
+        if entry is None:
+            raise _reports.UnknownReportError(
+                f"unknown report {report_id!r} — known reports: "
+                f"{', '.join(sorted(self.report_results_raw))}"
+            )
+        return copy.deepcopy(entry)
+
     def review_findings(self, assignment_id: str) -> tuple[str, str] | None:
         """Stand-in for ``coord.state.load_assignment_review_findings``.
 
@@ -353,6 +407,17 @@ def parse_fixture(raw: Any, *, path: Path | None = None) -> FixtureServer:
     if not all(isinstance(v, str) for v in diffs.values()):
         raise FixtureError("fixture 'diffs' values must be strings")
 
+    report_catalogue_raw = raw.get("report_catalogue")
+    if report_catalogue_raw is not None and not isinstance(report_catalogue_raw, dict):
+        raise FixtureError(
+            "fixture 'report_catalogue' must be a mapping (the GET /api/report response shape)"
+        )
+    report_results_raw = _as_dict(raw.get("report_results"), "report_results")
+    if not all(isinstance(v, dict) for v in report_results_raw.values()):
+        raise FixtureError(
+            "fixture 'report_results' values must be mappings (ReportResult wire shape)"
+        )
+
     server = FixtureServer(
         board_payload=board_payload,
         merge_queue_raw=_as_list(raw.get("merge_queue"), "merge_queue"),
@@ -360,6 +425,8 @@ def parse_fixture(raw: Any, *, path: Path | None = None) -> FixtureServer:
         machines_raw=_as_list(raw.get("machines"), "machines"),
         sessions_raw=_as_list(raw.get("sessions"), "sessions"),
         drive_queue_raw=_as_list(raw.get("drive_queue"), "drive_queue"),
+        report_catalogue_raw=report_catalogue_raw,
+        report_results_raw=report_results_raw,
         review_findings_raw=_as_dict(raw.get("review_findings"), "review_findings"),
         diffs=diffs,
         events=_parse_events(raw.get("events")),

{code_coordinator-0.5.207 → code_coordinator-0.5.210}/coord/dashboard/server.py

@@ -15,7 +15,13 @@ from pathlib import Path
 import httpx
 from starlette.applications import Starlette
 from starlette.requests import Request
-from starlette.responses import FileResponse, HTMLResponse, JSONResponse, StreamingResponse
+from starlette.responses import (
+    FileResponse,
+    HTMLResponse,
+    JSONResponse,
+    Response,
+    StreamingResponse,
+)
 from starlette.routing import Mount, Route, WebSocketRoute
 from starlette.staticfiles import StaticFiles
 from starlette.websockets import WebSocket, WebSocketDisconnect
@@ -449,6 +455,119 @@ def openapi_spec() -> dict:
             "summary": drive_queue_summary_ref,
         },
     }
+    # #2492 RPT-1: the report engine's wire types. `dataclass_schema` walks
+    # `coord.reports` dataclasses straight (like `DriveQueueSummary` above)
+    # for the ones its generic dataclass -> JSON-Schema walk actually
+    # supports (`RowIdentity`/`ColumnMeta`/`ChartSeries` have no `tuple[...]`
+    # or `Callable` fields). `ReportParam`/`ReportDef`/`ChartSpec`/
+    # `ReportResult` do — `ReportParam.validate`/`ReportDef.run` are
+    # deliberately non-wire (excluded from their own `to_dict()`), and
+    # `coord/openapi.py:json_schema_for` has no mapping for `Callable` or
+    # `tuple[...]` at all (`ChartSpec.series`, `ReportResult.window`,
+    # `ReportDef.params`, `ReportParam.choices` are all tuples on the
+    # dataclass but lists on the wire) — so those four are hand-built here,
+    # matching each type's own `to_dict()` field-for-field, the same way
+    # `board_response`/`session_response` below are hand-built rather than
+    # derived. Registered as named `components` refs either way (not inlined
+    # like `board_response`) because these are reused across both report
+    # routes and are what #1550's TS codegen (`scripts/codegen.py`) emits an
+    # `interface` for.
+    from coord.reports import ChartSeries, ColumnMeta, RowIdentity  # noqa: PLC0415 — mirrors serve_app.py's lazy `reports` import
+
+    row_identity_ref = dataclass_schema(RowIdentity, components)
+    column_meta_ref = dataclass_schema(ColumnMeta, components)
+    chart_series_ref = dataclass_schema(ChartSeries, components)
+    components["ReportParam"] = {
+        "type": "object",
+        "properties": {
+            "id": {"type": "string"},
+            "label": {"type": "string"},
+            "kind": {"type": "string", "description": "choice|text"},
+            "choices": {"type": "array", "items": {"type": "string"}},
+            "default": {"type": "string"},
+            "help": {"type": "string"},
+            "free_form": {
+                "type": "boolean",
+                "description": "choices are presets, not a whitelist",
+            },
+        },
+        "required": ["id", "label"],
+    }
+    report_param_ref = {"$ref": "#/components/schemas/ReportParam"}
+    components["ReportDef"] = {
+        "type": "object",
+        "properties": {
+            "id": {"type": "string"},
+            "title": {"type": "string"},
+            "description": {"type": "string"},
+            "params": {"type": "array", "items": report_param_ref},
+            "row_identity": {**row_identity_ref, "nullable": True},
+        },
+        "required": ["id", "title", "description", "params"],
+    }
+    report_def_ref = {"$ref": "#/components/schemas/ReportDef"}
+    components["ChartSpec"] = {
+        "type": "object",
+        "properties": {
+            "kind": {
+                "type": "string",
+                "description": "open vocabulary — bar|line|sparkline today",
+            },
+            "series": {"type": "array", "items": chart_series_ref},
+            "x": {"type": "string", "nullable": True},
+            "group_by": {"type": "string", "nullable": True},
+            "stacked": {"type": "boolean"},
+            "title": {"type": "string"},
+            "y_label": {"type": "string"},
+        },
+        "required": ["kind", "series"],
+    }
+    chart_spec_ref = {"$ref": "#/components/schemas/ChartSpec"}
+    components["ReportResult"] = {
+        "type": "object",
+        "properties": {
+            "report_id": {"type": "string"},
+            "generated_at": {"type": "number"},
+            "window": {"type": "array", "items": {"type": "number"}},
+            "columns": {"type": "array", "items": {"type": "string"}},
+            "column_meta": {"type": "array", "items": column_meta_ref},
+            "rows": {"type": "array", "items": {"type": "object"}},
+            "notes": {"type": "array", "items": {"type": "string"}},
+            "totals": {
+                "type": "object",
+                "nullable": True,
+                "description": (
+                    "#1763: optional grand-total row keyed by the same "
+                    "column ids as `rows`. `null` for reports with no "
+                    "meaningful sum."
+                ),
+            },
+            "chart": {
+                **chart_spec_ref,
+                "nullable": True,
+                "description": (
+                    "#2271: optional chart declaration — carries no numbers "
+                    "of its own, the renderer reads the same `rows` the "
+                    "table does."
+                ),
+            },
+        },
+        "required": [
+            "report_id",
+            "generated_at",
+            "window",
+            "columns",
+            "column_meta",
+            "rows",
+            "notes",
+        ],
+    }
+    report_result_ref = {"$ref": "#/components/schemas/ReportResult"}
+    report_catalogue_response = {
+        "type": "object",
+        "properties": {"reports": {"type": "array", "items": report_def_ref}},
+        "required": ["reports"],
+    }
     board_response = {
         "type": "object",
         "properties": {
@@ -580,6 +699,70 @@ def openapi_spec() -> dict:
                 },
             }
         },
+        "/api/report": {
+            "get": {
+                "summary": (
+                    "#2492: the report catalogue — ids, titles, descriptions "
+                    "and full parameter metadata (kind/choices/default), so "
+                    "a client builds its parameter form from here rather "
+                    "than hardcoding it"
+                ),
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "application/json": {"schema": report_catalogue_response}
+                        },
+                    }
+                },
+            }
+        },
+        "/api/report/{report_id}": {
+            "get": {
+                "summary": (
+                    "#2492: run a report and return its ReportResult. "
+                    "Read-only — no board write, no reconcile side effect. "
+                    "Query parameters are the report's own params (see "
+                    "GET /api/report)"
+                ),
+                "parameters": [
+                    _dashboard_path_param("report_id", "report id from the catalogue"),
+                    {
+                        "name": "format",
+                        "in": "query",
+                        "required": False,
+                        "schema": {"type": "string", "enum": ["json", "csv"]},
+                        "description": (
+                            "#1765: response encoding. Absent/`json` returns "
+                            "the ReportResult unchanged; `csv` returns "
+                            "text/csv (raw values, `#`-prefixed notes) with "
+                            "a Content-Disposition filename."
+                        ),
+                    },
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "application/json": {"schema": report_result_ref},
+                            "text/csv": {
+                                "schema": {"type": "string"},
+                                "description": (
+                                    "`?format=csv`. Header row labelled from "
+                                    "`column_meta`, one row per `rows` entry "
+                                    "with raw values, `notes` as leading `#` "
+                                    "lines."
+                                ),
+                            },
+                        },
+                    },
+                    "400": {
+                        "description": "Unknown parameter / bad parameter value / unknown format"
+                    },
+                    "404": {"description": "Unknown report id"},
+                },
+            }
+        },
         "/api/approve": {
             "post": {
                 "summary": "Dispatch one or more proposals by id",
@@ -923,6 +1106,22 @@ def build_app(
             }
         raise ValueError(f"unknown drive-queue action: {action!r}")
 
+    def _report_catalogue() -> dict:
+        """The report engine's catalogue — seeded fixture or the real
+        registry (#2492).
+
+        Unlike ``_read_drive_queue()``, there is no daemon-vs-local split to
+        resolve here: ``coord.reports.catalogue()`` is pure in-process
+        metadata (report ids/titles/param definitions), never a DB read, so
+        live mode calls it directly — same as ``coord/serve_app.py``'s own
+        ``get_report_catalogue``.
+        """
+        if _fixture is not None:
+            return _fixture.report_catalogue()
+        from coord import reports as _reports  # noqa: PLC0415
+
+        return _reports.catalogue()
+
     # ── Real-time event bus ────────────────────────────────────────────────
     event_source = EventSource()
 
@@ -1395,6 +1594,73 @@ def build_app(
             )
         return JSONResponse({"ok": True})
 
+    async def api_report_catalogue(request: Request) -> Response:  # noqa: ARG001 — Starlette handler signature
+        """GET /api/report — the report catalogue (#2492).
+
+        Mirrors ``coord/serve_app.py``'s ``get_report_catalogue`` almost
+        verbatim, just routed through ``_report_catalogue()`` — the
+        fixture-vs-live indirection every handler in this file goes through
+        (see ``_read_board()``/``_read_drive_queue()``).
+        """
+        return JSONResponse(_report_catalogue())
+
+    async def api_report_run(request: Request) -> Response:
+        """GET /api/report/{report_id}?... — run a report and return its
+        ReportResult (#2492).
+
+        Mirrors ``coord/serve_app.py``'s ``get_report`` almost verbatim:
+        ``format`` is popped before param validation (a rendering choice,
+        not a report parameter — #1765), ``UnknownReportError`` -> 404,
+        ``ReportError`` -> 400, anything else -> 503. ``run_report`` reads
+        local state directly (audit_log/issues/assignments) same as the
+        daemon does today, so live mode needs no board-daemon proxy either
+        — only fixture mode swaps the source, via
+        ``_fixture.report_result()``.
+        """
+        from starlette.concurrency import run_in_threadpool  # noqa: PLC0415
+
+        from coord import reports as _reports  # noqa: PLC0415
+
+        report_id = request.path_params["report_id"]
+        params = dict(request.query_params)
+        # #1765: `format` is a *rendering* choice, not a report parameter —
+        # pop it before validation or `resolve_params` rejects it as an
+        # unknown parameter.
+        fmt = (params.pop("format", "") or "json").strip().lower()
+        if fmt not in ("json", "csv"):
+            return JSONResponse(
+                {"error": f"unknown format {fmt!r} — allowed values: json, csv"},
+                status_code=400,
+            )
+        try:
+            if _fixture is not None:
+                result = _fixture.report_result(report_id, params)
+            else:
+                result = await run_in_threadpool(_reports.run_report, report_id, params)
+        except _reports.UnknownReportError as e:
+            return JSONResponse({"error": str(e)}, status_code=404)
+        except _reports.ReportError as e:
+            return JSONResponse({"error": str(e)}, status_code=400)
+        except Exception as e:  # noqa: BLE001 — surface a clean 503 rather than a stack trace
+            return JSONResponse(
+                {"error": "report run failed", "detail": str(e)}, status_code=503
+            )
+        if fmt == "csv":
+            # Same serializer the CLI calls, so `coord report run --format
+            # csv` and this route emit identical bytes for identical params.
+            return Response(
+                _reports.result_to_csv(result),
+                media_type="text/csv; charset=utf-8",
+                headers={
+                    "Content-Disposition": (
+                        f'attachment; filename="{_reports.csv_filename(result)}"'
+                    )
+                },
+            )
+        return JSONResponse(
+            result.to_dict() if isinstance(result, _reports.ReportResult) else result
+        )
+
     async def api_approve(request: Request) -> JSONResponse:
         from coord.dispatch import dispatch, post_briefing, compute_do_not_touch
         from coord.state import (
@@ -2316,6 +2582,8 @@ def build_app(
         Route("/api/proposals", api_proposals, methods=["GET"]),
         Route("/api/drive-queue", api_drive_queue, methods=["GET"]),
         Route("/api/drive-queue/action", api_drive_queue_action, methods=["POST"]),
+        Route("/api/report", api_report_catalogue, methods=["GET"]),
+        Route("/api/report/{report_id}", api_report_run, methods=["GET"]),
         Route("/api/approve", api_approve, methods=["POST"]),
         Route("/api/reject", api_reject, methods=["POST"]),
         Route("/api/diff/{id}", api_diff, methods=["GET"]),