mailmate 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2e41c1bf66c9a41c75d683f9e7edcfa2d6ac5982f6a54c2d3cc4b2cbb5c36a8
-  data.tar.gz: 378d1b75d3485de7cf5285e8b12f4fa0ebd7b144b9ebe4a5d4322f6a5d592726
+  metadata.gz: b030228294a0ca2411434364c83c99f83822d10258ac94cb81bc065eac5ce66c
+  data.tar.gz: df735317a7c2747ca656db9fa71eee6edcb77ada30708561652305fc1748fe07
 SHA512:
-  metadata.gz: 710617dc65666c1eec32f4a6d1e7c4ac15c3aab6ce295548d59edaefacd86863ed2b716246bceb250dd9f7f67c4e3a54701366a3c4c65a6b69321b6df3024587
-  data.tar.gz: a54ee5f4a6cf7ff02c35f6239ab63e805404db1610fa470358ac382bf4870b1fb8176a0990e5a01a24195275e6c603fe44b2d124b9c6829765f222872f874a10
+  metadata.gz: a9114cc082c2f302fc5b71f44bdc8ef3273c9f4f07e2c274f977a53f36db17533d2c693b111579587f0bd3a4ec2e5c02a979ebd4a8d4edc3beb748be762a877d
+  data.tar.gz: 0ab6609a1d3aa348a1de39ff8504d285b13adedae1c639060466aa343074435302d073a3f4dfe6a30c6ee6e2d5861c7d495b850bbfdf88a7499fe658a6a9a131

data/README.md

@@ -1,6 +1,6 @@
 # mailmate
 
-Ruby toolkit for [MailMate](https://freron.com) on macOS — a smart-mailbox filter engine, on-disk index readers, and CLI tools (`mmsearch`, `mmmessage`, `mmopen`, `mm-mailboxes`, `mmtags`, `mm-modify`, `mm-send`, `mm-draft`, `mmdiscover`) for searching, reading, modifying, and sending mail.
+Ruby toolkit for [MailMate](https://freron.com) on macOS — a smart-mailbox filter engine, on-disk index readers, and CLI tools (`mmsearch`, `mmmessage`, `mmopen`, `mm-mailboxes`, `mmtags`, `mm-modify`, `mm-verify`, `mm-send`, `mm-draft`, `mmdiscover`) for searching, reading, modifying, and sending mail.
 
 **Requires macOS with MailMate installed.** The library code (filter parser, evaluator) works anywhere, but the integration with MailMate itself — AppleScript, on-disk index reads, the `emate` binary — is macOS-only by way of MailMate being macOS-only.
 
@@ -149,17 +149,47 @@ mm-modify 183715 tag processed read move Archive
 # Dry-run first
 mm-modify 183715 archive --dry-run
 
-# Verify the new flags after acting
+# Print the current flags after acting (raw probe)
 mm-modify 183715 read --verify
 
 # As of 1.2.0, `--verify` works in `--dry-run` mode too — pair them as a
 # post-hoc state probe (run the action first, then re-run with --dry-run
 # --verify to confirm the change took effect).
 mm-modify 183715 read --dry-run --verify
+
+# Effect verification (--check): confirm the action actually landed on THIS
+# eml-id by re-reading its #flags index. This is the only way to catch a
+# Message-ID that resolved to a different duplicate copy — AppleScript can't
+# report which message it acted on, but the index can show whether OURS
+# changed. A mismatch exits 3. Opt-in because MailMate flushes #flags ~5s
+# after acting, so --check polls up to --check-timeout (default 8s).
+mm-modify 183715 tag urgent --check
 ```
 
 **Tip — batch your actions.** Doing all related changes in **one** `mm-modify` invocation is still worthwhile: one open/close cycle instead of two, and the chain runs deterministically without you having to think about ordering. Splitting is safe — `path_for` falls back to a filesystem glob if MailMate's `#source` index is briefly stale after a fast-move — just slower than batching.
 
+### `mm-verify` — confirm a batch of modifies with ONE flush-wait
+
+Inline `--check` pays MailMate's ~5 s `#flags`-flush latency *per message* — verifying 50 modifies that way would cost ~250 s. But `#flags` is a single global file flushed once, so a whole batch can be confirmed by waiting for that flush **once**. `mm-modify --emit-check` performs the action and prints a JSON *check-ticket* instead of waiting; collect the tickets, then hand them to `mm-verify`.
+
+```bash
+# Action phase: act on N messages, no per-message wait. Each --emit-check
+# prints a one-line ticket {eml_id, message_id, expectations} to stdout.
+for id in 183715 183720 183733; do
+  mm-modify "$id" tag triaged --emit-check >> tickets.jsonl
+done
+
+# Verify phase: confirm the whole batch in one index-flush wait.
+mm-verify --file tickets.jsonl
+# → JSON {checked, passed, failed, waited_seconds, results:[{eml_id, ok, flags, unmet}]}
+#   exit 0 if all confirmed, 3 if any failed.
+
+# Tickets can also be piped, or passed as a JSON-array argument:
+mm-modify 183715 flag --emit-check | mm-verify
+```
+
+A failed ticket means that action didn't land on that eml-id — it registered on a different duplicate copy, or not at all. Chains containing `move`/`archive`/`delete` aren't flag-verifiable and carry empty expectations (auto-pass).
+
 ### `mm-send` — send mail
 
 `mm-send` is a thin wrapper around MailMate's bundled `emate mailto`, with `--markup markdown` enforced. The body is read from stdin.
@@ -246,6 +276,8 @@ A few rough edges to be aware of:
 
 ## Status
 
+1.5.0 — Reliability and batch-verification for `mm-modify`, plus search/read speedups. `mm-modify` gains a no-window retry guard (a `mid:` open that spawns no viewer would otherwise act on the wrong message) and opt-in effect verification: `--check` confirms a flag/tag/read action landed on the target eml-id by re-reading `#flags` (the only way to catch a duplicate-Message-ID misland). Because MailMate flushes `#flags` to disk ~5 s after acting, a new **`mm-verify`** command plus `mm-modify --emit-check` decouple acting from confirming — collect JSON check-tickets across a batch and verify them all in one flush-wait instead of paying the latency per message. `mmsearch` is substantially faster (compiled date ranges, cheapest-spec-first ordering, bulk-unpack index reader, inverted body search) with bit-identical output; the persistent MCP server now invalidates index caches on disk change. `mmmessage` shows user tags and lazy-loads the `mail` gem (`--raw`/`--mailmate` skip it). MCP: `message` gains `markdown`, `modify` gains a `check` mode (`none｜inline｜defer`), and a new `verify` tool batch-confirms deferred tickets.
+
 1.2.0 — `mm-modify` no longer brings MailMate to the foreground and is roughly 8× faster on single-action invocations. Internally: the open call uses `open -g -a MailMate <url>` to keep MailMate in the background, and the fixed `--settle` sleeps are replaced by active waits (polling for the spawned viewer window to appear). `mmopen` gains a `--background` / `-g` flag for ad-hoc use. `mm-modify --verify` now works in `--dry-run` mode as a post-hoc state probe. `--settle` is preserved for backward compat; it now caps the active-wait timeout rather than fixing sleep duration.
 
 1.1.0 — `reverse_markdown` (and its transitive `nokogiri` dep) is now opt-in rather than auto-installed. Run `gem install reverse_markdown` if you want `mmmessage --markdown`; everything else is unchanged.
@@ -284,7 +316,7 @@ gem install reverse_markdown
 
 That single command pulls `nokogiri` in automatically — no separate `gem install nokogiri` step. This is kept out of the base install because nokogiri ships a native extension. On Ruby/platform combinations without a precompiled match nokogiri falls back to compiling from source — it vendors its own libxml2/libxslt, but it does need a C compiler, which on macOS means Xcode Command Line Tools (`xcode-select --install`). If `gem install reverse_markdown` fails, that's almost certainly the cause.
 
-If you never use `--markdown`, you never pay any of this. If you do invoke `--markdown` without the gem already being installed (default on most Ruby versions), `mmmessage` exits with a clear install hint.
+If you never use `--markdown`, you never pay any of this. If you do invoke `--markdown` without the gem installed, `mmmessage` warns with a clear install hint and falls back to the raw HTML body (it does not abort — so the in-process MCP server survives a missing optional dependency).
 
 ### From source (development)
 
@@ -303,7 +335,7 @@ Then `mmdiscover` as above.
 
 ### MCP server
 
-The gem also ships an MCP server (`exe/mailmate-mcp`) that exposes the same surface to AI assistants as JSON-RPC tools: `search`, `message`, `modify`, `send`, `open`, `list_mailboxes`, `list_tags`, `resolve_id`. After `gem install mailmate`, `mailmate-mcp` is on your `PATH`.
+The gem also ships an MCP server (`exe/mailmate-mcp`) that exposes the same surface to AI assistants as JSON-RPC tools: `search`, `message`, `modify`, `verify`, `send`, `draft`, `open`, `list_mailboxes`, `list_tags`, `resolve_id`. After `gem install mailmate`, `mailmate-mcp` is on your `PATH`.
 
 #### Claude Code (global, all projects)
 
@@ -347,7 +379,8 @@ Restart Claude Desktop after any change to server code or config.
 | `mmopen` | Open one message in MailMate's UI (via `open mid:…`). `--print` returns the URL. |
 | `mm-mailboxes` | List accounts, IMAP mailboxes (with optional counts), and smart-mailbox names. |
 | `mmtags` | List user tags applied to messages (with counts) or defined in Preferences. |
-| `mm-modify` | Mark read/flag/tag/archive a message via AppleScript; same-account `move` uses a fast `.eml`-rename path with no UI takeover. |
+| `mm-modify` | Mark read/flag/tag/archive a message via AppleScript; same-account `move` uses a fast `.eml`-rename path with no UI takeover. `--check` confirms the change landed; `--emit-check` defers confirmation to `mm-verify`. |
+| `mm-verify` | Batch-confirm `mm-modify --emit-check` tickets against the `#flags` index in one flush-wait. JSON in, JSON summary out. |
 | `mm-send` | Send mail through `emate` with a markdown body on stdin. |
 | `mm-draft` | Like `mm-send`, but only ever opens a draft — refuses `--send-now` (exit 2). |
 | `mmdiscover` | First-run bootstrap; (re-)writes the user config from MailMate's plists. |

data/exe/mm-verify

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "mailmate"
+require "mailmate/cli/verify"
+
+exit Mailmate::CLI::Verify.run(ARGV)

data/lib/mailmate/cli/message.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require "optparse"
-require "mail"
+# `mail` is required lazily inside run() — the --raw and --mailmate paths
+# never parse the message, so they shouldn't pay ~50 ms loading the gem.
 
 module Mailmate
   module CLI
@@ -47,6 +48,7 @@ module Mailmate
           return 0
         end
 
+        require "mail"
         mail = Mail.read(path)
         print_headers(mail, eml_id, path) unless opts[:text_only]
         $stdout.puts text_body(mail, markdown: opts[:markdown])
@@ -91,6 +93,8 @@ module Mailmate
         $stdout.puts "message-id: #{mail.message_id}"
         thread_id = Mailmate::Attributes.thread_id_for(mail)
         $stdout.puts "thread-id:  #{thread_id}" if thread_id
+        tags = user_tags(eml_id)
+        $stdout.puts "tags:       #{tags.join(", ")}" unless tags.empty?
         if mail.attachments.any?
           $stdout.puts "attachments:"
           mail.attachments.each do |a|
@@ -105,6 +109,18 @@ module Mailmate
         $stdout.puts
       end
 
+      # User tags applied to this message, from MailMate's `#flags` index —
+      # tags live there as IMAP keywords, not in the .eml, so the parsed Mail
+      # can't see them. Drops `\…` (RFC) and `$…` (Apple/Thunderbird) system
+      # flags so only user-facing tags show. Same derivation as mmsearch's
+      # `tags` column. Returns [] when the index is missing or the message
+      # has none.
+      def user_tags(eml_id)
+        return [] if eml_id.nil?
+        flags = (Mailmate::IndexReader.for("#flags").flags_for(eml_id.to_i) rescue [])
+        flags.reject { |f| f.start_with?("\\", "$") }
+      end
+
       def text_body(mail, markdown: false)
         if mail.text_part
           # text/plain is already plain — markdown flag is a no-op here.
@@ -145,8 +161,11 @@ module Mailmate
         rescue LoadError => e
           warn "mmmessage --markdown needs the reverse_markdown gem (which pulls nokogiri)."
           warn "Install it with:  gem install reverse_markdown"
-          warn "(underlying: #{e.message})"
-          exit 3
+          warn "(underlying: #{e.message}) — falling back to raw HTML."
+          # Degrade to the raw HTML rather than `exit`: a library method must
+          # not kill its host, and the in-process MCP server would otherwise
+          # die on the SystemExit (its dispatch rescues StandardError only).
+          return html
         end
         doc = Nokogiri::HTML(html)
         doc.css("style, script").remove

data/lib/mailmate/cli/modify.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "json"
+require_relative "../flag_check"
 
 module Mailmate
   module CLI
@@ -59,12 +61,45 @@ module Mailmate
 
         warn_on_duplicates(message_id, eml_id)
 
-        drive(eml_id, message_id, actions, opts)
-        0
+        ok = drive(eml_id, message_id, actions, opts)
+
+        # --emit-check: the action is sent; defer confirmation to a later
+        # batched `mm-verify` pass. Emit the ticket as the sole stdout line
+        # (operational notes went to stderr via `say`) and exit 0 — there's
+        # nothing to fail on yet.
+        if opts[:emit_check]
+          $stdout.puts JSON.generate(build_check_ticket(eml_id, message_id, actions))
+          return 0
+        end
+
+        # Exit 3 when an effect check fails — distinct from "couldn't resolve"
+        # (1) and "bad usage" (2). The MCP surfaces this as isError, and a
+        # caller scripting mm-modify can branch on it.
+        ok ? 0 : 3
+      end
+
+      # A deferred-verification ticket: the target eml-id plus the #flags
+      # expectations its action chain should satisfy once MailMate flushes.
+      # Non-flag-verifiable chains (move/archive/delete) carry an empty list,
+      # so mm-verify auto-passes them. Symbol kinds are stringified for JSON;
+      # mm-verify / FlagCheck.met? resolve either form.
+      def build_check_ticket(eml_id, message_id, actions)
+        exps = verifiable_expectations(actions) || []
+        {
+          "eml_id"       => eml_id.to_i,
+          "message_id"   => message_id,
+          "expectations" => exps.map { |kind, arg| [kind.to_s, arg] },
+        }
+      end
+
+      # Operational notes go to stderr in --emit-check mode (stdout must be
+      # pure JSON for the ticket); otherwise to stdout as before.
+      def say(opts, msg)
+        (opts[:emit_check] ? $stderr : $stdout).puts(msg)
       end
 
       def parse_options(argv)
-        opts = { verify: false, dry_run: false, settle: 3.5, keep_window: false }
+        opts = { verify: false, dry_run: false, settle: 3.5, keep_window: false, check: false, check_timeout: 8.0, emit_check: false }
         parser = OptionParser.new do |o|
           o.banner = <<~BANNER
             Usage: mm-modify <id> <action> [args...] [<action> [args...]]...
@@ -102,6 +137,9 @@ module Mailmate
           o.on("--dry-run", "Print the actions; don't run") { opts[:dry_run] = true }
           o.on("--settle SECONDS", Float, "Timeout for waiting for MailMate's viewer window to spawn after open_url (default 3.5)") { |s| opts[:settle] = s }
           o.on("--keep-window", "Don't close the spawned message-viewer window") { opts[:keep_window] = true }
+          o.on("--check", "Verify flag/tag/read actions actually landed on the TARGET eml-id by polling its #flags index after acting (mismatch → exit 3). This is the only way to detect a `mid:` open that resolved to a different duplicate copy. Opt-in, NOT default: MailMate flushes #flags to disk several seconds after an AppleScript action, so this waits up to --check-timeout (default 8s) for the index to catch up before deciding. Chains containing move/archive/delete/junk aren't flag-verifiable and are skipped.") { opts[:check] = true }
+          o.on("--check-timeout SECONDS", Float, "Max seconds to wait for the #flags index to reflect the action when --check is set (default 8.0; the index typically lags ~5s).") { |s| opts[:check_timeout] = s }
+          o.on("--emit-check", "Don't verify inline; instead print a one-line JSON check-ticket to stdout ({eml_id, message_id, expectations}) and exit 0 once the action is sent. Collect tickets across a batch of modifies and feed them to `mm-verify` to confirm them all with a SINGLE index-flush wait, instead of paying ~5s per message. Operational notes go to stderr so stdout stays pure JSON.") { opts[:emit_check] = true }
         end
         parser.parse!(argv)
         [opts, parser]
@@ -156,6 +194,7 @@ module Mailmate
         fast_moves, other = actions.partition { |name, _, _| name == "move" }
 
         if other.empty? && !fast_moves.empty?
+          ok = true
           current_path = Mailmate::EmlLookup.path_for(eml_id)
           fast_moves.each do |_name, selector, args|
             new_path = try_fast_move(eml_id, current_path, args.first, opts)
@@ -164,9 +203,10 @@ module Mailmate
             else
               # Fast-path declined for this one move (cross-account, target
               # not found, perm error, …) — single UI-driven move as fallback.
-              drive_via_applescript(eml_id, message_id, [["move", selector, args]], opts)
+              ok &&= drive_via_applescript(eml_id, message_id, [["move", selector, args]], opts)
             end
           end
+          ok
         else
           # Mixed chain (or pure non-move chain): everything goes through the
           # AppleScript driver in the user-supplied order.
@@ -188,14 +228,14 @@ module Mailmate
 
         dest_path = File.join(dest_messages, "#{eml_id}.eml")
         if dest_path == current_path
-          $stdout.puts "move (fast): #{eml_id}.eml is already in #{target_spec} — no-op"
+          say(opts, "move (fast): #{eml_id}.eml is already in #{target_spec} — no-op")
           return dest_path
         end
 
         if opts[:dry_run]
-          $stdout.puts "move (fast, dry-run): would rename"
-          $stdout.puts "  from: #{current_path}"
-          $stdout.puts "  to:   #{dest_path}"
+          say(opts, "move (fast, dry-run): would rename")
+          say(opts, "  from: #{current_path}")
+          say(opts, "  to:   #{dest_path}")
           return dest_path
         end
 
@@ -204,7 +244,7 @@ module Mailmate
         # rescans; bust it so any subsequent path_for in this process re-reads
         # (and eventually picks up MailMate's refreshed value).
         Mailmate::IndexReader.reset!("#source") if defined?(Mailmate::IndexReader)
-        $stdout.puts "move (fast): renamed #{eml_id}.eml → #{relative_to_imap_root(dest_messages)}"
+        say(opts, "move (fast): renamed #{eml_id}.eml → #{relative_to_imap_root(dest_messages)}")
         dest_path
       rescue Errno::EACCES, Errno::EXDEV, Errno::ENOENT, Errno::EEXIST => e
         warn "move (fast): rename failed (#{e.class}: #{e.message}); falling back to AppleScript"
@@ -271,12 +311,27 @@ module Mailmate
         # the timeout for this wait rather than the sleep duration.
         new_windows = opts[:dry_run] ? [] : wait_for_new_window(driver, windows_before, timeout: opts[:settle])
 
+        # No viewer window means the `mid:` open didn't take (MailMate busy,
+        # mid-launch, or the URL didn't resolve) — performing actions now
+        # would act on whatever is currently selected, i.e. the wrong message.
+        # Retry the open once before proceeding; if it still doesn't spawn,
+        # warn loudly. Effect verification below is the backstop for flag
+        # actions; for move/archive/delete this warning is the only signal.
+        if !opts[:dry_run] && new_windows.empty?
+          driver.open_url(mid_url)
+          new_windows = wait_for_new_window(driver, windows_before, timeout: opts[:settle])
+          if new_windows.empty?
+            warn "WARNING: no MailMate viewer window appeared for #{mid_url} (retried once)."
+            warn "         The action target is UNCONFIRMED — it may hit the wrong message or no-op."
+          end
+        end
+
         # Restore unread BEFORE user actions: a subsequent move / archive /
         # delete moves the message out of the viewer's selection, after
         # which a `markAsUnread:` would land on whatever MailMate selected
         # next (or be a silent no-op).
         if preserve_unread
-          $stdout.puts "preserve-read-state: re-marking #{eml_id}.eml unread (opening the mid: URL marks it read)"
+          say(opts, "preserve-read-state: re-marking #{eml_id}.eml unread (opening the mid: URL marks it read)")
           driver.perform("markAsUnread:")
         end
 
@@ -290,7 +345,7 @@ module Mailmate
             flags = opts[:dry_run] ? [] : current_flags(eml_id)
             has   = flags.include?("\\Flagged")
             if has == want
-              $stdout.puts "#{name}: already #{want ? "flagged" : "not flagged"} — no-op"
+              say(opts, "#{name}: already #{want ? "flagged" : "not flagged"} — no-op")
             else
               driver.perform("toggleFlag:")
             end
@@ -299,6 +354,32 @@ module Mailmate
           end
         end
 
+        # Opt-in effect verification (--check): re-read the TARGET eml-id's
+        # flags and confirm the actions actually landed there. This is the
+        # only check that catches a `mid:` open resolving to a different
+        # duplicate copy — AppleScript can't tell us which message it acted
+        # on, but the index can tell us whether OUR eml-id changed.
+        #
+        # NOT default: MailMate flushes #flags to disk ~5s after an
+        # AppleScript write (measured), so verify_effects polls up to
+        # check_timeout for the index to catch up. A default-on check would
+        # either false-fail (timeout too short) or slow every modify by
+        # several seconds (timeout long enough) — neither is acceptable for
+        # the common path, so the latency is paid only when asked for.
+        # Skipped for location-changing chains (the .eml leaves the viewer).
+        verified = true
+        if opts[:check] && !opts[:emit_check] && !opts[:dry_run] && (exps = verifiable_expectations(actions))
+          verified, flags = verify_effects(eml_id, exps, timeout: opts[:check_timeout])
+          if verified
+            $stdout.puts "verify: ✓ #{exps.size} effect(s) confirmed on #{eml_id}.eml — flags: #{flags.inspect}"
+          else
+            warn "verify: ✗ effect check FAILED on #{eml_id}.eml after #{opts[:check_timeout]}s — flags: #{flags.inspect}"
+            warn "        Expected: #{exps.map { |k, a| Mailmate::FlagCheck.label(k, a) }.join(", ")}"
+            warn "        The action may have landed on a different duplicate copy, or the index"
+            warn "        still hasn't flushed. Re-run, or raise --check-timeout."
+          end
+        end
+
         # --verify is now permitted in --dry-run mode so callers can use
         # `mm-modify <id> <any-action> --dry-run --verify` as a post-hoc
         # "what's the current flag state?" probe after a separate action run.
@@ -306,12 +387,70 @@ module Mailmate
         # flush #flags before we read it back; in dry-run no wait is needed.
         if opts[:verify]
           sleep(1) unless opts[:dry_run]
-          $stdout.puts "Flags now: #{current_flags(eml_id).inspect}"
+          say(opts, "Flags now: #{current_flags(eml_id).inspect}")
         end
 
         unless opts[:keep_window] || opts[:dry_run] || new_windows.empty?
           driver.close_windows(new_windows)
         end
+
+        verified
+      end
+
+      # Actions that relocate or destroy the .eml — its #flags record moves
+      # or disappears, so post-action flag verification isn't meaningful.
+      LOCATION_ACTIONS = %w[move archive delete junk not-junk].freeze
+
+      # Build the set of #flags expectations a chain should satisfy after it
+      # runs, or nil when the chain isn't effect-verifiable. Returns nil if:
+      #   - any action changes location (move/archive/delete/junk),
+      #   - clear-tags is mixed with tag/untag (order-dependent net state we
+      #     don't model — bail rather than risk a false failure),
+      #   - nothing in the chain is flag-observable.
+      # Later actions on the same flag win (last-write); `mute` is ignored
+      # (no clean #flags signal) without blocking the rest.
+      def verifiable_expectations(actions)
+        return nil if actions.any? { |name, _, _| LOCATION_ACTIONS.include?(name) }
+
+        exp = {}
+        has_clear = false
+        has_tagop = false
+        actions.each do |name, _, args|
+          case name
+          when "read"       then exp[:seen]    = [:seen, true]
+          when "unread"     then exp[:seen]    = [:seen, false]
+          when "flag"       then exp[:flagged] = [:flagged, true]
+          when "unflag"     then exp[:flagged] = [:flagged, false]
+          when "tag"        then has_tagop = true; exp["tag:#{args.first}"] = [:tag_present, args.first]
+          when "untag"      then has_tagop = true; exp["tag:#{args.first}"] = [:tag_absent, args.first]
+          when "clear-tags" then has_clear = true
+          end
+        end
+        return nil if has_clear && has_tagop
+        exp[:clear] = [:no_user_tags, nil] if has_clear
+        exp.empty? ? nil : exp.values
+      end
+
+      # Poll the target eml-id's flags until every expectation holds or the
+      # timeout elapses (success returns on the first satisfying read, so the
+      # common case is fast; only genuine failures wait out the timeout).
+      # Returns [met?, last_flags_seen].
+      def verify_effects(eml_id, expectations, timeout:, poll: 0.1)
+        deadline = Time.now + timeout
+        flags = nil
+        loop do
+          flags = current_flags(eml_id)
+          return [true, flags] if Mailmate::FlagCheck.all_met?(flags, expectations)
+          break if Time.now >= deadline
+          sleep(poll)
+        end
+        [false, flags]
+      end
+
+      # Thin delegator kept for the unit tests that target the predicate
+      # directly; the canonical logic lives in Mailmate::FlagCheck.
+      def flag_expectation_met?(flags, kind, arg)
+        Mailmate::FlagCheck.met?(flags, kind, arg)
       end
 
       # Poll for a new MailMate window appearing in `driver.window_ids` that