code-coordinator 0.5.206__tar.gz → 0.5.209__tar.gz

{code_coordinator-0.5.206 → code_coordinator-0.5.209}/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.206 → code_coordinator-0.5.209}/PKG-INFO

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

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

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.206",
+  "tag": "0.5.209",
   "distance": 0,
-  "node": "g3c2392941a4c874655cc8ccc15a0ef5112a0d822",
+  "node": "g8dd6856fa1b46016cf34e83dd691cc4cec06d72e",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-21"

{code_coordinator-0.5.206 → code_coordinator-0.5.209}/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.206 → code_coordinator-0.5.209}/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"]),

{code_coordinator-0.5.206 → code_coordinator-0.5.209}/coord/db.py

@@ -583,13 +583,35 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         -- CHECK pins it to one row so "which cursor?" can never be a
         -- question).  `pull_cursor` is opaque to coord — it is whatever the
         -- portal handed back — and is the replay point on daemon restart.
+        --
+        -- `verdict_watermark_at` / `verdict_watermark_rowid` (#2509 review
+        -- fix): the verdict consumer's OWN read position into
+        -- `portal_events`, independent of the shared `handled_at` column.
+        -- `unhandled_events()`/`mark_event_handled()` are shared plumbing —
+        -- this consumer only stamps `handled_at` for a `changes_requested`
+        -- event it actually dispatched, leaving every other kind (a new
+        -- submission, an `approved` verdict, a Q&A answer) NULL by design so
+        -- a future consumer can still read it.  Scanning by `handled_at IS
+        -- NULL` therefore re-returns that growing, never-marked backlog
+        -- ahead of anything newer forever once it exceeds one page — a real
+        -- `changes-requested` event behind it would never surface.  A
+        -- private watermark sidesteps that: it advances past every event
+        -- this consumer has looked at, acted on or not, so a pile of
+        -- non-actionable events cannot block the ones behind it.
+        -- `(received_at, rowid)` mirrors `unhandled_events`'s own tiebreaker
+        -- ordering.
+        -- Both NULL until the first tick with this column runs (an empty
+        -- `~/.coord/coord.db` or one predating this migration), read as
+        -- `(0.0, 0)` — before every real event's `received_at`/`rowid`.
         CREATE TABLE IF NOT EXISTS portal_sync_state (
-            id                INTEGER PRIMARY KEY CHECK (id = 1),
-            pull_cursor       TEXT,
-            last_pull_at      REAL,
-            last_push_at      REAL,
-            last_heartbeat_at REAL,
-            last_error        TEXT NOT NULL DEFAULT ''
+            id                    INTEGER PRIMARY KEY CHECK (id = 1),
+            pull_cursor           TEXT,
+            last_pull_at          REAL,
+            last_push_at          REAL,
+            last_heartbeat_at     REAL,
+            last_error            TEXT NOT NULL DEFAULT '',
+            verdict_watermark_at    REAL,
+            verdict_watermark_rowid INTEGER
         );
 
         CREATE INDEX IF NOT EXISTS idx_assignments_status ON assignments(status);
@@ -942,6 +964,18 @@ def _migrate_add_columns(conn: sqlite3.Connection) -> None:
         # predating this migration, same as the column's own default for a
         # freshly-enqueued entry.
         "ALTER TABLE merge_queue ADD COLUMN ci_fix_dispatches INTEGER NOT NULL DEFAULT 0",
+        # #2509 review fix: the verdict consumer's own read position into
+        # `portal_events` — see the CREATE TABLE comment above for why it
+        # cannot reuse the shared `handled_at` column. NULL (read as
+        # `(0.0, 0)`, before every real event) for every database predating
+        # this migration, which replays the full existing inbox exactly once
+        # on upgrade — safe: re-scanning a non-actionable event is a no-op,
+        # and `_consume_verdicts` skips (never re-dispatches) any event
+        # whose `handled_at` is already set, so an already-consumed
+        # `changes_requested` event from before this migration is walked
+        # past, not re-sent — see `coord.portal_sync._consume_verdicts`.
+        "ALTER TABLE portal_sync_state ADD COLUMN verdict_watermark_at REAL",
+        "ALTER TABLE portal_sync_state ADD COLUMN verdict_watermark_rowid INTEGER",
     ]
     for sql in migrations:
         try:

{code_coordinator-0.5.206 → code_coordinator-0.5.209}/coord/gate_a.py

@@ -224,6 +224,19 @@ def make_record(
     ``verdict`` must be one of :data:`VERDICTS`; anything else is a
     programming error, not an operator error (the CLI's mutually-exclusive
     ``--approved``/``--changes`` flags already reject bad input).
+
+    **Open policy question (#2509, flagged for the operator, not resolved by
+    this call or any caller yet):** should an "approved" verdict on the
+    customer portal auto-call this with ``verdict=VERDICT_APPROVED`` — i.e.
+    does a client's portal sign-off record itself — or does an operator
+    still confirm separately via the existing CLI/TUI path? Today nothing
+    does the former: ``coord.portal_sync._consume_verdicts`` only acts on
+    `changes-requested` (auto-amending the contract) and deliberately leaves
+    `approved` events unconsumed rather than silently picking an answer here.
+    Whichever way this is eventually decided, an auto-recorded call MUST
+    pass ``actor="client via portal"`` (or similarly explicit) — never leave
+    ``actor`` to default such that a client's decision reads as if some
+    coord process made it.
     """
     if verdict not in VERDICTS:
         raise ValueError(f"unknown Gate A verdict {verdict!r}")