feat(board): agent board RPCs, roster summary and board events (RIG-5172)

[rigel-mintaka]

This PR is part of a stack containing 2 PRs:

1. main
2. feat(mirror): mirror asks and topics to forge issues and PRs (RIG-5181) #2275
3. "feat(board): agent board RPCs, roster summary and board events (RIG-5172)" (this PR)

Summary

Status board T4: the read RPC, the agent write path, roster summaries, and the live board event.

• CommsService.ListAgentBoards lists whole boards for agents the caller can see. It supports filters (query, ref, task state, agent_handles, waiting_on_operator), clamps to 100 agents, and returns INVALID_ARGUMENT for out-of-range or NUL-bearing filters. Reads run in one REPEATABLE READ snapshot (SearchAndReadAgentBoards).
• Agents write only through the relay update_board arm (AgentCommsCall). There is no public UpdateAgentBoard RPC. Writes are validated against the exported store.MaxBoard* limits before allocation. waiting.ref and blocks are canonicalized through refs.Parse.
• The roster carries a board summary per agent: focus, open/blocked counts, waiting_on_operator, AWAITING_ENQUEUE count and staleness. A malformed board omits only that agent's summary.
• AgentBoardChanged publishes on the comms bus after every committed non-empty patch. The event board holds authored fields only: no refs, untracked refs, stale flag or asks.
• When stored task data fails to decode, the authored board is still served. Derivation is skipped, and the error is logged.
• ListAgentBoards is classified authenticatedOpen in admin_gate.go.

Deviations and deferrals

• No Hub.PublishBoard. The event is published directly on the comms bus from UpdateBoardAsAccount. The hub has no board-specific logic, so a hub publisher would only forward the call.
• Forges.LinearTeams is nil. T12 (RIG-5180) seeds it from COMPASS_FORGE_LINEAR_TEAMS.
• Asks stay unset. T5 adds board asks.
• Ask mirror re-drive is T13 (RIG-5181, feat(mirror): mirror asks and topics to forge issues and PRs (RIG-5181) #2275).
• Roster/list derivation batching is RIG-5336.

Tests

• Unit: board, comms, runnerhub, auth, store, server.
• pgtest: comms suite (incl. board, roster, relay comms) and store Board.
• golangci-lint plain and --build-tags pgtest: 0 issues. compass-go:nilaway clean.
• Gates: sqlc-drift, inline-sql-gate, sql-migration-gate, compass-proto:ci/lint/gen-fence, rumdl.
• Red checks (mutate, see fail, restore): auth classification, zero-task boards in search, authored-only event, halt plus clear_halt conflict, boardVisible, task-state mapping, the jsonb_typeof waiting guard, and malformed waiting staying out of list and roster.

Review: 10 rounds; R10 on c4f0f066 had no high or medium findings.

Refs RIG-5172

Ledger-impact: none

[linear-code]

RIG-5172

[rigel-mintaka]

Review result

Head reviewed: R10 on c4f0f066, then three no-behavior changes before submit:

• spec: added the update_board write contract (the R10 low finding);
• nilaway: boardAuthoredToWire returns a struct, so the board is provably non-nil on a decode error;
• rebased onto feat(mirror): mirror asks and topics to forge issues and PRs (RIG-5181) #2275 (T13), resolving serve.go (both setters kept) and regenerating proto.

High/medium: 0 open. Low: emptyBoardPatch duplication dismissed (two small call sites, different shapes); spec gap fixed.

Dismissed with reason across rounds: caller-set automatic (D4, runtime owns it), mirror re-drive (T13), event ordering (D9, clients re-read), Hub.PublishBoard (see body), LinearTeams nil (T12/RIG-5180), batching (RIG-5336), asks (T5).

[github-actions]

Compass engineering docs preview: https://compass-server-rig-5172-boar.compass-eng-docs.pages.dev

Deployed from compass-server/rig-5172-board-rpc at 9e017e7.

Changed pages:

• docs/specs/product/compass.md

[rigel-mintaka]

Review result (head 39d899e)

R11 at 6d709f36 covered the commit after the nilaway fix, the new spec requirement, the rebase onto #2275, and the proto comment. Result: high 0, medium 0, low 1.

• low (accepted, fixed in 39d899e9): the spec said a set "" replaces any task field, but validateTask rejects an empty title. The wording now says "" clears note or primary_ref, and title is never empty. This is a docs-only change, rumdl clean.

No high or medium findings are open.

[rigel-mintaka]

Rebase note (head 4fee89a)

Rebased onto #2275 ba41f2b9 (comms review fixes). No conflicts.

• Interdiff: the T4 change (de6732a1..39d899e9 vs ba41f2b9..4fee89ac) is identical apart from hunk offsets. The R11 review at 39d899e9 still covers it.
• Local gates on 4fee89ac: build; unit tests for comms, board, store, mirror and server; nilaway; golangci-lint plain and pgtest (0 issues); pgtest comms Board|Roster|Mirror (56 pass) and store/mirror/server Board|Roster|Mirror|Drive (97 pass).

[rigel-mintaka]

Rebase onto #2275 cf1f2969 + review round 12 on head 913250b0

#2275 was rebased onto main 52c78ef0, so this PR is rebased onto its new head, cf1f2969.

• T4 diff unchanged: ba41f2b9..4fee89ac and cf1f2969..2bce197f are identical once index/@@ lines are stripped, so round 11 still covers them.
• New commit 913250b0: main added a line to Serve, and T4's one setter call pushed it to 121 lines, one over funlen. The commit folds SetForgeHost and SetBoardForges into setCommsForges(c, cfg) and removes boardForges. The values are the same; only the call shape changed.

Round	Reviewer	Findings	Status
12	single reviewer on 913250b0	0 high, 0 medium, 0 low	clean

Gates on 913250b0:

• go build passes.
• Unit tests pass for comms, board, store, mirror and server.
• nilaway is clean.
• golangci-lint finds 0 issues with the default tags and with pgtest (before the fix it reported the funlen failure).
• pgtests Board|Roster|Mirror|Drive: 240 PASS, 0 FAIL, 0 SKIP (run on 2bce197f; 913250b0 differs only by the helper extraction).
• moon ci on cf1f296..913250b: only the known local jj-workspace failures (app-bundle, compass-ui:test, design-ledger, font-coverage, orion-ref, sea-ref).

[rigel-mintaka]

CI on 913250b0

microvm (and therefore rollup) is red because of an upstream network drop, not this diff. go test could not download the lz4 module from proxy.golang.org (stream error ... INTERNAL_ERROR; received from peer), so cmd/compass-guestd and internal/guestd failed package setup. The other 47 packages passed. Filed as RIG-5426. Per policy, there is no rerun; the check stays red until someone with authority reruns it or RIG-5426 lands.

All other checks pass: 9 pass, 6 skipping.

[rigel-mintaka]

Rebase note: 9e017e77

Rebased with the board line onto main 309cd3fa; the new parent is #2275 60031ae2. No conflicts. My three commits' interdiff, cf1f2969..913250b0 against 60031ae2..9e017e77 with index/@@ lines stripped, is identical (4118 lines). Review round 12 at 913250b0 still covers this diff. The new head re-runs microvm; its last failure was an external proxy.golang.org reset (RIG-5426).