code-coordinator 0.5.321__tar.gz → 0.5.323__tar.gz

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/PKG-INFO

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

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

@@ -403,6 +403,7 @@ tests/test_approve_dependency_busy_2804.py
 tests/test_approve_reject_plan.py
 tests/test_approve_usage_gate.py
 tests/test_approved_work_2532.py
+tests/test_approved_work_2996.py
 tests/test_assignment_already_recorded_daemon.py
 tests/test_audit_log.py
 tests/test_audit_outcome.py

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/code_coordinator.egg-info/scm_file_list.json

@@ -429,6 +429,7 @@
     "tests/test_approve_reject_plan.py",
     "tests/test_approve_usage_gate.py",
     "tests/test_approved_work_2532.py",
+    "tests/test_approved_work_2996.py",
     "tests/test_assignment_already_recorded_daemon.py",
     "tests/test_audit_log.py",
     "tests/test_audit_outcome.py",

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.321",
+  "tag": "0.5.323",
   "distance": 0,
-  "node": "g0b3cfbaeacfdc63b22ee0b9e78fa04e6afa9ccad",
+  "node": "g6d62d0b99d361f200c0329792182a2f8918b2864",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-31"

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/coord/approved_work.py

@@ -256,6 +256,47 @@ def approved_submission_ids() -> set[str]:
     return {sid for sid, verdict in _fold_signoff_verdicts().items() if verdict == "approved"}
 
 
+def is_pulled_status(status: str) -> bool:
+    """Whether *status* is one of :data:`_PULLED_STATUSES` — the public,
+    non-underscore way for another module (:mod:`coord.commands.portal`,
+    #2996) to ask "would pushing this status withdraw a submission from
+    :func:`approved_submissions`?" without reaching into this module's
+    private constant.
+    """
+    return status in _PULLED_STATUSES
+
+
+def disqualifying_status(submission_id: str) -> str | None:
+    """The ``last_status`` responsible for *submission_id* being missing
+    from :func:`approved_submissions` despite an ``approved`` sign-off
+    verdict on file — or ``None`` when that is not why it is missing (never
+    approved, no record at all, or genuinely not pulled) (#2996).
+
+    Reads local :mod:`coord.portal_store` directly, same as
+    :func:`approved_submissions` itself — so, like that function, this is
+    only meaningful when called on the daemon host (the caller is
+    responsible for that; see :func:`coord.commands.portal.
+    _refuse_if_thin_client` and :func:`coord.decomposition_chat.
+    resolve_approved_submission`'s own thin-client routing).
+
+    Exists so a "why isn't this on the queue" failure message
+    (:func:`coord.decomposition_chat.resolve_approved_submission`'s callers)
+    can name the actual cause — a status an operator pushed by hand, most
+    often via ``coord portal enqueue-status`` — instead of the generic
+    "is not a currently-approved portal submission", which names neither.
+    """
+    from coord import portal_store  # noqa: PLC0415 — avoid import cycle
+
+    record = portal_store.get_submission(submission_id)
+    if record is None:
+        return None
+    if record.submission_id not in approved_submission_ids():
+        return None
+    if record.last_status in _PULLED_STATUSES:
+        return record.last_status
+    return None
+
+
 def approved_submissions(config: "Config") -> list[dict[str, Any]]:
     """The ``/board`` ``approved_submissions`` payload, **oldest first**.
 

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/coord/commands/portal.py

@@ -612,6 +612,7 @@ def _run_decompose_chat_interactive(
     )
     from coord.decomposition_chat import (  # noqa: PLC0415
         build_decomposition_chat_briefing,
+        describe_unapproved_submission,
         fetch_running_context,
         render_running_context_section,
         repo_topology_context,
@@ -633,8 +634,7 @@ def _run_decompose_chat_interactive(
     submission = resolve_approved_submission(cfg, submission_id)
     if submission is None:
         click.secho(
-            f"error: submission {submission_id!r} is not a currently-approved "
-            "portal submission — nothing to decompose",
+            f"error: {describe_unapproved_submission(cfg, submission_id)}",
             fg="red",
         )
         raise SystemExit(1)
@@ -1343,11 +1343,48 @@ def portal_enqueue_status(submission_id: str, status: str) -> None:
     Unlike `push`, this allocates the revision for you and refuses a status
     that would summon the customer to an empty screen — `awaiting-signoff`
     with no design round queued, `needs-input` with no question (#835).
+
+    **#2996: warns, never refuses, before a `_PULLED_STATUSES` push that
+    would silently withdraw SUBMISSION_ID from decomposition.**
+    `coord.approved_work.approved_submissions` (the "Approved work items"
+    panel's data source) drops any submission whose `last_status` moves to
+    `planned` / `in-progress` / `quality-check` / `shipped` — those four
+    values are only ever supposed to mean "already pulled into a linked
+    milestone/issue and dispatch has begun". Pushing one of them here on a
+    submission with no `coord portal link` on file does that removal anyway,
+    with nothing to say so — the observed failure mode (#2996's own filing)
+    was a status pushed purely to update the customer-facing wording, which
+    happened to also empty the queue and only surfaced later as an unrelated
+    "not a currently-approved portal submission" error. This command still
+    sends the push regardless — there are legitimate reasons to set any of
+    these by hand (a correction, a re-sync, an out-of-band delivery) — it
+    only makes the consequence visible first.
     """
     _refuse_if_thin_client("enqueue-status")
 
+    from coord.approved_work import is_pulled_status  # noqa: PLC0415
     from coord.portal_sync import PortalSyncError, enqueue_status  # noqa: PLC0415
 
+    if is_pulled_status(status):
+        from coord import portal_store  # noqa: PLC0415
+
+        if portal_store.get_link_by_submission(submission_id) is None:
+            click.secho(
+                f"warning: {submission_id} has no linked milestone/issue on "
+                "file (no `coord portal link` recorded) and no decomposition "
+                f"on record — pushing status={status!r} will still be sent, "
+                "but coord treats that status as \"already pulled into "
+                f"decomposition and delivery\": {submission_id} will vanish "
+                "from the TUI's Approved work items panel, and `coord portal "
+                "decompose-chat` will refuse it as no longer approved. If "
+                "the work has not actually been decomposed yet and you just "
+                "want an honest \"we know what's next\" status for the "
+                f"customer, use `coord portal enqueue-status {submission_id} "
+                "in-design` instead — it stays on the queue and announces "
+                "nobody.",
+                fg="yellow",
+            )
+
     try:
         row = enqueue_status(submission_id, status)
     except PortalSyncError as exc:
@@ -1838,6 +1875,13 @@ def _render_ledger_text(payload: dict) -> str:
                 lines.append(_render_answer_line(a, indent="    "))
         else:
             lines.append("    (unanswered — needs-input)")
+        # #2987: `.get` — a thin client may be talking to a daemon that
+        # predates this key.
+        for c in entry.get("confirmations") or []:
+            when = datetime.datetime.fromtimestamp(
+                c["recorded_at"], tz=datetime.timezone.utc
+            ).strftime("%Y-%m-%d %H:%M UTC")
+            lines.append(f"    [CONFIRMED by {c['actor'] or 'customer'}, {when}]")
     for a in unpaired:
         tag = " RELAYED" if a.get("relayed") else ""
         lines.append(
@@ -2076,6 +2120,14 @@ def portal_answer(
     refused — it routes through the daemon's ``/portal-answer`` seam when
     ``board_service`` is configured, so it works from wherever the operator
     happens to be.
+
+    Also queues the answer OUTBOUND to the portal (#2987, coord-portal#159,
+    best-effort) — draft-gated like a question or design round under the
+    default ``portal.approval`` policy, so it sits in ``coord portal
+    drafts`` until approved. Once sent, the client sees exactly what was
+    recorded and can confirm or correct it in one tap; a confirm marks this
+    ledger row client-confirmed, a correction lands as a normal answer
+    alongside it.
     """
     from coord import portal_store  # noqa: PLC0415
     from coord.board_service import resolve  # noqa: PLC0415

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/coord/config.py

@@ -2173,7 +2173,12 @@ class PortalProjectRepo:
 #: imports ``coord.db``, and config must stay importable by everything.
 #: ``tests/test_portal_config.py`` pins the two lists together so the copy
 #: cannot silently drift.
-PORTAL_OUTBOX_KINDS = ("status", "design_round", "question", "preview")
+PORTAL_OUTBOX_KINDS = (
+    "status", "design_round", "question", "preview",
+    # #2987: a relayed answer (#2986) pushed outbound for the client to
+    # confirm/correct — see `coord.portal_sync.KIND_RELAYED_ANSWER`.
+    "relayed_answer",
+)
 
 #: The draft gate's default policy (#2903, phase 1 of #2902): the two kinds
 #: that carry **agent-authored prose to a customer** are held for an
@@ -2184,11 +2189,16 @@ PORTAL_OUTBOX_KINDS = ("status", "design_round", "question", "preview")
 #: read and rewrite, and gating them would produce a rubber-stamp queue of
 #: "In progress" ×N that trains the operator to approve without reading,
 #: which is the failure mode this gate exists to prevent (see epic #2902).
+#: #2987: a relayed answer is prose an operator typed on the client's
+#: behalf — "the most worth reading before it sends" (the issue's own
+#: framing) — so it is gated like the other two prose kinds, not left
+#: ungated like `status`/`preview`.
 DEFAULT_PORTAL_APPROVAL: dict[str, bool] = {
     "status": False,
     "design_round": True,
     "question": True,
     "preview": False,
+    "relayed_answer": True,
 }
 
 

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/coord/db.py

@@ -591,7 +591,10 @@ def retry_on_locked(
 #
 # #2786: bumped 5 -> 6 for the `assignments.num_turns` column appended to
 # `_migrate_add_columns` below.
-_DB_SCHEMA_VERSION = 6
+#
+# #2987: bumped 6 -> 7 for the two `portal_sync_state.relayed_answer_
+# watermark_*` columns appended to `_migrate_add_columns` below.
+_DB_SCHEMA_VERSION = 7
 
 
 def _read_schema_version(conn: sqlite3.Connection) -> int:
@@ -1237,7 +1240,17 @@ _SCHEMA_SQL = """
             verdict_watermark_at    REAL,
             verdict_watermark_rowid TEXT,
             question_watermark_at    REAL,
-            question_watermark_rowid TEXT
+            question_watermark_rowid TEXT,
+            -- #2987: the relayed-answer CONFIRMATION consumer's own read
+            -- position — same shape and same reason as
+            -- `question_watermark_at`/`question_watermark_rowid` just above
+            -- (a private watermark, independent of `handled_at`, so the
+            -- never-marked backlog every OTHER event kind leaves behind
+            -- cannot starve this consumer of a `relayed_answer.confirmed`
+            -- event newer than it). See
+            -- `coord.portal_sync._consume_relayed_answer_confirmations`.
+            relayed_answer_watermark_at    REAL,
+            relayed_answer_watermark_rowid TEXT
         );
 
         -- #2749 (IL-3, epic #2746): the running-context ledger — the record
@@ -1755,6 +1768,18 @@ _MIGRATE_ADD_COLUMNS: list[str] = [
     # `question_answered` event a no-op rather than a duplicate ledger row.
     "ALTER TABLE portal_sync_state ADD COLUMN question_watermark_at REAL",
     "ALTER TABLE portal_sync_state ADD COLUMN question_watermark_rowid TEXT",
+    # #2987: the relayed-answer confirmation consumer's own read position
+    # into `portal_events` — same reason and same shape as
+    # `question_watermark_at`/`question_watermark_rowid` above. NULL (read
+    # as `(0.0, "")`, before every real event) for every database predating
+    # this migration, which replays the full existing inbox exactly once on
+    # upgrade — safe for the same reason replaying it is safe for the
+    # question consumer: `append_ledger_entry`'s `(submission_id, kind,
+    # source_event_id)` dedupe makes a re-observed event a no-op rather than
+    # a duplicate ledger row. See
+    # `coord.portal_sync._consume_relayed_answer_confirmations`.
+    "ALTER TABLE portal_sync_state ADD COLUMN relayed_answer_watermark_at REAL",
+    "ALTER TABLE portal_sync_state ADD COLUMN relayed_answer_watermark_rowid TEXT",
     # #2786: worker-reported turn count, parsed off the final stream-json
     # `result` event into `WorkerSummary.num_turns` (coord/worker_events.py)
     # alongside the four token columns above, but never persisted until now.

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/coord/decomposition_chat.py

@@ -38,6 +38,7 @@ posture every other dispatcher in this file already uses.
 from __future__ import annotations
 
 import datetime
+import logging
 import time
 import uuid
 from typing import TYPE_CHECKING, Any
@@ -46,6 +47,8 @@ if TYPE_CHECKING:  # pragma: no cover - typing only
     from coord.config import Config
     from coord.models import Machine
 
+_log = logging.getLogger(__name__)
+
 #: Sentinel `issue_title` this module writes onto the dispatched assignment
 #: — mirrors `dispatch_new_issue_chat`'s own `"(new issue draft)"` sentinel
 #: for a chat type with no real GitHub issue yet. The TUI's own bind path
@@ -546,6 +549,71 @@ def resolve_approved_submission(config: "Config", submission_id: str) -> dict[st
     )
 
 
+def describe_unapproved_submission(config: "Config", submission_id: str) -> str:
+    """Human-readable reason :func:`resolve_approved_submission` returned
+    ``None`` for *submission_id* (#2996).
+
+    Names the disqualifying ``last_status`` when that is actually why — most
+    often an operator's own ``coord portal enqueue-status`` push to a
+    :data:`coord.approved_work._PULLED_STATUSES` value on a submission that
+    had not, in fact, been decomposed yet — instead of the generic "is not a
+    currently-approved portal submission", which names neither the cause nor
+    the status that caused it (the whole complaint in #2996's issue body).
+
+    Best-effort: the disqualifying-status lookup
+    (:func:`coord.approved_work.disqualifying_status`) needs to read the
+    daemon's own local :mod:`coord.portal_store` directly, so it is skipped
+    (falling back to the plain generic message) when this machine is a thin
+    client — the same constraint :func:`resolve_approved_submission` itself
+    already works around by routing through the daemon's ``/board`` instead
+    of reading the wrong box's empty tables.
+
+    **This function must never raise.** It exists only to phrase a failure
+    its callers have already decided on — ``dispatch_decomposition_chat``
+    raises ``RuntimeError(describe_unapproved_submission(...))`` and
+    ``_run_decompose_chat_interactive`` prints it — so an exception escaping
+    the *enrichment* lookup would replace a clear, actionable error with a
+    traceback about a completely different subsystem. The store read is
+    therefore best-effort: any failure (an unreadable/locked portal store, a
+    schema older than :func:`coord.approved_work.disqualifying_status`
+    expects, a thin client that slipped past the ``board_service`` check)
+    degrades to the plain generic message, which is exactly the pre-#2996
+    behaviour and still correct — just less specific.
+    """
+    base = f"submission {submission_id!r} is not a currently-approved portal submission"
+
+    reason: str | None = None
+    try:
+        from coord import board_service  # noqa: PLC0415
+
+        if board_service.resolve() is None:
+            from coord.approved_work import disqualifying_status  # noqa: PLC0415
+
+            reason = disqualifying_status(submission_id)
+    except Exception:  # noqa: BLE001 — best-effort enrichment, never break the message
+        _log.debug(
+            "describe_unapproved_submission: disqualifying-status lookup failed "
+            "for %s; falling back to the generic message",
+            submission_id,
+            exc_info=True,
+        )
+        reason = None
+
+    if reason:
+        return (
+            f"{base} — its last_status is {reason!r}, which coord already treats "
+            "as pulled into decomposition/delivery (coord.approved_work."
+            "_PULLED_STATUSES), so it no longer shows up in the TUI's Approved "
+            "work items panel and this command refuses it. If it was pushed to "
+            f"that status before decomposition actually happened, `coord portal "
+            f"enqueue-status {submission_id} in-design` puts it back on the "
+            "queue without re-mailing the customer. Nothing to decompose."
+        )
+    return (
+        f"{base} (coord.approved_work.approved_submissions) — nothing to decompose"
+    )
+
+
 def dispatch_decomposition_chat(
     submission_id: str,
     config: "Config",
@@ -576,10 +644,7 @@ def dispatch_decomposition_chat(
     """
     submission = resolve_approved_submission(config, submission_id)
     if submission is None:
-        raise RuntimeError(
-            f"submission {submission_id!r} is not a currently-approved portal "
-            "submission (coord.approved_work.approved_submissions) — nothing to decompose"
-        )
+        raise RuntimeError(describe_unapproved_submission(config, submission_id))
 
     repos: list[str] = submission.get("repos") or []
     if not repos:

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/coord/portal_bridge.py

@@ -95,6 +95,10 @@ COORD_OWNED_FIELDS = (
     "artifacts",
     "onhold_since",
     "preview_url",
+    # #2987: a relayed answer coord recorded on the client's behalf
+    # (`coord portal answer`, #2986), pushed OUT so the client can see and
+    # confirm/correct it — the wire shape coord-portal#159 specifies.
+    "relayed_answer",
 )
 
 

{code_coordinator-0.5.321 → code_coordinator-0.5.323}/coord/portal_store.py

@@ -948,6 +948,9 @@ class DraftGateError(ValueError):
 EDITABLE_DRAFT_FIELDS: dict[str, tuple[str, ...]] = {
     "question": ("question",),
     "design_round": ("design_round.outcome_definition",),
+    # #2987: the operator's own relayed text — the exact prose the draft
+    # gate exists to let a human read before it reaches the client.
+    "relayed_answer": ("relayed_answer.text",),
 }
 
 
@@ -1450,6 +1453,63 @@ def events_after_question_watermark(
     return [(r["event_id"], _event_from_row(r)) for r in rows]
 
 
+def get_relayed_answer_watermark() -> tuple[float, str]:
+    """The relayed-answer CONFIRMATION consumer's own read position (#2987)
+    — ``(0.0, "")`` if never set. A private watermark, independent of
+    ``verdict_watermark_*``/``question_watermark_*`` above, for the same
+    reason those two are independent of each other: this consumer walks the
+    same ``portal_events`` inbox at its own pace, and every event kind it
+    ignores must not pile up ahead of the next ``relayed_answer.confirmed``
+    event forever. See :func:`get_verdict_watermark`'s docstring for why the
+    sentinel is ``(0.0, "")`` and not ``(0.0, 0)``.
+    """
+    row = sql.execute(
+        _conn(),
+        "SELECT relayed_answer_watermark_at, relayed_answer_watermark_rowid "
+        "FROM portal_sync_state WHERE id = 1",
+    ).fetchone()
+    if row is None or row["relayed_answer_watermark_at"] is None:
+        return (0.0, "")
+    return (
+        row["relayed_answer_watermark_at"],
+        row["relayed_answer_watermark_rowid"] or "",
+    )
+
+
+def set_relayed_answer_watermark(received_at: float, event_id: str) -> None:
+    """Advance the relayed-answer confirmation consumer's read position past
+    ``(received_at, event_id)`` — called after a scan has looked at that
+    row, whatever kind it turned out to be, same reasoning as
+    :func:`set_verdict_watermark`.
+    """
+    _update_sync_state(
+        relayed_answer_watermark_at=received_at,
+        relayed_answer_watermark_rowid=event_id,
+    )
+
+
+def events_after_relayed_answer_watermark(
+    received_at: float, after_event_id: str, *, limit: int = 100
+) -> list[tuple[str, "PortalEvent"]]:
+    """The relayed-answer confirmation consumer's own paginated scan —
+    identical query to :func:`events_after_question_watermark`, against this
+    consumer's own watermark instead. See
+    :func:`coord.portal_sync._consume_relayed_answer_confirmations`.
+    """
+    rows = sql.execute(
+        _conn(),
+        """
+        SELECT * FROM portal_events
+         WHERE received_at > ?
+            OR (received_at = ? AND event_id > ?)
+         ORDER BY received_at ASC, event_id ASC
+         LIMIT ?
+        """,
+        (received_at, received_at, after_event_id, limit),
+    ).fetchall()
+    return [(r["event_id"], _event_from_row(r)) for r in rows]
+
+
 def note_push(*, now: float | None = None) -> None:
     _update_sync_state(last_push_at=time.time() if now is None else now)
 
@@ -1754,6 +1814,18 @@ LEDGER_KIND_DRAFT_REJECTED = "draft_rejected"
 #: IS a narrative cannot be regenerated — that asymmetry is the design").
 LEDGER_KIND_OPERATOR_NOTE = "operator_note"
 
+#: #2987: the client tapped "confirm" on a relayed answer the portal showed
+#: them. A new row, not a mutation of the #2986 answer row it confirms — the
+#: ledger has no UPDATE path (see :func:`append_ledger_entry`'s docstring) —
+#: paired to the same ``question_revision`` so :func:`render_ledger_payload`
+#: can fold it into the same Q&A bucket. A CORRECTION needs no kind of its
+#: own: it arrives as an ordinary inbound ``question.answered`` event and
+#: lands as a normal (non-``relayed``) :data:`LEDGER_KIND_QUESTION_ANSWERED`
+#: row in the same bucket via the existing #2749 consumer — append-only, so
+#: both the relayed answer and the correction that supersedes it stay
+#: visible, in the order they were recorded.
+LEDGER_KIND_ANSWER_CONFIRMED = "answer_confirmed"
+
 #: Marks a ledger ``actor`` as a human at coord's CLI rather than the portal
 #: wire, so a later session can tell operator-relayed context from something
 #: the client actually wrote. See :func:`operator_actor`.
@@ -2093,6 +2165,30 @@ def _fold_status_after_answer(config: Any, submission_id: str) -> None:
         )
 
 
+def _push_relayed_answer(config: Any, submission_id: str, entry: LedgerEntry) -> None:
+    """Best-effort: queue *entry* — a #2986 relayed answer just ledgered —
+    for the portal to see, so the client can confirm or correct it (#2987).
+
+    Never raises. The ledger write above is the durable, coord-side record
+    of the fact; this is the OUTBOUND half of it, and a failure here (a
+    stale/missing config, the draft-gate policy read finding nothing to
+    read) must never make the ledger append look like it failed — same
+    posture as :func:`_fold_status_after_answer` right above, and the same
+    #2179 failure posture the rest of this bridge holds to: the answer
+    stays recorded locally either way.
+    """
+    try:
+        from coord import portal_sync  # noqa: PLC0415
+
+        portal_sync.enqueue_relayed_answer(submission_id, entry, config=config)
+    except Exception:  # noqa: BLE001 — outbound queuing is best-effort here
+        _log.warning(
+            "portal answer: could not enqueue outbound relayed_answer for %s",
+            submission_id,
+            exc_info=True,
+        )
+
+
 def _answer_question_local(
     submission_id: str,
     text: str,
@@ -2149,6 +2245,7 @@ def _answer_question_local(
         now=now,
     )
     _fold_status_after_answer(config, submission_id)
+    _push_relayed_answer(config, submission_id, entry)
     return entry
 
 
@@ -2189,6 +2286,12 @@ def answer_question(
     (:func:`coord.portal_sync._record_question_answer`) is additive, not a
     conflict: the ledger is append-only, so both rows coexist under the same
     ``question_revision`` in the order they were recorded.
+
+    Also queues the answer OUTBOUND (#2987, best-effort — see
+    :func:`_push_relayed_answer`), draft-gated like ``design_round``/
+    ``question`` so nothing customer-facing sends without operator approval,
+    so the client sees exactly what was recorded and can confirm or correct
+    it in one tap.
     """
     routed = _route_answer(
         {
@@ -2668,6 +2771,14 @@ def render_ledger_payload(submission_id: str) -> dict[str, Any]:
     ``operator_notes`` key, in ledger ``seq`` order — deliberately NOT mixed
     into ``qa`` (they answer no question) and NOT folded into ``narrative``
     (they are ledger-class facts, and the narrative is regenerable).
+
+    A relayed answer's client CONFIRMATION (#2987,
+    :data:`LEDGER_KIND_ANSWER_CONFIRMED`) folds into the same bucket as
+    ``confirmations`` — never merged into ``answers`` itself, so a renderer
+    can tell "the client said this" from "the client confirmed what we said
+    they said" without inspecting payloads. A correction needs no such
+    folding: it arrives as an ordinary (non-``relayed``) row in ``answers``
+    and both stay visible in ``seq`` order, same as any other append.
     """
     ledger = ledger_for_submission(submission_id)
     decisions = decisions_for_submission(submission_id)
@@ -2681,7 +2792,7 @@ def render_ledger_payload(submission_id: str) -> dict[str, Any]:
             operator_notes.append(entry)
         elif entry.kind == LEDGER_KIND_QUESTION_PUSHED:
             questions.setdefault(
-                entry.question_revision, {"question": entry, "answers": []}
+                entry.question_revision, {"question": entry, "answers": [], "confirmations": []}
             )
         elif entry.kind == LEDGER_KIND_QUESTION_ANSWERED:
             bucket = questions.get(entry.question_revision)
@@ -2689,6 +2800,10 @@ def render_ledger_payload(submission_id: str) -> dict[str, Any]:
                 bucket["answers"].append(entry)
             else:
                 unpaired_answers.append(entry)
+        elif entry.kind == LEDGER_KIND_ANSWER_CONFIRMED:
+            bucket = questions.get(entry.question_revision)
+            if bucket is not None:
+                bucket["confirmations"].append(entry)
 
     current_decisions = [d for d in decisions if d.is_current]
     archived_decisions = [d for d in decisions if not d.is_current]
@@ -2714,6 +2829,12 @@ def render_ledger_payload(submission_id: str) -> dict[str, Any]:
                     }
                     for a in qa["answers"]
                 ],
+                # #2987: every time the client confirmed a relayed answer for
+                # this question — empty when none has been (yet, or ever).
+                "confirmations": [
+                    {"actor": c.actor, "recorded_at": c.recorded_at}
+                    for c in qa["confirmations"]
+                ],
             }
             for revision, qa in questions.items()
         ],