code-coordinator 0.5.289__tar.gz → 0.5.291__tar.gz

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/.github/workflows/test.yml

@@ -31,6 +31,17 @@ jobs:
       # testpaths=["tests"]) was the one accidental gap. (ms-51 — Playwright,
       # never .py either — left this repo entirely with the webapp, #2009.)
       - run: pytest --ignore=tests/acceptance
+      # #2897: the Rust drift gate `tests/test_generated_rust_fixture.py`
+      # no longer byte-compares the committed `tui/src/app/types/generated.rs`
+      # (see docs/ADR_COORD_TUI_CI.md and the header comment further down
+      # this file) — this explicit step stands in for that comparison while
+      # `tui/` still lives here. `$COORD_TUI_SRC=.` names this checkout as
+      # the coord-tui root (`RUST_OUTPUT_RELPATH` keeps the `tui/` prefix for
+      # exactly this reason). One matrix leg only: the generator's output
+      # depends on `coord.serve_app.openapi_spec()`, not the Python version.
+      - name: python scripts/codegen.py --rust --check
+        if: matrix.python-version == '3.12'
+        run: COORD_TUI_SRC=. python scripts/codegen.py --rust --check
       # #2180: the cli-pytest sealed route (acceptance.drivers routes
       # "coord/**" -> cli-pytest -> tests/acceptance/ms-37) run through the
       # #2164 CI wrapper instead of a raw `pytest tests/acceptance` call, so
@@ -310,16 +321,31 @@ jobs:
   # for it to run against, and a job that installs Node to build nothing is
   # how the previous `acceptance`-on-every-push waste (#2389) started.
   #
-  # #1941: `scripts/codegen.py` also generates coord-tui's RUST wire types
-  # (`--rust`), and unlike the TS half above, `tui/` never left this repo —
-  # so that drift gate needs no separate job or `coord-web` checkout at all.
-  # It rides the ordinary `pytest --ignore=tests/acceptance` runs above, as
-  # `tests/test_generated_rust_fixture.py::
-  # test_committed_generated_rs_matches_generator_output`, the same way the
-  # TS-side `tests/test_generated_types_fixture.py` already rides them for
-  # the half of that check this repo can still make (the generator runs and
-  # covers every schema; the coord-web byte-comparison itself is that repo's
-  # own CI, per the paragraph above).
+  # #1941/#2897: `scripts/codegen.py` also generates coord-tui's RUST wire
+  # types (`--rust`). #2897 gave that half the SAME cross-repo shape as the
+  # TS half above (`--out PATH` / `$COORD_TUI_SRC`, no fallback default,
+  # docs/ADR_COORD_TUI_CI.md) — but `tui/` has not actually moved out of
+  # this repo yet, so unlike the TS byte-comparison (which is now
+  # exclusively `coord-web`'s CI job), the Rust byte-comparison has nowhere
+  # else to run yet and stays HERE, as an explicit step below rather than a
+  # pytest test:
+  #
+  #     COORD_TUI_SRC=. python scripts/codegen.py --rust --check
+  #
+  # `tests/test_generated_rust_fixture.py` itself is narrowed to what one
+  # checkout can prove — the generator runs and covers every schema — same
+  # as `tests/test_generated_types_fixture.py`; it no longer byte-compares
+  # the committed `tui/src/app/types/generated.rs`. The day coord-tui gets
+  # its own checkout + CI, delete the step below (its replacement lives in
+  # that CI, installing `code-coordinator[server]` from PyPI exactly as
+  # `coord-web`'s does) — no pytest file to un-narrow.
+  #
+  # The consumer-side INTEGER-backed-bool text-scraping guard
+  # (`coord/board_bool_guard.py`) that used to also read Rust source text
+  # here is RETIRED as of #2897, not moved — see docs/ADR_COORD_TUI_CI.md:
+  # #2895 (Phase 1 of #2894) deleted coord-tui's last direct SQL reader, so
+  # `tests/test_board_schema.py`'s DTO-level assertions are now the sole
+  # guard against that class.
 
   # #2886: a real Postgres 16 service, so `coord/sql.py`'s Postgres branches
   # (paramstyle translation, upsert idioms, `information_schema`

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/PKG-INFO

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

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

@@ -39,7 +39,6 @@ coord/approved_work.py
 coord/audit.py
 coord/auto_loop.py
 coord/block_log.py
-coord/board_bool_guard.py
 coord/board_schema.py
 coord/board_service.py
 coord/board_wire.py
@@ -296,6 +295,7 @@ deploy/coord-web-dist-build.timer
 deploy/coord-web-rollback.sh
 deploy/coord-web.service
 deploy/node-shim.sh
+docs/ADR_COORD_TUI_CI.md
 docs/ADR_COORD_WEB_ACCEPTANCE_SUITE.md
 docs/ADR_COORD_WEB_CI.md
 docs/ADR_COORD_WEB_DIST.md

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/code_coordinator.egg-info/scm_file_list.json

@@ -33,7 +33,6 @@
     "coord/audit.py",
     "coord/auto_loop.py",
     "coord/block_log.py",
-    "coord/board_bool_guard.py",
     "coord/board_schema.py",
     "coord/board_service.py",
     "coord/board_wire.py",
@@ -288,6 +287,7 @@
     "deploy/coord-web-rollback.sh",
     "deploy/coord-web.service",
     "deploy/node-shim.sh",
+    "docs/ADR_COORD_TUI_CI.md",
     "docs/ADR_COORD_WEB_ACCEPTANCE_SUITE.md",
     "docs/ADR_COORD_WEB_CI.md",
     "docs/ADR_COORD_WEB_DIST.md",

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.289",
+  "tag": "0.5.291",
   "distance": 0,
-  "node": "ga013df1e45f8ba2ece0ba26be923f8a107dbe654",
+  "node": "g408957bf4d2de2370d4e9df055a80c1680a697a2",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-29"

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/coord/agent.py

@@ -4139,6 +4139,82 @@ and report back what you asked/proposed/filed/queued/linked (and any gap) \
 when done.\
 """
 
+# #2867: the ATTENDED posture. Appended to (never merged into)
+# DECOMPOSITION_CHAT_SYSTEM_PROMPT by `coord portal decompose-chat
+# --interactive` only — the headless dispatch
+# (`default_worker_command`'s `spec.type == "decomposition-chat"` branch)
+# must keep receiving the base prompt byte-for-byte, because it genuinely
+# has nobody to ask and its one-turn fire-and-forget shape is correct there.
+#
+# WHY this exists at all: #2750 shipped `--interactive` reusing the headless
+# prompt verbatim, so the attended session was written for an agent with
+# nobody to ask ("THIS iteration ends in EXACTLY ONE of three terminal
+# moves", each a command to run) and duly read the ledger, chose ASK, and
+# ran `enqueue-question` in the SAME turn — its whole output to the human
+# sitting there was a report of what it had already done. On a paid client
+# engagement where a round-trip takes days, that spent a day on questions
+# the operator may already have had answers to. The base prompt's
+# "summarize your plan before writing anything" was not enough: nothing
+# made it a STOP, and without a turn boundary a compliant session still
+# writes.
+DECOMPOSITION_CHAT_ATTENDED_ADDENDUM = """\
+
+── ATTENDED SESSION (`--interactive`) — OVERRIDES THE ABOVE ──
+
+An operator is sitting at this terminal RIGHT NOW, watching you type. That \
+changes the shape of this iteration, and where this section conflicts with \
+anything above, THIS SECTION WINS.
+
+**YOUR FIRST TURN WRITES NOTHING.** Not `coord portal enqueue-question`, not \
+`coord portal enqueue-status`, not `coord portal decision propose/reject/\
+supersede`, not `coord issue create`, not `coord milestone create`, not \
+`coord drive-queue add`, not `coord portal link`, not `coord issue edit`. \
+Read-only commands (`coord portal ledger`, `gh issue view`, reading files) \
+are fine and expected. The "EXACTLY ONE of three terminal moves" rule above \
+still decides WHICH exit this iteration takes — it just does not get to \
+happen until the operator has answered you.
+
+So your first turn is:
+
+1. State your READ — the MODE line verbatim (as always), then what RUNNING \
+CONTEXT already tells you, explicitly including any operator-supplied \
+background recorded there.
+2. State your PROPOSED EXIT — which of Ask / Propose / Decompose you intend, \
+the exact command(s) you would run (question text, decision text, issue \
+titles), and WHY that exit and not the other two.
+3. State what you are ASSUMING or MISSING — above all, anything you were \
+about to ask the CLIENT that the OPERATOR may simply know. The operator may \
+have spoken to the client since the last iteration; a client round-trip \
+costs days and an operator answer costs one line, so ask the human in front \
+of you FIRST.
+4. END YOUR TURN AND WAIT. Do not narrate a plan and then execute it in the \
+same turn — the turn boundary IS the confirmation.
+
+Then act on what the operator says: carry out the exit as proposed, or the \
+revised one they steer you to. If they confirm with no changes, run the \
+commands exactly as you stated them and report back. If they redirect you \
+into a different exit, take that one — it is still exactly one terminal \
+move per iteration.
+
+**Recording what the operator tells you.** Background the operator relays \
+("I spoke to her — it's just the two of them, and the calendar is a \
+nice-to-have") is durable, ledger-class context that every FUTURE session on \
+every machine should see. It is not a decision, so do NOT push it through \
+`coord portal decision propose`. Record it verbatim with:
+
+    coord portal note <submission_id> "<what the operator told you>"
+
+This is an ADDITIONAL write path you are permitted, on top of the ones the \
+Rules section above enumerates — and, being a write, it is also subject to \
+the first-turn rule: offer it, then record it once the operator agrees. \
+OFFER IT PROACTIVELY: the operator should not have to know this command \
+exists. Any time the operator gives you a substantive fact about the \
+client, the users, or the scope, say back what you would record and ask \
+whether to record it. Keep the wording theirs, not your paraphrase — the \
+ledger is verbatim by design, and the narrative (which is regenerable) is \
+where summarizing belongs.\
+"""
+
 # Deny list applied to decomposition-chat workers (#2533; extended #2750
 # IL-4 for the ask/propose/decompose intake loop). Unlike milestone-chat,
 # this type's WHOLE job is to write (issue create / issue edit / milestone

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/coord/board_schema.py

@@ -287,10 +287,12 @@ BOARD_PROJECTIONS: dict[str, type] = {
 #: therefore ship as ``0``/``1``.  Their DTO fields are annotated ``int`` on
 #: purpose; ``tests/test_board_schema.py`` asserts the generated JSON Schema
 #: types them ``integer`` and never ``boolean``, so the wire shape survives a
-#: storage-engine swap (Postgres would make these real ``BOOLEAN``s).  This is
-#: the DTO-level counterpart of ``coord/board_bool_guard.py``'s consumer-side
-#: check against the real Rust wire structs (``tui/src/app/types.rs`` and,
-#: since #1941, its generated ``types/generated.rs`` sibling).
+#: storage-engine swap (Postgres would make these real ``BOOLEAN``s).  This
+#: WAS the DTO-level counterpart of ``coord/board_bool_guard.py``'s consumer-
+#: side check against the real Rust wire structs (``tui/src/app/types.rs``
+#: and its generated ``types/generated.rs`` sibling, #1941); that
+#: text-scraping check is retired as of #2897 (docs/ADR_COORD_TUI_CI.md) —
+#: this assertion is now the sole remaining guard.
 INTEGER_BACKED_BOOLEANS: frozenset[str] = frozenset(
     {"is_interactive", "review_scoped", "hold_after", "no_acceptance"}
 )

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/coord/board_wire.py

@@ -113,7 +113,8 @@ TRUNCATION_NOTICE = "\n… [truncated on the /board wire — full text: detail e
 # two: `coord/**` and `tui/**`). Lines carrying it survive the body cut; see
 # `_machine_readable_residue`. Kept in sync with the Rust side by
 # tests/test_board_wire.py::test_allowed_glob_marker_matches_the_rust_parser,
-# the same cross-language guard posture as coord/board_bool_guard.py.
+# the same cross-language-guard posture the now-retired coord/board_bool_
+# guard.py used (#2897, docs/ADR_COORD_TUI_CI.md).
 #
 # Measured cost of the retention: ZERO on today's live board — 0 of 781
 # issue bodies carry the marker (the house `## Files` convention is a bare

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/coord/commands/portal.py

@@ -596,6 +596,7 @@ def _run_decompose_chat_interactive(
 
     from coord.agent import (  # noqa: PLC0415
         AssignmentSpec as _AssignmentSpecDc,
+        DECOMPOSITION_CHAT_ATTENDED_ADDENDUM,
         DECOMPOSITION_CHAT_DENY_COMMANDS,
         DECOMPOSITION_CHAT_SYSTEM_PROMPT,
         build_deny_prompt,
@@ -664,7 +665,8 @@ def _run_decompose_chat_interactive(
     if _board_service.resolve() is not None:
         click.secho(
             "note: this machine is a thin client — `coord portal decision`/"
-            "`ledger`/`link` route through the daemon (#2751), but `coord "
+            "`ledger`/`link`/`note` route through the daemon (#2751/#2867), "
+            "but `coord "
             "portal enqueue-question`/`enqueue-status` (the Ask move) do "
             "not yet and will refuse loudly if this iteration needs them. "
             "ssh to the daemon host for that case (#2750's own stated "
@@ -699,7 +701,9 @@ def _run_decompose_chat_interactive(
         f"Intake session for portal submission {submission_id} "
         f"(MODE: {mode_word} — {discuss_reason}): read the full context at "
         f"{brief_path} (submission fields, repo topology, and the running-"
-        "context ledger so far) and let's work through it."
+        "context ledger so far) and let's work through it. This is an "
+        "ATTENDED session: state your read and your PROPOSED exit, then stop "
+        "and wait for me — write nothing until I answer (#2867)."
     )
 
     spec = _AssignmentSpecDc(
@@ -719,15 +723,22 @@ def _run_decompose_chat_interactive(
     # internal branch table has no `"decomposition-chat"` case, so leaving
     # it implicit would silently fall through to the generic work-shaped
     # branch (full WORKER_SYSTEM_PROMPT + Edit/Write/Monitor), which is
-    # wrong for a no-worktree chat type. Passing these explicitly keeps
-    # this session byte-identical, on the system prompt, to the headless
-    # dispatch path (`coord.agent.default_worker_command`'s own
-    # `spec.type == "decomposition-chat"` branch).
+    # wrong for a no-worktree chat type.
+    #
+    # #2867: the attended addendum is appended HERE and only here — the
+    # headless dispatch path (`coord.agent.default_worker_command`'s own
+    # `spec.type == "decomposition-chat"` branch) keeps the base prompt
+    # byte-for-byte, so its one-turn fire-and-forget behaviour is unchanged.
+    # This session, by contrast, has a human in the pane: the addendum makes
+    # its first turn confirm-then-write (#2742's absorbed half, which #2750
+    # only ever wired into mode SELECTION, never into the posture itself).
     argv = provider.build_command(
         spec,
         resolved_model=resolved_model,
-        system_prompt=DECOMPOSITION_CHAT_SYSTEM_PROMPT + build_deny_prompt(
-            DECOMPOSITION_CHAT_DENY_COMMANDS
+        system_prompt=(
+            DECOMPOSITION_CHAT_SYSTEM_PROMPT
+            + DECOMPOSITION_CHAT_ATTENDED_ADDENDUM
+            + build_deny_prompt(DECOMPOSITION_CHAT_DENY_COMMANDS)
         ),
         allowed_tools="Read,Bash",
     )
@@ -1805,6 +1816,16 @@ def _render_ledger_text(payload: dict) -> str:
             f"{a['text']}  (by {a['actor'] or 'customer'})"
         )
 
+    # #2867: verbatim, attributed, in ledger seq order — its own heading so
+    # a later session can tell operator-relayed background from something
+    # the client actually wrote on the portal. `.get` (not `[...]`) because
+    # a thin client may be talking to a daemon that predates this key.
+    notes = payload.get("operator_notes") or []
+    if notes:
+        lines += ["", "## Operator notes"]
+        for n in notes:
+            lines.append(f"- [{n['seq']}] {n['text']}  (by {n['actor'] or 'operator'})")
+
     lines += ["", "## Decisions"]
     current = payload["decisions"]
     if not current:
@@ -1861,6 +1882,39 @@ def portal_ledger(submission_id: str, as_json: bool) -> None:
     click.echo(_render_ledger_text(payload))
 
 
+@portal_group.command("note")
+@click.argument("submission_id")
+@click.argument("text")
+def portal_note(submission_id: str, text: str) -> None:
+    """Record operator-supplied background about SUBMISSION_ID (#2867).
+
+    The ledger layer that holds what the OPERATOR knows — "spoke to the
+    client: household of two, no logins needed" — which before this had
+    nowhere durable to live and died with the tmux pane it was typed into.
+    Stored verbatim on the ledger, attributed to you, and rendered into
+    every future session's RUNNING CONTEXT on any machine.
+
+    Deliberately NOT `coord portal decision propose`: a relayed fact is not
+    a judgment call, has no proposed/confirmed lifecycle, and does not
+    belong in the decision archive.
+
+    Like `decision` and `link` (#2751) this is not thin-client-refused — it
+    routes through the daemon's `/portal-note` seam when `board_service` is
+    configured, so it works from wherever the operator happens to be.
+    """
+    from coord import portal_store  # noqa: PLC0415
+
+    try:
+        entry = portal_store.append_operator_note(submission_id, text, actor=_actor())
+    except ValueError as exc:
+        click.secho(f"error: {exc}", fg="red")
+        raise SystemExit(2) from exc
+    click.secho(
+        f"noted: {submission_id} #{entry.seq} (by {entry.actor}) — {entry.text}",
+        fg="green",
+    )
+
+
 @portal_group.group("decision")
 def portal_decision_group() -> None:
     """Propose / confirm / reject / supersede a decision (#2749).

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/coord/decomposition_chat.py

@@ -278,6 +278,11 @@ def render_running_context_section(payload: dict[str, Any]) -> str:
     ones carrying why), and the current narrative. This is what lets a
     fresh iteration pick up exactly where the last one left off with no
     memory of the prior session (#2750's "the loop").
+
+    Since #2867 it also renders the ledger's operator-note layer — what a
+    human relayed out of band ("I spoke to her; it's just the two of them")
+    — attributed as operator-supplied so a session can tell it from
+    something the client wrote on the portal itself.
     """
     lines: list[str] = ["RUNNING CONTEXT (from the portal ledger):", "", "Q&A so far:"]
     qa = payload.get("qa") or []
@@ -301,6 +306,22 @@ def render_running_context_section(payload: dict[str, Any]) -> str:
             f"{a.get('text', '')}  (by {a.get('actor') or 'customer'})"
         )
 
+    # #2867: verbatim and attributed, so a session on a different machine
+    # with no shared transcript still sees what the operator was told out of
+    # band. Placed ahead of decisions because it is INPUT to them.
+    notes = payload.get("operator_notes") or []
+    if notes:
+        lines.append("")
+        lines.append(
+            "Operator-supplied background (relayed by a human, NOT written by "
+            "the client on the portal — treat as fact, do not re-ask it):"
+        )
+        for n in notes:
+            lines.append(
+                f"  - [{n.get('seq')}] {n.get('text')}  "
+                f"(by {n.get('actor') or 'operator'})"
+            )
+
     lines.append("")
     lines.append("Current decisions (proposed/confirmed — treat as live guidance):")
     current = payload.get("decisions") or []

{code_coordinator-0.5.289 → code_coordinator-0.5.291}/coord/portal_store.py

@@ -1739,6 +1739,44 @@ LEDGER_KIND_DRAFT_EDITED = "draft_edited"
 LEDGER_KIND_DRAFT_APPROVED = "draft_approved"
 LEDGER_KIND_DRAFT_REJECTED = "draft_rejected"
 
+#: #2867: background the OPERATOR relays — "I spoke to her; it's just the two
+#: of them and the calendar is a nice-to-have." Ledger-class, not
+#: decision-class: it is a FACT someone told the operator, not a judgment
+#: call with a proposed/confirmed lifecycle, so forcing it through
+#: `coord portal decision propose` would both lose the raw statement and
+#: pollute the decision archive. Still coord-observed in the sense this
+#: section's ownership note means — a human typed it at coord's own CLI,
+#: which is not "an agent's say-so about a fact it does not solely observe".
+#: Stored VERBATIM and never folded into the narrative (#2746: "a ledger that
+#: IS a narrative cannot be regenerated — that asymmetry is the design").
+LEDGER_KIND_OPERATOR_NOTE = "operator_note"
+
+#: 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`.
+OPERATOR_ACTOR_PREFIX = "operator:"
+
+
+def operator_actor(name: str = "") -> str:
+    """The ``actor`` string for an operator-authored ledger row.
+
+    ``"jane"`` → ``"operator:jane"``; empty → the bare ``"operator"``. Already
+    prefixed values pass through unchanged, so routing a note through the
+    daemon (which re-normalizes) can't produce ``operator:operator:jane``.
+    """
+    n = (name or "").strip()
+    if not n:
+        return "operator"
+    return n if n.startswith(OPERATOR_ACTOR_PREFIX) else f"{OPERATOR_ACTOR_PREFIX}{n}"
+
+
+def is_operator_actor(actor: str) -> bool:
+    """True when *actor* names a human at coord's CLI (:func:`operator_actor`'s
+    output) rather than the customer or an agent — what the briefing renders
+    attribute notes with."""
+    a = (actor or "").strip()
+    return a == "operator" or a.startswith(OPERATOR_ACTOR_PREFIX)
+
 
 @dataclass(frozen=True)
 class LedgerEntry:
@@ -1870,6 +1908,79 @@ def ledger_for_submission(submission_id: str) -> list[LedgerEntry]:
     return [_ledger_from_row(r) for r in rows]
 
 
+def operator_notes_for_submission(submission_id: str) -> list[LedgerEntry]:
+    """*submission_id*'s operator notes (#2867), oldest first — the ledger
+    rows a human typed, filtered out of :func:`ledger_for_submission`'s full
+    history by kind."""
+    return [
+        e
+        for e in ledger_for_submission(submission_id)
+        if e.kind == LEDGER_KIND_OPERATOR_NOTE
+    ]
+
+
+def _append_operator_note_local(
+    submission_id: str, text: str, *, actor: str = "", now: float | None = None
+) -> LedgerEntry:
+    """Write half of :func:`append_operator_note` — runs on the daemon host
+    (either directly, or via ``/portal-note`` on behalf of a thin client).
+
+    Validates the submission EXISTS here rather than in the CLI: on a thin
+    client the local ``portal_submissions`` table is empty by construction
+    (#2336), so a caller-side check would reject every id. Doing it here
+    means the "unknown submission" error is raised where the real table
+    lives, whichever machine the operator typed the command on.
+    """
+    if not submission_id or not submission_id.strip():
+        raise ValueError("operator note needs a submission_id")
+    if not text or not text.strip():
+        raise ValueError("operator note needs non-empty text")
+    if get_submission(submission_id) is None:
+        raise ValueError(
+            f"unknown submission {submission_id!r} — no portal submission with "
+            "that id (check `coord portal status` for the current ids)"
+        )
+    return append_ledger_entry(
+        submission_id,
+        LEDGER_KIND_OPERATOR_NOTE,
+        text=text.strip(),
+        actor=operator_actor(actor),
+        now=now,
+    )
+
+
+def _route_note(payload: dict[str, Any]) -> dict[str, Any] | None:
+    """POST *payload* to the daemon's ``/portal-note`` seam, or ``None`` if
+    this process IS the daemon host — the note-shaped twin of
+    :func:`_route_decision`, and daemon-routed for exactly the same reason
+    (#2751): the operator may be sitting at any machine in the fleet, and a
+    note written into a thin client's own empty DB would be silently lost.
+    """
+    from coord import board_service  # noqa: PLC0415
+
+    svc = board_service.resolve()
+    return board_service.route_write(svc, "/portal-note", payload)
+
+
+def append_operator_note(
+    submission_id: str, text: str, *, actor: str = "", now: float | None = None
+) -> LedgerEntry:
+    """Append one operator-supplied background fact to *submission_id*'s
+    ledger (#2867) — routed to the daemon when ``board_service`` is
+    configured, else written locally.
+
+    Raises :class:`ValueError` for an unknown submission, empty text, or a
+    missing id. The stored text is VERBATIM (stripped of surrounding
+    whitespace only) and is never rewritten into the narrative.
+    """
+    routed = _route_note(
+        {"submission_id": submission_id, "text": text, "actor": actor}
+    )
+    if routed is not None:
+        return _ledger_from_row(routed["entry"])
+    return _append_operator_note_local(submission_id, text, actor=actor, now=now)
+
+
 # ── layer 2: decisions (agent-authored, operator-confirmed) ─────────────────
 
 DECISION_PROPOSED = "proposed"
@@ -2208,6 +2319,11 @@ def render_ledger_payload(submission_id: str) -> dict[str, Any]:
     :func:`coord.portal_sync._record_question_answer` never drops one just
     because it can't be paired) lands in ``unpaired_answers`` instead of
     being silently lost.
+
+    Operator notes (#2867) come back verbatim under their own
+    ``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).
     """
     ledger = ledger_for_submission(submission_id)
     decisions = decisions_for_submission(submission_id)
@@ -2215,8 +2331,11 @@ def render_ledger_payload(submission_id: str) -> dict[str, Any]:
 
     questions: dict[int | None, dict[str, Any]] = {}
     unpaired_answers: list[LedgerEntry] = []
+    operator_notes: list[LedgerEntry] = []
     for entry in ledger:
-        if entry.kind == LEDGER_KIND_QUESTION_PUSHED:
+        if entry.kind == LEDGER_KIND_OPERATOR_NOTE:
+            operator_notes.append(entry)
+        elif entry.kind == LEDGER_KIND_QUESTION_PUSHED:
             questions.setdefault(
                 entry.question_revision, {"question": entry, "answers": []}
             )
@@ -2252,6 +2371,19 @@ def render_ledger_payload(submission_id: str) -> dict[str, Any]:
             }
             for a in unpaired_answers
         ],
+        # #2867: verbatim, in ledger `seq` order (`ledger_for_submission` is
+        # seq-ordered and this list preserves that), carrying the operator
+        # `actor` so every renderer can attribute them rather than letting
+        # them read as something the client said.
+        "operator_notes": [
+            {
+                "seq": n.seq,
+                "text": n.text,
+                "actor": n.actor,
+                "recorded_at": n.recorded_at,
+            }
+            for n in operator_notes
+        ],
         "decisions": [
             {
                 "seq": d.seq,