@mapier/imsg-sdk 0.2.0 → 0.2.2

package/docs/host-mac-control.md

@@ -0,0 +1,188 @@
+# Host-Mac control — remote ops for the iMessage gateway Mac
+
+How we remotely control the Mac that sends/receives iMessages for the Mapi agent.
+Written generically as "the host Mac"; current concrete values below.
+
+## Current host
+
+| Field | Value |
+|---|---|
+| Machine | Haoxiang's MacBook Air, macOS 26.5.1 |
+| Tailnet IP | `100.64.126.62` |
+| User | `mark` |
+| Repo path | `~/mapier/imsg-agent` |
+| tmux session | `mapi` (window 0 = shell, window `agent` = running agent) |
+| Agent's iMessage number | `+16282640380` |
+| Test phone 1 | `+17738867338` (chat 3996) |
+| Test phone 2 | `+15105426028` (chat 22) |
+| Test phone 3 | `+13129001215` — for group add/remove/leave legs (the platform blocks `removeParticipant`/`leaveGroup` below 3 other members, so smokes need a third handle to build a big-enough disposable group) |
+
+## 1. Access path
+
+- Tailscale tailnet connects dev Mac ↔ host Mac. If status shows "stopped": `tailscale up`.
+- SSH with key auth:
+
+```bash
+ssh -o IdentitiesOnly=yes -i ~/.ssh/id_rsa mark@100.64.126.62
+```
+
+  `IdentitiesOnly=yes` avoids "Too many authentication failures" from ssh-agent key
+  spam — this error bit us during `ssh-copy-id`.
+- Remote Login must be ON, all users, on the host: System Settings → General → Sharing.
+
+## 2. Why plain SSH is not enough (TCC model)
+
+The core insight: sends and chat.db reads work over plain SSH once File access is
+granted. But tapback/react and group-create use System Events UI automation
+(keystrokes), and macOS TCC (Transparency, Consent, and Control) authorizes UI
+automation **per responsible process**, not per user or per terminal.
+
+- **Full Disk Access** is a plain file check — passes for any process once granted.
+- **Accessibility** (send keystrokes) blames the daemonized **tmux server**
+  (ppid 1, launchd) — NOT Terminal.app, even when tmux was started from a Terminal
+  that already has Accessibility. Error looks like:
+
+```
+System Events got an error: osascript is not allowed to send keystrokes. (1002)
+```
+
+- **Fix**: grant Accessibility to the tmux *binary* itself, not to Terminal:
+  1. System Settings → Privacy & Security → Accessibility → `+`
+  2. `Cmd+Shift+G` → `/opt/homebrew/bin/tmux` → add → toggle ON
+  3. Restart the tmux server so it picks up the grant:
+
+```bash
+tmux kill-server && tmux new -s mapi
+```
+
+- Also required once: Full Disk Access for the terminal app, and Automation →
+  Messages (this prompts on the first send/react — someone must click on the
+  host screen directly or via Screen Sharing to approve it).
+
+## 3. The tmux command bridge (how we drive it)
+
+All GUI-privileged commands run **inside** the tmux session via `send-keys`,
+result captured via `capture-pane`:
+
+```bash
+ssh -o IdentitiesOnly=yes -i ~/.ssh/id_rsa mark@100.64.126.62 \
+  '/opt/homebrew/bin/tmux send-keys -t mapi "<command>" Enter; sleep 5; /opt/homebrew/bin/tmux capture-pane -t mapi -p -J'
+```
+
+Gotchas:
+
+- `capture-pane` only returns the visible viewport — long output gets clipped.
+  Redirect the command's output to a file and `cat` it over SSH instead of
+  reading it off the pane.
+- `grep -v "^$"` exits 1 when everything is blank, which breaks `&&` chains.
+- Quote `$` as `\$` — it has to survive shell → SSH → tmux send-keys quoting layers.
+- Use full paths (`/opt/homebrew/bin/...`) — tmux panes may not have brew on `PATH`.
+- `tmux new-window` with an inline command closes the window instantly if the
+  command fails. Create the window bare, then `send-keys` separately, so errors
+  stay visible instead of vanishing with the window.
+
+## 4. iMessage primitives
+
+The host keeps `/opt/homebrew/bin/imsg` 0.12.3 as the basic-I/O baseline. The
+pod uses `/Users/mark/imsg-emoji-build/bin/imsg` from Mapier's pinned
+`mapier/deploy` branch via `IMSG_BIN`. That 0.13.x build contains the
+live-verified macOS-26 participant/group-photo fixes and arbitrary-emoji RPC.
+After rebuilding it, run `bin/imsg launch --json` to inject the matching dylib.
+
+```bash
+# list chats — numeric chat_id per thread; hex identifier = group chat
+imsg chats --limit 5
+
+# read history — one JSON object per line
+# text comes from attributedBody; the raw sqlite `text` column is often NULL
+# on modern macOS, don't trust it
+imsg history --chat-id <id> --limit N --json
+
+# send — works for 1:1 (--to) or groups (--chat-id); AppleScript events,
+# no UI focus needed, no autocorrect
+imsg send --to "+1..." --text "..."
+imsg send --chat-id <id> --text "..."
+
+# react — UI automation, needs the Accessibility setup from §2, ~2s when working
+imsg react --chat-id <id> --reaction love|like|dislike|laugh|emphasis|question
+
+# native Apple Name & Photo flow (patched binary; privacy-sensitive share)
+/Users/mark/imsg-emoji-build/bin/imsg name-photo status --chat '<chat-guid>' --json
+/Users/mark/imsg-emoji-build/bin/imsg name-photo share --chat '<chat-guid>' --json
+```
+
+Numeric chat IDs are local execution details, not configuration. A consumer
+binding to a group configures it by portable GUID plus exact expected
+participants and resolves it afresh at boot. After changing that binding or
+upgrading `imsg`, run the read-only `scripts/resolve-group-smoke.ts`; it
+performs no sends, reactions, or thread creation.
+
+React caveats:
+
+- Reactions **toggle**. Reacting where the same reaction already exists
+  **removes** it — check `reactions[]` in `imsg history` first.
+- Targets the most-recent visible bubble; targeting precision is not yet
+  gate-tested (the 20× gate in `SETUP.md` §3d is still owed).
+
+Name & Photo caveat: `share` sends the pod's configured identity/photo to
+every participant. Inspect `status` and confirm the destination first. The
+gateway requires `available:true` and `should_offer:true`; the 2026-07-14 live
+gate returned `requested:true`, and the receiving test phone displayed Mapi's
+new contact info.
+
+Group creation:
+
+```bash
+osascript scripts/create-group.applescript "+1A" "+1B" "first message"
+```
+
+Drives `Cmd+N` compose keystrokes; sending the first message creates the
+thread (~7s). Caveat: keystroke typing passes through Messages autocorrect
+(turned "mapi" into "maxi") — planned fix is clipboard + `Cmd+V` paste. The
+group appears in `imsg chats` immediately; send-by-chat-id then works normally.
+
+Verification via sqlite when needed (only inside the FDA-granted tmux):
+
+```bash
+sqlite3 ~/Library/Messages/chat.db
+```
+
+- Tapbacks are rows with `associated_message_type` 2000–2005 (2000 = love),
+  `associated_message_guid` = `"p:0/<target-guid>"`.
+- Date decode: `datetime(date/1000000000 + 978307200, 'unixepoch')`.
+
+## 5. Running the agent
+
+```bash
+tmux new-window -t mapi -n agent
+# then, via send-keys into that window:
+cd ~/mapier/imsg-agent && /opt/homebrew/bin/pnpm dev 2>&1 | tee -a agent.log
+```
+
+- pnpm on the host: `brew install pnpm` (or `corepack enable` — the repo pins
+  the version via `packageManager`). The old better-sqlite3 ABI-rebuild note
+  is obsolete: #20 removed the native dependency.
+- Logs: `agent.log` in the repo. Prefixes: `[inbound]`, `[send]`, `[gate]`.
+  Multi-bubble bursts appear as consecutive `[send]` lines.
+- `.env` on the host is **not in git**: `PERSONA_MODEL=deepseek:deepseek-chat`,
+  `DEEPSEEK_API_KEY`, `ALLOWED_HANDLES` (empty = agent replies to nobody).
+
+## 6. Host posture
+
+Lid open, never lock, no auto-sleep — UI automation needs an unlocked GUI
+session. FileVault may stay ON. Manual login required after any reboot.
+
+## Known-fragile list
+
+- **React toggle behavior**: reacting twice with the same reaction removes it
+  instead of no-op'ing — always check existing `reactions[]` first.
+- **React targeting precision unproven**: targets "most recent visible bubble";
+  the 20× accuracy gate (`SETUP.md` §3d) hasn't been run yet.
+- **Autocorrect in group-create**: keystroke-typed group names/messages get
+  mangled by Messages autocorrect ("mapi" → "maxi"); clipboard-paste fix planned.
+- **capture-pane clipping**: long command output silently truncates to the
+  visible tmux viewport — always redirect to a file for anything nontrivial.
+- **TCC grants go stale after tmux/imsg brew upgrades**: a `brew upgrade` that
+  replaces the tmux or imsg binary can silently drop the Accessibility/Full
+  Disk Access grant — re-toggle it in System Settings if UI automation starts
+  failing after an upgrade.

package/docs/imsg-polls.md

@@ -0,0 +1,473 @@
+# Native iMessage poll investigation
+
+Date: 2026-07-07.
+
+Purpose: capture the exact host setup, commands, and findings from testing
+`openclaw/imsg` 0.12.3 native Messages polls for future investigation.
+
+## Host and test thread
+
+Host:
+
+- Machine: Haoxiang's MacBook Air, macOS 26.5.1
+- Tailnet IP: `100.64.126.62`
+- User: `mark`
+- Repo path: `~/mapier/imsg-agent`
+- Pod handle: `+16282640380`
+- `imsg` version: `0.12.3`
+
+Test thread:
+
+- Chat rowid: `3996`
+- Chat guid: `any;-;+17738867338`
+- Peer handle: `+17738867338`
+- `imsg chats --limit 5 --json` reported this thread as `service:"SMS"` even
+  though Messages rendered the native poll UI on the tester device.
+
+## Bridge setup
+
+Native poll send/vote requires the `imsg` advanced bridge. Before enabling the
+bridge, `imsg status --json` showed:
+
+```json
+{
+  "advanced_features": false,
+  "v2_ready": false,
+  "bridge_version": 0,
+  "basic_features": true,
+  "sip": "disabled"
+}
+```
+
+The helper dylib shipped with the required macOS 26 architecture:
+
+```bash
+lipo -archs /opt/homebrew/Cellar/imsg/0.12.3/libexec/imsg-bridge-helper.dylib
+# x86_64 arm64 arm64e
+```
+
+SIP was already disabled:
+
+```bash
+csrutil status
+# System Integrity Protection status: disabled.
+```
+
+The missing macOS 26 setting was library validation. Check it with:
+
+```bash
+defaults read /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation
+```
+
+It initially did not exist. Set it with admin privileges:
+
+```bash
+sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
+```
+
+Then reboot the host. FileVault/manual login may be required before Tailscale
+and SSH return.
+
+After reboot:
+
+```bash
+imsg launch --json
+```
+
+Expected success:
+
+```json
+{
+  "status": "launched",
+  "message": "Messages.app launched with dylib injection",
+  "dylib": "/opt/homebrew/Cellar/imsg/0.12.3/libexec/imsg-bridge-helper.dylib"
+}
+```
+
+Verify:
+
+```bash
+imsg status --json
+```
+
+Observed after the fix:
+
+```json
+{
+  "advanced_features": true,
+  "v2_ready": true,
+  "bridge_version": 2,
+  "typing_indicators": true,
+  "read_receipts": true,
+  "message": "Connected to Messages.app. IMCore features available."
+}
+```
+
+Also verified the helper was loaded:
+
+```bash
+pid=$(pgrep -x Messages | head -1)
+lsof -p "$pid" | grep -i 'imsg-bridge\|bridge-helper'
+```
+
+Observed:
+
+```text
+/opt/homebrew/Cellar/imsg/0.12.3/libexec/imsg-bridge-helper.dylib
+/Users/mark/Library/Containers/com.apple.MobileSMS/Data/.imsg-bridge-ready
+```
+
+## Poll send test
+
+Command:
+
+```bash
+imsg poll send \
+  --chat-id 3996 \
+  --question "poll smoke 1136?" \
+  --option "yes" \
+  --option "no" \
+  --json
+```
+
+Observed success:
+
+```json
+{
+  "messageGuid": "41F8E456-6EF3-4FC9-9736-93C29DD2E620",
+  "balloonBundleID": "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.messages.Polls",
+  "chatGuid": "any;-;+17738867338",
+  "poll": {
+    "kind": "created",
+    "event": "imessage.poll.created",
+    "question": "poll smoke 1136?",
+    "sessionIdentifier": "E76A5829-4530-4DC8-B106-88C2DA2795BD",
+    "options": [
+      {
+        "id": "D0EB4FE3-2D3E-4642-B178-C266E2B32052",
+        "text": "yes"
+      },
+      {
+        "id": "A316E9F5-3AFA-4275-80F2-DC96C1D99E30",
+        "text": "no"
+      }
+    ]
+  }
+}
+```
+
+## Reading poll history
+
+High-level read:
+
+```bash
+imsg history --chat-id 3996 --limit 15 --json
+```
+
+Observed rows:
+
+- Row `65919`: poll balloon.
+  - `guid`: `41F8E456-6EF3-4FC9-9736-93C29DD2E620`
+  - `text`: replacement character
+  - `balloon_bundle_id`: `com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.messages.Polls`
+  - `poll.kind`: `created`
+  - `poll.question`: `poll smoke 1136?`
+  - `poll.options`: `yes`, `no`
+- Row `65920`: plain caption message.
+  - `guid`: `1F4396DE-18DF-461B-A6D5-E190B25EABBD`
+  - `text`: `poll smoke 1136?`
+  - `reply_to_guid`: poll message guid
+
+This matches the `imsg poll --help` behavior: Messages does not render the poll
+title on the balloon, so `imsg` sends the question as a visible plain caption
+right after the poll.
+
+Raw `chat.db` query used:
+
+```bash
+sqlite3 ~/Library/Messages/chat.db "
+select
+  m.ROWID,
+  datetime(m.date/1000000000 + 978307200, 'unixepoch') as ts,
+  m.guid,
+  m.is_from_me,
+  h.id as handle,
+  quote(m.text),
+  m.balloon_bundle_id,
+  m.associated_message_guid,
+  m.associated_message_type,
+  length(m.payload_data),
+  length(m.message_summary_info),
+  m.reply_to_guid
+from message m
+left join handle h on h.ROWID=m.handle_id
+where m.ROWID >= 65918
+order by m.ROWID;
+"
+```
+
+Observed poll rows:
+
+```text
+65919|2026-07-07 18:36:07|41F8E456-6EF3-4FC9-9736-93C29DD2E620|1|+17738867338|NULL|com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.messages.Polls||0|7700|60|FBD9147D-F0D4-4B8C-8433-A16F10ACD1ED
+65920|2026-07-07 18:36:08|1F4396DE-18DF-461B-A6D5-E190B25EABBD|1|+17738867338|NULL|||0||51|41F8E456-6EF3-4FC9-9736-93C29DD2E620
+```
+
+**Balloon `associated_message_type` is unstable early.** The capture above
+(seconds after send) shows `0` on row 65919; re-querying the same row after
+the vote/option activity synced returns `3`, and `imsg` reports
+`poll.metadata.associated_message_type: 3` for it (verified twice on
+2026-07-07). Messages restamps the column. Consumers must never branch on the
+balloon's value — classification keys on `kind`, type `2` (option update),
+type `4000` (vote), and `original_guid` only (`pollEventKind`, `src/polls.ts`).
+
+Dump payload blobs:
+
+```bash
+sqlite3 ~/Library/Messages/chat.db "
+select writefile('/tmp/poll_payload_65919.bin', payload_data)
+from message
+where ROWID=65919;
+
+select writefile('/tmp/poll_summary_65919.bin', message_summary_info)
+from message
+where ROWID=65919;
+"
+
+file /tmp/poll_payload_65919.bin /tmp/poll_summary_65919.bin
+plutil -p /tmp/poll_payload_65919.bin
+plutil -p /tmp/poll_summary_65919.bin
+strings -a /tmp/poll_payload_65919.bin | grep -Ei 'yes|no|poll|option|vote'
+```
+
+The payload is an Apple binary property list. Its embedded `data:` URL decoded
+to a JSON payload with:
+
+```json
+{
+  "version": 1,
+  "item": {
+    "title": "poll smoke 1136?",
+    "creatorHandle": "e:mapi@mapier.ai",
+    "orderedPollOptions": [
+      {
+        "optionIdentifier": "D0EB4FE3-2D3E-4642-B178-C266E2B32052",
+        "canBeEdited": false,
+        "creatorHandle": "e:mapi@mapier.ai",
+        "attributedText": "yes",
+        "text": "yes"
+      },
+      {
+        "optionIdentifier": "A316E9F5-3AFA-4275-80F2-DC96C1D99E30",
+        "canBeEdited": false,
+        "creatorHandle": "e:mapi@mapier.ai",
+        "attributedText": "no",
+        "text": "no"
+      }
+    ]
+  }
+}
+```
+
+The URL had `c=2`, matching the two original options.
+
+## Vote and user-added option findings
+
+Tester action 1: selected `yes`.
+
+Tester action 2: added a third option from the user device.
+
+Observed from the host afterward:
+
+- `imsg history --chat-id 3996 --limit 15 --json` still showed only the two
+  original options.
+- `sqlite3 ~/Library/Messages/chat.db` showed no new rows for chat `3996` after
+  rows `65919` and `65920`.
+- `max(ROWID)` was `65922`, but rows `65921` and `65922` belonged to chat `190`,
+  not the poll chat.
+- Re-dumping `payload_data` and `message_summary_info` for row `65919` produced
+  identical SHA-256 hashes before and after the vote/third-option test.
+- The decoded payload still had `c=2` and only the original `yes`/`no` options.
+
+Hash check used:
+
+```bash
+shasum -a 256 \
+  /tmp/poll_payload_65919.bin \
+  /tmp/poll_payload_65919_after.bin \
+  /tmp/poll_summary_65919.bin \
+  /tmp/poll_summary_65919_after.bin
+```
+
+Observed:
+
+```text
+b80198e108faea14bca823748292528f7ed86d6c0e4407f92fd8717e8313a512  /tmp/poll_payload_65919.bin
+b80198e108faea14bca823748292528f7ed86d6c0e4407f92fd8717e8313a512  /tmp/poll_payload_65919_after.bin
+f29fc961af96b20a71de09b39b575c0f1358a263a704ffa8df03a760dbf91997  /tmp/poll_summary_65919.bin
+f29fc961af96b20a71de09b39b575c0f1358a263a704ffa8df03a760dbf91997  /tmp/poll_summary_65919_after.bin
+```
+
+Conclusion from this test: on this host and this thread, Mapi can see a poll it
+creates, including the question and original options. It could not see the
+tester vote or the tester-added third option.
+
+**Correction (same day, ~18:52): the negative finding above was sync lag, not a
+capability gap. See the follow-up section below — both the vote and the
+user-added option landed in chat.db as new message rows minutes later, and
+`imsg` 0.12.3 parses both.**
+
+## Follow-up: vote and option readback works
+
+Re-checked the same chat later the same day. Two new rows had arrived in chat
+`3996`, both from `+17738867338`, both pointing at the original poll guid:
+
+```text
+65925|2026-07-07 18:52:07|AF3C34AC-E272-46AF-931A-C65AA21CC1F9|is_from_me=0|+17738867338|associated_message_type=4000|assoc_guid=41F8E456-...|payload 706B|summary 239B
+65926|2026-07-07 18:52:20|C863C985-FCA7-45E3-BD9B-FEA749D04982|is_from_me=0|+17738867338|associated_message_type=2   |assoc_guid=41F8E456-...|payload 1876B|summary 61B
+```
+
+### Row 65925 — the vote (`associated_message_type` 4000)
+
+`payload_data` is an NSKeyedArchiver plist wrapping a `data:` URL whose JSON is:
+
+```json
+{"version":1,"item":{"votes":[{
+  "voteOptionIdentifier":"D0EB4FE3-2D3E-4642-B178-C266E2B32052",
+  "serverVoteTime":805143043.515404,
+  "participantHandle":"+17738867338"}]}}
+```
+
+That option id is the original `yes`. `message_summary_info` is human-readable:
+`ams = "You removed a vote from “no”"` — the tester apparently voted `no`
+first, removed it, then voted `yes`; the `votes` array reflects the
+participant's current vote state.
+
+### Row 65926 — the user-added option (`associated_message_type` 2)
+
+Balloon session update. Decoded `data:` URL JSON carries the full updated
+option list, with per-option `creatorHandle` identifying who added what:
+
+```json
+{"item":{"creatorHandle":"+17738867338","title":"","orderedPollOptions":[
+  {"text":"yes","optionIdentifier":"D0EB4FE3-...","creatorHandle":"e:mapi@mapier.ai"},
+  {"text":"no","optionIdentifier":"A316E9F5-...","creatorHandle":"e:mapi@mapier.ai"},
+  {"text":"unsure","optionIdentifier":"2E247807-B986-4E57-ABB3-7E7128503A5A","creatorHandle":"+17738867338"}
+]},"version":1}
+```
+
+The tester-added third option is `unsure`.
+
+### imsg 0.12.3 parses both — history and watch
+
+No manual plist decoding needed. `imsg history --chat-id 3996 --json` returns:
+
+- Vote row: `poll.kind: "vote"`, `poll.event: "imessage.poll.voted"`, and
+  `poll.vote` / `poll.votes[]` with `option_id`, **`option_text` already
+  resolved** (`"yes"`), `participant`, `server_time`, plus
+  `original_guid` = the poll message guid.
+- Option-update row: full `poll.options[]` including `unsure`, `creator` =
+  `+17738867338`, `original_guid` = the poll guid.
+
+`imsg watch --chat-id 3996 --since-rowid 65918 --json` replays the same rows
+with the same `poll` objects, so the live watch/rpc stream the pod already
+consumes carries poll events.
+
+### Parsing caveats
+
+- The option-update row is mislabeled `poll.kind: "created"` /
+  `event: "imessage.poll.created"` (imsg keys "created" off the balloon
+  payload shape, and `associated_message_type` 2 is also used for fresh
+  balloons). Detect updates as: poll object whose `original_guid` differs
+  from the original poll send, or diff `options[]` against the options seen
+  at `poll send` time.
+- The update row's `poll.question` is junk (the update payload has
+  `title: ""`, and imsg falls back to unrelated nearby text). Join via
+  `original_guid` to the original poll for the real question.
+- `poll.votes[]` is the *sender's current votes*, not an event log — a vote
+  switch shows up as one row with the final state (the removal narrative only
+  survives in `message_summary_info.ams`).
+- Timing: the vote/update rows appeared with `date` ≈ 18:52, ~16 min after the
+  poll send, and were absent during the first inspection. Whether that lag was
+  tester timing or Messages/CloudKit sync latency is unresolved — do not
+  assume poll updates are immediate.
+
+## Source-level notes (openclaw/imsg)
+
+From reading the imsg source (github.com/openclaw/imsg) after the follow-up:
+
+- Poll decode lives in `MessagePollDecoder` (`Sources/IMsgCore/MessagePolls.swift`)
+  with vote/option-text resolution in `MessageStore+Polls.swift`; the injected
+  bridge send path is `handleSendPoll` / `buildPollVoteIMMessage` in
+  `Sources/IMsgHelper/IMsgInjected.m`.
+- **Reading polls needs no bridge/dylib** — only `poll send` / `poll vote`
+  (private IMCore API) require `imsg launch`. Readback is implicit in the
+  normal read paths (`history`, `watch`, RPC `messages.history` /
+  `watch.subscribe`); any row that decodes as a poll gets the `poll` object
+  attached, no flag needed.
+- **No live IMCore push channel for polls.** The dylib event tailer
+  (`IMsgEventTailer`, used for typing indicators) has zero poll code. Poll
+  events are chat.db-derived via `MessageWatcher` (filesystem events + 5s
+  fallback poll), so latency floor is DB-write time, and votes only become
+  visible when Messages persists the rows.
+- The decoder constants match what we observed: `voteAssociatedMessageType`
+  = 4000, `updateAssociatedMessageType` = 2; the reaction-exclusion SQL only
+  drops `associated_message_type` 2000–3006, so poll rows pass through by
+  default.
+- Version timeline: readback shipped in 0.10.0, `poll vote` in 0.12.0, vote
+  option-text resolution from Add-Choice rows fixed in 0.12.2 (#153). Nothing
+  after 0.12.3 adds a new readback mechanism — 0.12.3 is current for polls.
+- Watch caveat: `MessageWatcher` gives up on a row whose `chat_message_join`
+  hasn't resolved after 20 retries (`WatchState.unresolvedChatRetryLimit`) and
+  silently advances past it — a dropped row is indistinguishable from "never
+  written" if only watching. When debugging missing poll events, check the raw
+  `message` table by ROWID first, independent of the chat join.
+- `poll vote` outbound had a macOS 26.4.x persistence bug fixed in 0.12.2
+  (#150) — evidence that Apple's Polls IMCore plumbing regresses across 26.x
+  point releases; treat inbound persistence as fragile too.
+- The upstream repo's own docs (`docs/history.md`, "Manual native poll test
+  plan") document exactly our verification flow:
+  `imsg history --chat-id <id> --json | jq -c 'select(.poll != null)'`.
+
+## Current Mapi behavior
+
+**Updated 2026-07-07 (same day, follow-up change): the pipeline now forwards
+poll events to the LLM.** The original gap — `toModelMessages()` forwarded only
+`m.text`, so the agent saw a vote as a blank bubble and an added option as
+`�`, and replied "did something get lost in translation there? 😂" — is fixed:
+
+- `src/types.ts` models the poll payload (`MessagePoll` on `ImsgMessage`);
+  both gateways pass it through (the rpc path already forwarded whole JSON
+  objects, so no `src/gateway/imsg.ts` change was needed).
+- `src/polls.ts` classifies rows (`pollEventKind` — absorbing the
+  kind-mislabel and junk-question hazards above) and renders them as bracket
+  notes (`renderPollEvent`), resolving the question via `original_guid`.
+- `toModelMessages()` (imsg-agent) pushes those notes — e.g.
+  `[voted "yes" on the poll "poll smoke 1136?"]`, `[added option "unsure" to
+  the poll "poll smoke 1136?"]` — instead of the junk display text.
+- Contract + fake parity + sim UI: gateway-contract.md §2 "Native poll
+  readback", FakeGateway poll fixtures, sim poll bubble (sim-dev-tools.md §6).
+
+## Things to try next
+
+Resolved by the follow-up above:
+
+- ~~Try `imsg watch --json`~~ — watch emits the same `poll` objects as history.
+- ~~Search whether poll updates land elsewhere~~ — they land in the same chat
+  as new `message` rows (`associated_message_type` 4000 = vote, 2 = option
+  update); the original balloon row is never rewritten.
+
+Still open:
+
+- Repeat in a known iMessage-only DM. The tested thread `3996` reports
+  `service:"SMS"` on the host.
+- Repeat in an iMessage group chat (multi-participant votes; per-participant
+  attribution in `poll.votes[]`).
+- Characterize vote-sync latency (the ~16 min gap above) and whether it
+  requires Messages.app frontmost / bridge injected.
+- Vote removal without re-vote: does a bare retraction produce a 4000 row with
+  an empty `votes[]`?
+- If building on this, update `src/types.ts`, gateway contract docs, fake
+  gateway parity, and `toModelMessages()` so the LLM receives poll events in a
+  stable text form — including the `original_guid` join and the
+  kind-mislabel caveats above.