From 8f20f6f945f49460bf5f2d1090dae580a78c49a2 Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Tue, 7 Jul 2026 12:27:47 -0600
Subject: [PATCH] fix(em): flag/star dead-case-label bug + help discoverability
 (Phase 1+2)

Per SPEC-em-ux-refactor-2026-07-07.md, from this session's ADHD-UX audit
of em.

P0 fix: em()'s dispatch case statement had "star|flag)" bound to _em_star
in one section AND "flag|fl)" bound to _em_flag in another, earlier
section. Since zsh case matches top-down, `em flag` always resolved to
_em_flag (one-way add) and never reached _em_star's toggle logic --
the "flag" alias on the star arm was dead code. Fixed the routing so
each command name maps to exactly one function; also removed a harmless
duplicate `move|mv)` label. _em_star extended to accept multiple IDs
(toggling each independently against one consistent folder snapshot)
to match flag/unflag's existing batch capability.

Added tests/test-em-flag-star.zsh: routing regression tests (flag/star/
unflag each hit a distinct function), multi-ID parity tests, and a
grep-based dead-code guard that specifically detects the same case-label
word bound to two different handlers (not just any repeated word --
verified against a false positive on legitimate multi-word aliases).
Verified the guard actually catches this exact bug class via a planted-
defect positive control (reintroduced the old duplicate label, confirmed
the guard fails with the right message, restored the fix).

Phase 2: added `em help <topic>` (inbox/compose/organize/manage/safety/
ai/search) so users aren't stuck scanning a ~90-line dump for one thing;
no-arg `em help` output is unchanged. Documented the existing 3-tier
confirmation system ([y/N/e] / type "yes" / type folder name) in the
SAFETY section as an intentional design, not an incidental discovery.
Updated MASTER-DISPATCHER-GUIDE.md and the man page to match, including
fixing a duplicate `em move` reference row and a stale "em flag is an
alias for em star" note that mirrored the same underlying bug.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 CHANGELOG.md                              |   6 +
 docs/CHANGELOG.md                         |   6 +
 docs/reference/MASTER-DISPATCHER-GUIDE.md |   9 +-
 lib/dispatchers/email-dispatcher.zsh      | 156 ++++++++++++++++++---
 man/man1/em.1                             |  17 ++-
 tests/run-all.sh                          |   1 +
 tests/test-em-flag-star.zsh               | 160 ++++++++++++++++++++++
 7 files changed, 322 insertions(+), 33 deletions(-)
 create mode 100755 tests/test-em-flag-star.zsh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e11a5db20..2cc373de2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   upstream in favor of Antigravity/`agy`, but nothing is removed here.
 
 - **`tests/test-teach-dispatcher-characterization.zsh`** — 35 routing checks that mock action functions and verify every public `teach <cmd>` path before and after the split.
+- **`em help <topic>`** — filter help output to one section (`inbox`, `compose`, `organize`, `manage`, `safety`, `ai`, `search`) instead of the full ~90-line dump; unrecognized topics list the valid names. No-arg `em help` output is unchanged.
+- **`em help`'s SAFETY section** now documents the three confirmation tiers (`[y/N/e]` / type `yes` / type folder name) as an intentional graduated-friction design, not an incidental discovery.
+
+### Fixed
+
+- **`em flag`/`em star` dead-code bug** — a duplicate `case` label in `em()`'s dispatcher silently made `em flag` always resolve to the one-way `_em_flag` handler, never the toggle `_em_star` handler its `star|flag)` alias implied. Fixed the routing; `em flag`/`em unflag` remain one-way batch operations, `em star` remains the toggle — now also extended to accept multiple IDs like `flag`/`unflag` already did. See `docs/specs/SPEC-em-ux-refactor-2026-07-07.md`.
 
 ### Changed
 
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index a60bef042..3415a2f2a 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -19,6 +19,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/), and this pro
   upstream in favor of Antigravity/`agy`, but nothing is removed here.
 
 - **`tests/test-teach-dispatcher-characterization.zsh`** — 35 routing checks that mock action functions and verify every public `teach <cmd>` path before and after the split.
+- **`em help <topic>`** — filter help output to one section (`inbox`, `compose`, `organize`, `manage`, `safety`, `ai`, `search`) instead of the full ~90-line dump; unrecognized topics list the valid names. No-arg `em help` output is unchanged.
+- **`em help`'s SAFETY section** now documents the three confirmation tiers (`[y/N/e]` / type `yes` / type folder name) as an intentional graduated-friction design, not an incidental discovery.
+
+### Fixed
+
+- **`em flag`/`em star` dead-code bug** — a duplicate `case` label in `em()`'s dispatcher silently made `em flag` always resolve to the one-way `_em_flag` handler, never the toggle `_em_star` handler its `star|flag)` alias implied. Fixed the routing; `em flag`/`em unflag` remain one-way batch operations, `em star` remains the toggle — now also extended to accept multiple IDs like `flag`/`unflag` already did. See `docs/specs/SPEC-em-ux-refactor-2026-07-07.md`.
 
 ### Changed
 
diff --git a/docs/reference/MASTER-DISPATCHER-GUIDE.md b/docs/reference/MASTER-DISPATCHER-GUIDE.md
index c92e7c799..380404fd7 100644
--- a/docs/reference/MASTER-DISPATCHER-GUIDE.md
+++ b/docs/reference/MASTER-DISPATCHER-GUIDE.md
@@ -3300,10 +3300,10 @@ calendar ICS parsing, and IMAP IDLE background watching.
 | `em delete --purge <ID>` | | Permanent delete (requires typing "yes") |
 | `em create-folder <name>` | `em cf` | Create a new mail folder |
 | `em delete-folder <name>` | `em df` | Delete folder (type-to-confirm) |
-| `em move <FOLDER> <ID>` | `em mv` | Move email to folder |
+| `em move <ID> [FOLDER]` | `em mv` | Move email to folder (fzf picker if no folder) |
 | `em restore <ID>` | | Restore from Trash to INBOX |
-| `em flag <ID>` | `em fl` | Star email for follow-up |
-| `em unflag <ID>` | | Remove star |
+| `em flag <ID>...` | `em fl` | One-way: set starred (batch-capable) |
+| `em unflag <ID>...` | | One-way: clear starred (batch-capable) |
 | `em respond` | `em resp` | Batch AI drafts for actionable emails |
 | `em classify <ID>` | | AI category classification |
 | `em summarize <ID>` | `em sum` | One-line AI summary |
@@ -3321,9 +3321,8 @@ calendar ICS parsing, and IMAP IDLE background watching.
 | `em watch start\|stop\|status\|log` | `em w` | IMAP IDLE background watcher [experimental] |
 | `em cache stats\|prune\|clear\|warm` | | Manage AI cache |
 | `em ai [backend]` | | Show/switch AI backend (claude, agy, gemini legacy, none, toggle, auto) |
-| `em star <ID>` | `em flag` | Toggle star (Flagged) on email |
+| `em star <ID>...` | | Toggle starred status per-ID (batch-capable) |
 | `em starred` | | List all starred/flagged emails |
-| `em move <ID> [FOLDER]` | `em mv` | Move email to folder (fzf picker if no folder) |
 | `em thread <ID>` | `em th` | Show conversation thread for email |
 | `em snooze <ID> <TIME>` | `em snz` | Snooze email (2h, 1d, tomorrow, monday, etc.) |
 | `em snoozed` | | List snoozed emails with status |
diff --git a/lib/dispatchers/email-dispatcher.zsh b/lib/dispatchers/email-dispatcher.zsh
index 998c0d949..6c005f745 100644
--- a/lib/dispatchers/email-dispatcher.zsh
+++ b/lib/dispatchers/email-dispatcher.zsh
@@ -131,9 +131,8 @@ em() {
         # ─────────────────────────────────────────────────────────────
         # ORGANIZE
         # ─────────────────────────────────────────────────────────────
-        star|flag)    shift; _em_star "$@" ;;
+        star)         shift; _em_star "$@" ;;
         starred)      shift; _em_starred "$@" ;;
-        move|mv)      shift; _em_move "$@" ;;
         thread|th)    shift; _em_thread "$@" ;;
         snooze|snz)   shift; _em_snooze "$@" ;;
         snoozed)      shift; _em_snoozed "$@" ;;
@@ -163,7 +162,7 @@ em() {
         # ─────────────────────────────────────────────────────────────
         # HELP
         # ─────────────────────────────────────────────────────────────
-        help|h|--help|-h) _em_help ;;
+        help|h|--help|-h) shift; _em_help "$@" ;;
 
         *)
             _flow_log_error "Unknown command: $1"
@@ -177,7 +176,112 @@ em() {
 # HELP SYSTEM
 # ═══════════════════════════════════════════════════════════════════
 
+_em_help_topic() {
+    # Print just one section of `em help`, for `em help <topic>`.
+    # Returns 1 (unhandled) for an unrecognized topic so the caller can
+    # fall back to the full help dump.
+    local topic="${1:l}"
+    case "$topic" in
+        inbox|reading)
+            echo -e "
+${_C_BLUE}📋 INBOX & READING${_C_NC}:
+  ${_C_CYAN}em inbox [N]${_C_NC}      List N recent emails (default: ${FLOW_EMAIL_PAGE_SIZE})
+  ${_C_CYAN}em read <ID>${_C_NC}      Read email (smart rendering)
+  ${_C_CYAN}em read --html <ID>${_C_NC} Read HTML version (w3m/lynx)
+  ${_C_CYAN}em read --md <ID>${_C_NC}   Read as clean Markdown (pandoc)
+  ${_C_CYAN}em read --raw <ID>${_C_NC}  Dump raw MIME source
+  ${_C_CYAN}em unread${_C_NC}         Show unread count
+  ${_C_CYAN}em html <ID>${_C_NC}      Render HTML email ${_C_DIM}(alias for read --html)${_C_NC}
+"
+            ;;
+        compose|reply)
+            echo -e "
+${_C_BLUE}COMPOSE & REPLY${_C_NC}:
+  ${_C_CYAN}em send${_C_NC}           Compose new (opens \$EDITOR, preview before send)
+  ${_C_CYAN}em send --force${_C_NC}   Compose + send without preview
+  ${_C_CYAN}em reply <ID>${_C_NC}     Reply with AI draft (--no-ai, --all, --batch, --force)
+  ${_C_CYAN}em forward <ID> [to]${_C_NC} Forward email (--prompt, --backend, --force)
+"
+            ;;
+        organize)
+            echo -e "
+${_C_BLUE}ORGANIZE${_C_NC}:
+  ${_C_CYAN}em star <ID>...${_C_NC}  Toggle starred (flagged) status (per-ID)
+  ${_C_CYAN}em starred${_C_NC}       List starred emails
+  ${_C_CYAN}em thread <ID>${_C_NC}   Show conversation thread
+  ${_C_CYAN}em snooze <ID> <T>${_C_NC} Snooze (2h, 1d, tomorrow, monday)
+  ${_C_CYAN}em snoozed${_C_NC}       List snoozed emails
+  ${_C_CYAN}em digest${_C_NC}        AI-grouped daily summary (--week)
+
+${_C_DIM}Related: em flag/em unflag are one-way set/clear (batch-capable);${_C_NC}
+${_C_DIM}em star is the toggle (also batch-capable) — see 'em help manage'${_C_NC}
+"
+            ;;
+        manage)
+            echo -e "
+${_C_BLUE}MANAGE${_C_NC}:
+  ${_C_CYAN}em delete <ID>${_C_NC}       Delete email (move to Trash)
+  ${_C_CYAN}em delete --pick${_C_NC}     Interactive multi-select delete
+  ${_C_CYAN}em delete --purge${_C_NC}    Permanent delete (requires \"yes\")
+  ${_C_CYAN}em move <ID> [F]${_C_NC}    Move to folder (fzf picker if no folder)
+  ${_C_CYAN}em restore <ID>${_C_NC}     Restore from Trash to INBOX
+  ${_C_CYAN}em flag <ID>...${_C_NC}     One-way: set starred (batch-capable)
+  ${_C_CYAN}em unflag <ID>...${_C_NC}   One-way: clear starred (batch-capable)
+"
+            ;;
+        safety)
+            echo -e "
+${_C_MAGENTA}SAFETY${_C_NC}: Three tiers of confirmation, scaled to how reversible the action is:
+  ${_C_DIM}1. Reversible (delete)${_C_NC}       ${_C_YELLOW}[y/N/e]${_C_NC} single keypress (default: No, e=edit)
+  ${_C_DIM}2. Irreversible (--purge)${_C_NC}     Type the word ${_C_YELLOW}yes${_C_NC} in full
+  ${_C_DIM}3. Bulk irreversible (delete-folder)${_C_NC} Type the folder name in full
+  Send/reply/forward use the same two-phase gate as tier 1: preview then ${_C_YELLOW}[y/N/e]${_C_NC}.
+"
+            ;;
+        ai)
+            echo -e "
+${_C_BLUE}AI-POWERED COMPOSITION${_C_NC}:
+  ${_C_CYAN}em reply <ID> --prompt 'instructions'${_C_NC}       AI draft with custom instructions
+  ${_C_CYAN}em send <to> <subj> --prompt 'instructions'${_C_NC} AI compose from instructions
+  ${_C_CYAN}em forward <ID> <to> --prompt 'text'${_C_NC}        AI forward with custom note
+  ${_C_DIM}--backend claude|agy|gemini${_C_NC}                 Override AI backend per-command
+
+${_C_BLUE}AI BACKEND${_C_NC}:
+  ${_C_CYAN}em ai${_C_NC}              Show current AI backend
+  ${_C_CYAN}em ai claude${_C_NC}       Switch to Claude
+  ${_C_CYAN}em ai agy${_C_NC}          Switch to Antigravity (agy)
+  ${_C_CYAN}em ai gemini${_C_NC}       Switch to Gemini (legacy)
+  ${_C_CYAN}em ai none${_C_NC}         Disable AI
+  ${_C_CYAN}em ai toggle${_C_NC}       Cycle backends
+  ${_C_CYAN}em ai auto${_C_NC}         Smart per-op routing
+
+${_C_MAGENTA}CURRENT${_C_NC}: \$FLOW_EMAIL_AI=${_C_CYAN}${FLOW_EMAIL_AI}${_C_NC}  ${_C_DIM}Timeout: ${FLOW_EMAIL_AI_TIMEOUT}s${_C_NC}
+"
+            ;;
+        search|browse)
+            echo -e "
+${_C_BLUE}SEARCH & BROWSE${_C_NC}:
+  ${_C_CYAN}em find <query>${_C_NC}   Search emails
+  ${_C_CYAN}em pick [FOLDER]${_C_NC}  fzf browser with preview
+"
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+    return 0
+}
+
 _em_help() {
+    if [[ -n "$1" ]]; then
+        if _em_help_topic "$1"; then
+            return 0
+        fi
+        _flow_log_error "Unknown help topic: $1"
+        echo "Topics: inbox, compose, organize, manage, safety, ai, search"
+        echo "Run ${_C_CYAN}em help${_C_NC} for the full command reference"
+        return 1
+    fi
     echo -e "
 ${_C_BOLD}╭─────────────────────────────────────────────╮${_C_NC}
 ${_C_BOLD}│ em - Email Dispatcher (himalaya)             │${_C_NC}
@@ -239,7 +343,7 @@ ${_C_BLUE}WATCH${_C_NC} ${_C_DIM}[experimental]${_C_NC}:
   ${_C_CYAN}em watch log${_C_NC}       Show recent notifications
 
 ${_C_BLUE}ORGANIZE${_C_NC}:
-  ${_C_CYAN}em star <ID>${_C_NC}     Toggle starred (flagged) status
+  ${_C_CYAN}em star <ID>...${_C_NC}  Toggle starred (flagged) status (per-ID)
   ${_C_CYAN}em starred${_C_NC}       List starred emails
   ${_C_CYAN}em thread <ID>${_C_NC}   Show conversation thread
   ${_C_CYAN}em snooze <ID> <T>${_C_NC} Snooze (2h, 1d, tomorrow, monday)
@@ -252,8 +356,8 @@ ${_C_BLUE}MANAGE${_C_NC}:
   ${_C_CYAN}em delete --purge${_C_NC}    Permanent delete (requires \"yes\")
   ${_C_CYAN}em move <ID> [F]${_C_NC}    Move to folder (fzf picker if no folder)
   ${_C_CYAN}em restore <ID>${_C_NC}     Restore from Trash to INBOX
-  ${_C_CYAN}em flag <ID>${_C_NC}        Star for follow-up
-  ${_C_CYAN}em unflag <ID>${_C_NC}      Remove star
+  ${_C_CYAN}em flag <ID>...${_C_NC}     One-way: set starred (batch-capable)
+  ${_C_CYAN}em unflag <ID>...${_C_NC}   One-way: clear starred (batch-capable)
 
 ${_C_BLUE}AI FEATURES${_C_NC}:
   ${_C_CYAN}em respond${_C_NC}        Batch AI drafts for actionable emails
@@ -275,7 +379,11 @@ ${_C_BLUE}INFO & MANAGEMENT${_C_NC}:
   ${_C_CYAN}em cache clear${_C_NC}    Clear AI cache
   ${_C_CYAN}em doctor${_C_NC}         Check dependencies
 
-${_C_MAGENTA}SAFETY${_C_NC}: Two-phase gate — preview then ${_C_YELLOW}[y/N/e]${_C_NC} confirm (default: No, e=edit)
+${_C_MAGENTA}SAFETY${_C_NC}: Three tiers of confirmation, scaled to how reversible the action is:
+  ${_C_DIM}1. Reversible (delete)${_C_NC}       ${_C_YELLOW}[y/N/e]${_C_NC} single keypress (default: No, e=edit)
+  ${_C_DIM}2. Irreversible (--purge)${_C_NC}     Type the word ${_C_YELLOW}yes${_C_NC} in full
+  ${_C_DIM}3. Bulk irreversible (delete-folder)${_C_NC} Type the folder name in full
+  Send/reply/forward use the same two-phase gate as tier 1: preview then ${_C_YELLOW}[y/N/e]${_C_NC}.
 
 ${_C_BLUE}AI-POWERED COMPOSITION${_C_NC}:
   ${_C_CYAN}em reply <ID> --prompt 'instructions'${_C_NC}       AI draft with custom instructions
@@ -2337,27 +2445,33 @@ ${_C_DIM}Safety: every send requires explicit [y/N] confirmation${_C_NC}
 _em_star() {
     [[ "$1" == "--help" || "$1" == "-h" || "$1" == "help" ]] && { _em_help; return 0; }
     _em_require_himalaya || return 1
-    local msg_id="$1"
-    if [[ -z "$msg_id" ]]; then
+    if [[ $# -eq 0 ]]; then
         _flow_log_error "Email ID required"
-        echo "Usage: ${_C_CYAN}em star <ID>${_C_NC}"
+        echo "Usage: ${_C_CYAN}em star <ID> [<ID>...]${_C_NC}"
         return 1
     fi
 
     local folder="${FLOW_EMAIL_FOLDER:-INBOX}"
 
-    # Check current flags to determine toggle direction
-    local flags
-    flags=$(_em_hml_list "$folder" 100 2>/dev/null \
-        | jq -r --arg id "$msg_id" '.[] | select(.id == ($id | tonumber)) | .flags | join(",")' 2>/dev/null)
+    # Fetch the folder's envelope list once so every ID toggles against the
+    # same consistent snapshot (mixed starting states -> mixed correct end
+    # states, independent of each other).
+    local envelopes
+    envelopes=$(_em_hml_list "$folder" 100 2>/dev/null)
 
-    if [[ "$flags" == *"Flagged"* ]]; then
-        _em_hml_flags remove "$msg_id" Flagged
-        echo -e "  ${_C_DIM}☆${_C_NC} Unstarred #${msg_id}"
-    else
-        _em_hml_flags add "$msg_id" Flagged
-        echo -e "  ${_C_YELLOW}★${_C_NC} Starred #${msg_id}"
-    fi
+    local msg_id flags
+    for msg_id in "$@"; do
+        flags=$(echo "$envelopes" \
+            | jq -r --arg id "$msg_id" '.[] | select(.id == ($id | tonumber)) | .flags | join(",")' 2>/dev/null)
+
+        if [[ "$flags" == *"Flagged"* ]]; then
+            _em_hml_flags remove "$msg_id" Flagged
+            echo -e "  ${_C_DIM}☆${_C_NC} Unstarred #${msg_id}"
+        else
+            _em_hml_flags add "$msg_id" Flagged
+            echo -e "  ${_C_YELLOW}★${_C_NC} Starred #${msg_id}"
+        fi
+    done
 }
 
 _em_starred() {
diff --git a/man/man1/em.1 b/man/man1/em.1
index 30a665c07..962ee8641 100644
--- a/man/man1/em.1
+++ b/man/man1/em.1
@@ -146,15 +146,15 @@ Move email to folder. Opens fzf folder picker if FOLDER is omitted.
 .B restore \fIID\fR
 Restore email from Trash to INBOX.
 .TP
-.B flag\fR, \fBfl \fIID\fR
-Star email for follow-up.
+.B flag\fR, \fBfl \fIID\fR...
+One-way: set starred status (batch-capable, multiple IDs allowed).
 .TP
-.B unflag \fIID\fR
-Remove star from email.
+.B unflag \fIID\fR...
+One-way: clear starred status (batch-capable, multiple IDs allowed).
 .SS Organize
 .TP
-.B star \fIID\fR
-Toggle starred (flagged) status.
+.B star \fIID\fR...
+Toggle starred status per-ID (batch-capable, multiple IDs allowed).
 .TP
 .B starred
 List all starred emails.
@@ -273,7 +273,10 @@ Clear the AI draft cache.
 Check all email-related dependencies (himalaya, w3m/lynx, pandoc, AI CLIs).
 .TP
 .B help\fR, \fBh\fR, \fB--help\fR, \fB-h
-Show help page.
+Show full help page.
+.TP
+.B help \fITOPIC\fR
+Show help for one topic only (inbox, compose, organize, manage, safety, ai, search).
 .SH ENVIRONMENT
 .TP
 .B FLOW_EMAIL_AI
diff --git a/tests/run-all.sh b/tests/run-all.sh
index abdf5a7a0..1e36a59e6 100755
--- a/tests/run-all.sh
+++ b/tests/run-all.sh
@@ -82,6 +82,7 @@ run_test ./tests/test-dot-chezmoi-safety.zsh
 run_test ./tests/test-em-dispatcher.zsh
 run_test ./tests/test-em-prompt-flag.zsh
 run_test ./tests/test-em-help-guards.zsh
+run_test ./tests/test-em-flag-star.zsh
 run_test ./tests/test-em-ai-switch.zsh
 run_test ./tests/test-em-ai-agy.zsh
 run_test ./tests/test-tok.zsh
diff --git a/tests/test-em-flag-star.zsh b/tests/test-em-flag-star.zsh
new file mode 100755
index 000000000..4997f64b9
--- /dev/null
+++ b/tests/test-em-flag-star.zsh
@@ -0,0 +1,160 @@
+#!/usr/bin/env zsh
+# ══════════════════════════════════════════════════════════════════════════════
+# TEST SUITE: em flag/star/unflag routing + dead-case-label regression guard
+# ══════════════════════════════════════════════════════════════════════════════
+#
+# Purpose: Regression guard for SPEC-em-ux-refactor-2026-07-07.md — a duplicate
+#          `case` label (`star|flag)`) previously made `em flag` silently
+#          unreachable to `_em_star`'s toggle logic; `em flag` always resolved
+#          to `_em_flag` (one-way add) regardless. Confirms flag/star/unflag
+#          each route to a distinct function, and that em star supports
+#          multiple IDs like flag/unflag do.
+#
+# Created: 2026-07-07
+# ══════════════════════════════════════════════════════════════════════════════
+
+SCRIPT_DIR="${0:A:h}"
+PROJECT_ROOT="${SCRIPT_DIR:h}"
+source "$SCRIPT_DIR/test-framework.zsh" || { echo "ERROR: Cannot source test-framework.zsh"; exit 1 }
+
+setup() {
+    typeset -g project_root=""
+    if [[ -n "${0:A}" ]]; then project_root="${0:A:h:h}"; fi
+    if [[ -z "$project_root" || ! -f "$project_root/flow.plugin.zsh" ]]; then
+        if [[ -f "$PWD/flow.plugin.zsh" ]]; then project_root="$PWD"
+        elif [[ -f "$PWD/../flow.plugin.zsh" ]]; then project_root="$PWD/.."
+        fi
+    fi
+    [[ -z "$project_root" || ! -f "$project_root/flow.plugin.zsh" ]] && { echo "ERROR: Cannot find project root"; exit 1; }
+
+    FLOW_QUIET=1
+    FLOW_ATLAS_ENABLED=no
+    FLOW_PLUGIN_DIR="$project_root"
+    exec < /dev/null
+    source "$project_root/flow.plugin.zsh"
+}
+
+cleanup() {
+    reset_mocks
+}
+trap cleanup EXIT
+
+# ═══════════════════════════════════════════════════════════════
+# Section 1: Dispatch routing — flag/star/unflag hit distinct functions
+# ═══════════════════════════════════════════════════════════════
+
+test_flag_routes_to_em_flag_only() {
+    test_case "em flag routes to _em_flag, not _em_star"
+    create_mock "_em_flag"
+    create_mock "_em_star"
+    em flag 42 &>/dev/null
+    assert_mock_called "_em_flag" 1 && \
+    assert_mock_not_called "_em_star" && \
+    test_pass
+    reset_mocks
+}
+
+test_star_routes_to_em_star_only() {
+    test_case "em star routes to _em_star, not _em_flag"
+    create_mock "_em_flag"
+    create_mock "_em_star"
+    em star 42 &>/dev/null
+    assert_mock_called "_em_star" 1 && \
+    assert_mock_not_called "_em_flag" && \
+    test_pass
+    reset_mocks
+}
+
+test_unflag_routes_to_em_unflag() {
+    test_case "em unflag routes to _em_unflag"
+    create_mock "_em_unflag"
+    em unflag 42 &>/dev/null
+    assert_mock_called "_em_unflag" 1 && test_pass
+    reset_mocks
+}
+
+test_star_receives_multiple_ids() {
+    test_case "em star 42 43 passes both IDs to _em_star"
+    create_mock "_em_star"
+    em star 42 43 &>/dev/null
+    assert_mock_args "_em_star" "42 43" && test_pass
+    reset_mocks
+}
+
+test_flag_receives_multiple_ids() {
+    test_case "em flag 42 43 passes both IDs to _em_flag (unchanged behavior)"
+    create_mock "_em_flag"
+    em flag 42 43 &>/dev/null
+    assert_mock_args "_em_flag" "42 43" && test_pass
+    reset_mocks
+}
+
+# ═══════════════════════════════════════════════════════════════
+# Section 2: No duplicate case labels in the em() dispatch block
+# ═══════════════════════════════════════════════════════════════
+# Guard against this exact bug class recurring for any future command.
+# Detects the same label WORD bound to two DIFFERENT handler functions in
+# two different case arms — not just any repeated word (legitimate aliases
+# like `flag|fl)` binding one handler are valid and must not false-positive).
+
+test_no_duplicate_case_labels_in_em_dispatch() {
+    test_case "em() dispatch has no word bound to two different handlers"
+
+    local dispatcher_file="$project_root/lib/dispatchers/email-dispatcher.zsh"
+    local em_block
+    # Extract the em() function body up to its closing brace at column 0.
+    em_block=$(awk '/^em\(\) \{/{f=1} f{print} f && /^}/{exit}' "$dispatcher_file")
+
+    # Collect "word) ... handler ;;" and "word|alias) ... handler ;;" arms,
+    # split each arm's pipe-separated labels into individual words, and
+    # track which handler function each word maps to.
+    local -A word_to_handler
+    local dup_found=""
+    local line word_list handler w
+
+    while IFS= read -r line; do
+        [[ "$line" =~ '^[[:space:]]*([A-Za-z_|-]+)\)[[:space:]]+shift;[[:space:]]+([A-Za-z_]+)' ]] || continue
+        word_list="${match[1]}"
+        handler="${match[2]}"
+        for w in ${(s:|:)word_list}; do
+            if [[ -n "${word_to_handler[$w]:-}" && "${word_to_handler[$w]}" != "$handler" ]]; then
+                dup_found="word '$w' bound to both '${word_to_handler[$w]}' and '$handler'"
+            fi
+            word_to_handler[$w]="$handler"
+        done
+    done <<< "$em_block"
+
+    if [[ -n "$dup_found" ]]; then
+        test_fail "$dup_found"
+    else
+        test_pass
+    fi
+}
+
+# ═══════════════════════════════════════════════════════════════
+# MAIN
+# ═══════════════════════════════════════════════════════════════
+
+main() {
+    test_suite_start "em flag/star/unflag routing + dead-case-label guard"
+
+    setup
+
+    echo "${CYAN}Section 1: Dispatch routing${RESET}"
+    test_flag_routes_to_em_flag_only
+    test_star_routes_to_em_star_only
+    test_unflag_routes_to_em_unflag
+    test_star_receives_multiple_ids
+    test_flag_receives_multiple_ids
+    echo ""
+
+    echo "${CYAN}Section 2: No duplicate case labels${RESET}"
+    test_no_duplicate_case_labels_in_em_dispatch
+    echo ""
+
+    cleanup
+    test_suite_end
+    exit $?
+}
+
+main