fix(poll): make the poll question visible both directions (echo out, backfill in)

[omarshahine]

What Problem This Solves

Native iMessage poll balloons have no title — item.title is empty and Messages never renders it. The question you see on a native poll lives in a separate caption message whose reply_to is the poll guid (the composer's "comment or Send" field). imsg ignored this on both sides:

• Outbound: poll send --question 'X' stored X in the invisible item.title, so agent-created polls rendered as bare options with no question.
• Inbound: a native poll decoded from chat.db had question=nil, so agents saw a title-less Poll — options: ….

Why This Change Was Made

Make the poll question visible in both directions, matching native behavior, with no consumer changes required (OpenClaw already renders 📊 Poll: <question> when the field is present, and passes --question on send).

User Impact

• Outbound — poll send / poll.send RPC now send --question as a plain caption message right after the poll — associated_message_type = 0, thread_originator_guid = None, i.e. not a threaded reply, so it renders as a normal caption bubble instead of the "reply connector" a threaded reply would draw. --comment overrides the echoed text; the echo is best-effort so a caption failure never fails an already-delivered poll. Agents keep passing only --question.
• Inbound — enrichedPollEvent backfills an empty created-poll question from its caption (earliest reply-to-the-poll message), so inbound native polls surface their question. imsg-created polls with a real title are unchanged; vote enrichment untouched.

Evidence

Verified end-to-end on macOS 26 through a live v2 bridge, sending with this branch's build (swift build --product imsg).

Outbound — live send to a test group:

$ imsg poll send --chat-id 22 --question "PR#155 proof: which crustacean?" \
      --option Lobster --option Crab --option Shrimp --json
{"poll":{"kind":"created","question":"PR#155 proof: which crustacean?",
 "options":[Lobster,Crab,Shrimp]},"event":"imessage.poll.created",
 "messageGuid":"EAE66DE7-…","balloonBundleID":"…Polls"}

Visual — confirmed in the Messages UI on the receiving device: the poll shows the three options (Lobster / Crab / Shrimp), and directly beneath it the question appears as an ordinary caption bubble ("PR#155 proof: which crustacean?") — no threaded-reply connector line. (Screenshot available; can be attached to this PR.)

Structural proof (chat.db) — my sent caption is byte-for-byte the same shape as a natively-composed poll's caption, and differs from the earlier threaded-reply attempt that drew the connector:

poll_guid  origin          caption   assoc_type  thread_originator
EAE66DE7   this PR (sent)   01E1505B  0           NULL   ← clean, matches native
2E97B312   native (recv)    CCBD34D4  0           NULL   ← native reference
AC8A8E5B   native (recv)    1ECFCA87  0           NULL   ← native reference
A3DDC24F   old threaded try C615FCEF  100         A3DDC24F ← the rejected reply connector

Note: this bridge auto-populates reply_to_guid on every send (the poll itself got a reply_to although no --reply-to was passed), so both native and PR captions carry reply_to; the connector is driven by thread_originator/assoc_type=100, which the PR caption does not set — matching native exactly.

Inbound — backfill via imsg history (chat.db read, no bridge), native [recv] polls that decoded as question=None now surface their question:

[recv] [poll created] Favorite crustacean friend of a Lobster?: Lobster 🦞 / Crab 🦀 / Shrimp 🦐
[recv] [poll created] What color pill?: Red / Blue
[recv] [poll created] Pick a color: Black / White

Review follow-ups addressed (ClawSweeper P2s): CLI caption echo is now best-effort (do/catch, matching the RPC path); pollCommentText is guarded on schema.hasReplyToGUIDColumn so schemas without the column degrade to nil instead of throwing; poll-send tests record the full bridge call sequence and assert both .sendPoll and the .sendMessage caption echo. macOS + Linux CI green.

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 5, 2026, 12:52 PM ET / 16:52 UTC.

Summary
The branch sends a best-effort plain caption message after poll creation, backfills empty inbound created-poll questions from native caption rows, adds a --comment override, and updates poll tests.

Reproducibility: yes. from source and contributor proof: current main sends only the poll payload and only enriches vote rows, while the PR head sends a caption and backfills native poll questions. I did not run Messages locally in this read-only review.

Review metrics: 2 noteworthy metrics.

• Changed surface: 8 files changed, 282 additions, 21 deletions. The patch is focused on poll send/read behavior and matching tests, but it still changes live message-delivery semantics.
• Current checks: 2 successful checks. GitHub reports both macOS and linux-read-core CI passed on the latest head.

Root-cause cluster
Relationship: canonical
Canonical: #155
Summary: This PR is the canonical implementation for poll caption echo and inbound poll question backfill; the related items are documentation follow-ups or adjacent skill work.

Members:

• partial_overlap: skill: re-add poll caption/backfill/--comment docs after #155 lands #157 - It tracks re-adding skill documentation for this behavior after this PR lands, but it does not implement the behavior itself.
• adjacent_distinct: docs(skill): expand imsg agent skill with full CLI surface #154 - It updates the bundled imsg skill and intentionally removed future poll-caption claims so it can merge independently of this behavior PR.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] Merging intentionally changes poll send from one bridge call to a poll plus a best-effort follow-up caption message; if the caption send fails, users can still receive a delivered poll without the visible question.

Maintainer options:

1. Land the proven caption behavior (recommended)
   Accept the two-message poll send because the caption path is best-effort and the latest head filters inbound backfill to clean native captions.
2. Require one more UI artifact
   Ask the contributor to attach the promised Messages screenshot or a short recording if visual confirmation is required before merge.
3. Pause if extra visible sends are unacceptable
   Close or redesign the PR if maintainers do not want poll send to create a second visible message after the poll balloon.

Next step before merge

• No ClawSweeper repair lane is needed; the remaining action is maintainer acceptance of the intentional two-message poll-send behavior before merge.

Maintainer decision needed

• Question: Should imsg accept the intentional two-message poll-send behavior where the poll is delivered first and the visible caption is sent best-effort afterward?
• Rationale: The patch is technically focused and proven, but it changes outbound message-delivery semantics in a way only maintainers can accept for the CLI/RPC contract.
• Likely owner: steipete — Recent poll helper refactoring and release ownership make this the best available routing candidate for accepting the outbound behavior contract.
• Options:
  • Land the proven caption behavior (recommended): Accept the two-message behavior because the caption echo is best-effort, structurally matched to native captions, and guarded by threaded-reply regression coverage.
  • Ask for attached UI proof first: Require a screenshot or recording showing the caption bubble without a threaded connector if maintainers want more visual confidence before merge.
  • Reject follow-up message semantics: Pause or close this approach if maintainers do not want poll creation to emit an additional user-visible message.

Security
Cleared: The diff changes local Swift poll handling and tests only; it does not alter dependencies, workflows, secrets, permissions, or artifact execution paths.

Review details

Best possible solution:

Land the focused caption/backfill fix after maintainer acceptance of the two-message poll-send behavior, then use #157 for the skill-doc follow-up.

Do we have a high-confidence way to reproduce the issue?

Yes from source and contributor proof: current main sends only the poll payload and only enriches vote rows, while the PR head sends a caption and backfills native poll questions. I did not run Messages locally in this read-only review.

Is this the best way to solve the issue?

Yes, with maintainer acceptance of the delivery tradeoff. The implementation is narrow, keeps caption echo best-effort to avoid duplicate poll retries, and constrains inbound backfill to native caption-shaped rows with regression coverage.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 9ac97ab1d242.

Label changes

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body and follow-up comments provide after-fix live CLI output, chat.db structural comparison against native captions, UI confirmation, and inbound history output.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

• P2: Poll question visibility affects a bounded but user-facing native iMessage poll workflow.
• merge-risk: 🚨 message-delivery: The PR changes outbound poll sending into a poll plus follow-up caption message and changes inbound caption rows into agent-visible poll questions.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body and follow-up comments provide after-fix live CLI output, chat.db structural comparison against native captions, UI confirmation, and inbound history output.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body and follow-up comments provide after-fix live CLI output, chat.db structural comparison against native captions, UI confirmation, and inbound history output.

Evidence reviewed

What I checked:

• AGENTS.md read and applied: Repository guidance was read fully; its focus on Swift style, deterministic fixtures, and regression tests for parsing/filtering changes informed the review. (AGENTS.md:1, 9ac97ab1d242)
• Current main outbound gap: On main, poll send invokes .sendPoll and returns without any follow-up caption message, so the requested visible question behavior is not already implemented. (Sources/imsg/Commands/PollCommand.swift:95, 9ac97ab1d242)
• Current main inbound gap: On main, enrichedPollEvent exits unless the poll kind is .vote, so created polls with empty questions are not backfilled from caption rows. (Sources/IMsgCore/MessageStore+Polls.swift:9, 9ac97ab1d242)
• PR outbound behavior: The PR head captures the poll guid, sends a plain .sendMessage caption afterward, and catches caption failures so a delivered poll is not retried as a duplicate. (Sources/imsg/Commands/PollCommand.swift:113, 64ab39604bd9)
• Prior blocker fixed: The PR head now filters poll-caption backfill to matching reply_to_guid, associated_message_type = 0 when available, and thread_originator_guid IS NULL when available. (Sources/IMsgCore/MessageStore+ReplyContext.swift:58, 64ab39604bd9)
• Regression coverage: The latest tests prove a clean caption backfills the poll question and a threaded reply is ignored. (Tests/IMsgCoreTests/MessagePollTests.swift:485, 64ab39604bd9)

Likely related people:

• veteranbv: Authored the merged native poll support and readback commits that introduced the poll decoding surface this PR extends. (role: native poll feature contributor; confidence: medium; commits: 0c9d85db44f0, 20ed29c35e81, 2529aa7ad011; files: Sources/IMsgCore/MessagePolls.swift, Sources/IMsgCore/MessageStore+Polls.swift, Sources/IMsgCore/MessageStore+ReplyContext.swift)
• steipete: Recent history shows poll helper refactoring and release stewardship around the affected CLI/RPC and poll files. (role: recent poll command area contributor; confidence: medium; commits: fed89d6b4f9d, 9fe0d92b5dbf; files: Sources/imsg/Commands/PollCommand.swift, Sources/imsg/RPCServer+BridgeMessageHandlers.swift, Sources/IMsgCore/MessageStore+Polls.swift)
• omarshahine: Authored prior merged native poll voting work that touched the same command, RPC, and enrichment paths, so the author is also connected to current-main poll history beyond this PR. (role: adjacent poll contributor; confidence: medium; commits: 617d941f7b1e; files: Sources/imsg/Commands/PollCommand.swift, Sources/imsg/RPCServer+BridgeMessageHandlers.swift, Sources/IMsgCore/MessageStore+Polls.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (8 earlier review cycles)

• reviewed 2026-07-05T00:44:56.189Z sha b3e734a :: needs real behavior proof before merge. :: [P2] Keep the CLI echo best-effort | [P2] Update the poll-send tests for two bridge calls
• reviewed 2026-07-05T01:22:26.328Z sha a9071de :: needs real behavior proof before merge. :: [P2] Keep the CLI caption send best-effort | [P2] Update poll-send tests for the second bridge call
• reviewed 2026-07-05T01:41:29.802Z sha f5de557 :: needs real behavior proof before merge. :: [P2] Keep the CLI caption send best-effort | [P2] Update poll-send tests for the second bridge call
• reviewed 2026-07-05T01:46:08.112Z sha f5de557 :: needs real behavior proof before merge. :: [P2] Keep the CLI caption send best-effort | [P2] Update poll-send tests for the second bridge call
• reviewed 2026-07-05T15:55:13.239Z sha 2847415 :: needs real behavior proof before merge. :: [P2] Keep the CLI caption send best-effort | [P2] Update poll-send tests for the second bridge call | [P2] Guard caption lookup when reply_to_guid is absent
• reviewed 2026-07-05T16:07:02.482Z sha 36e1ece :: needs maintainer review before merge. :: none
• reviewed 2026-07-05T16:11:36.188Z sha 36e1ece :: needs changes before merge. :: [P2] Filter out threaded replies when backfilling captions
• reviewed 2026-07-05T16:48:13.465Z sha 64ab396 :: needs maintainer review before merge. :: none

[omarshahine]

@clawsweeper re-review

Addressed all three P2 findings and added real behavior proof:

• CLI caption echo is now best-effort (do/catch, matching the RPC path) — a caption failure no longer exits nonzero after the poll delivered (36e1ece).
• pollCommentText is guarded on schema.hasReplyToGUIDColumn; a table without the column degrades to nil instead of throwing (8b8f451).
• Poll-send tests now record the full bridge call sequence and assert both .sendPoll and the .sendMessage caption echo (8b8f451).

Proof (PR body updated): live imsg poll send through a v2 bridge on macOS 26 using this branch's build; chat.db shows the sent caption is structurally identical to a natively-composed poll's caption (assoc_type=0, thread_originator=None) and differs from the old threaded-reply attempt (assoc_type=100, thread_originator set). Inbound native [recv] polls now surface their backfilled questions via imsg history. macOS + Linux CI green.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[omarshahine]

Fixed the P1 (64ab396): pollCommentText now filters to clean native captions (associated_message_type = 0 AND thread_originator_guid IS NULL, schema-aware since both columns are optional), so a threaded inline reply to the poll can no longer be mistaken for the question. Added regression coverage: messageStorePollBackfillsQuestionFromCleanCaption (clean caption still backfills) and messageStorePollBackfillIgnoresThreadedReply (threaded reply ignored, question stays empty). macOS + Linux green.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.