# Optional 👍 requirement for new Repo tasks

New Repo tasks default to `policy.require_thumbs_up = true`. The administrator can turn this off in **Worker settings** (`/inbox-tasks/admin`) before new tasks are created. Existing tasks with a missing flag keep the original Inbox/read rules. Each task freezes its policy; changing the setting never rewrites active tasks or completion history. The legacy Gmail workflow, OAuth scopes and Cortex sending contract are unchanged.

A qualifying delivery must still be present, read, in Inbox, outside Spam/Trash, and meet any existing star/important flags. When required, it must also have a verified outgoing 👍 reaction to that delivery's exact RFC Message-ID. The existing frozen work list, hidden margin and logical-message deduplication apply to the combined checks. Reactions do not increase completion credit or establish human reading.

## Matching and observation

`GmailReader::message()` saves the Gmail conversation ID from the same metadata response already used for identity/label checks. `GmailTaskSync` follows Gmail history and checks relevant message/reaction changes in parallel groups of at most six. It reuses verified countdown metadata and inspects conversation headers once to find existing reactions. See [Faster progress](FAST-PROGRESS.md). The original `GmailReactions::check()` four-conversation path remains available when fast sync is disabled. It uses fixed Gmail HTTPS GET requests, existing backend credentials and the existing exclusive task lease. It does not scan the whole Sent mailbox, send reactions, mark messages read or alter Gmail labels.

Optimized conversation reads request metadata headers without message body data; the original fallback reads MIME structure and headers without body data. Only candidate outgoing reaction messages get body data. A candidate must have Gmail's `SENT` label, a From address canonicalizing to the connected mailbox or a verified send-as alias of that mailbox, exactly one `In-Reply-To` matching an identified task attempt, and a send date within the task's lifetime. Its non-attachment MIME part must be `text/vnd.google.email-reaction+json`, with integer `version: 1` and one 👍 emoji (skin tones accepted). Ordinary replies containing 👍, incoming reactions, other emoji and reactions to unrelated messages do not count. Optimized candidate reads resume from durable queues within bounded passes; the fallback inspects up to eight candidate bodies per conversation per pass. API attachment bodies are fetched only for the small reaction JSON part, with size limits.

Custom senders are validated lazily using authenticated `GET /settings/sendAs`, requesting only `sendAsEmail` and `verificationStatus`. Only custom addresses with `verificationStatus: accepted` qualify. Successful lookup results contain address hashes only, cached for 60 seconds under the connection and authorization identity. The lookup costs one quota unit and shares the existing Gmail budgets and retry handling. Reactions from the primary connected address need no alias lookup. A failed lookup preserves the synchronization queue and reports a checking failure; it must not silently reject a legitimate reaction. Both optimized and fallback trackers use these rules. Existing ignored alias reactions can be found by the next bounded conversation reconciliation without resetting task history or changing mailbox settings.

Confirmed evidence is keyed by original RFC Message-ID, with logical message ID, attempt ID, Gmail reaction/conversation IDs, emoji, sent time and observed time. Successful checkpoints persist before checking the next conversation, so a later API failure does not erase evidence. The worker receives aggregate counts only. No original email bodies or reaction text are stored. An API/access failure records checking unavailable and prevents completion on that pass; it is not a worker action or misconduct decision.

Evidence records what was observed. Deleting a Sent reaction later does not erase its earlier observation. Normal monitoring still records subsequent original-message label/location changes separately. Completion freezes the label observation and reaction evidence together for manual review. Approval and payment remain manual.

## Campaign compatibility

Cortex must send messages on which Gmail permits reactions. In particular, omit custom `Reply-To` and mailing-list headers. The checker recognizes those two restrictions from original metadata; if they make the task's required count impossible, it tells the worker to contact the task owner. Gmail has other eligibility restrictions, so a worker who cannot see the reaction control should contact the owner rather than being instructed to keep retrying an impossible step. Disabling the requirement affects future tasks only; existing tasks need administrator review if incompatible.

Worker progress shows **Read in Inbox** and **👍 added** against the full received total, while the combined progress bar counts messages satisfying all requirements. Dynamic instructions explicitly ask for missing 👍 when the Inbox/read steps are done. `/worker-review` and the detailed review page show saved reaction counts and evidence without calling Gmail.

## Storage and deployment

Migration `2026_10_19_000004_add_gmail_reaction_tracking.php` adds nullable `inbox_tasks.reaction_state` JSON and nullable `inbox_deliveries.gmail_thread_id` / `reaction_supported` columns. No data backfill, new tokens, new tables or campaign sends are involved. `reaction_state` is hidden from model serialization and worker responses. Existing account deletion removes these records with the existing task/delivery graph.

Run the targeted migration only; legacy production migrations do not describe the entire deployed schema. Tests use in-memory SQLite and fake HTTP responses. Never run the production dispatch processor just to test reaction tracking.

References: https://developers.google.com/workspace/gmail/reactions/format and https://support.google.com/mail/answer/14080429.
