Validate the binary and RPC support:

```bash
imsg rpc --help
imsg status --json
apus channels status --probe
```

If the check reports RPC unsupported, update `imsg`. If private API actions are unavailable, run `imsg launch` in the logged-in macOS user session and check again. If the Gateway is not running on macOS, use the [Remote Mac over SSH](/channels/imessage/setup#remote-mac-over-ssh) setup instead of the default local `imsg` path.

First prove whether the message reached the local Mac. If `chat.db` does not change, Apus cannot receive the message even when `imsg status --json` reports a healthy bridge.

imsg chats --limit 10 --json
imsg watch --chat-id <chat-id> --json
sqlite3 ~/Library/Messages/chat.db \
  "select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

If phone-sent messages create no new rows, repair the macOS Messages and Apple Push layer before changing Apus config. A one-shot service refresh is often enough:

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
apus gateway restart

Send a fresh iMessage from the phone and confirm a new `chat.db` row or `imsg watch` event before debugging Apus sessions. Do not run this as a periodic bridge-relaunch loop; repeated `imsg launch` plus gateway restarts during active work can interrupt deliveries and strand in-flight channel runs.

The default `cliPath: "imsg"` must run on the Mac signed into Messages. On Linux or Windows, set `channels.imessage.cliPath` to a wrapper script that SSHes to that Mac and runs `imsg "$@"`.

#!/usr/bin/env bash
exec ssh -T messages-mac imsg "$@"

Then run:

apus channels status --probe --channel imessage

Check:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- pairing approvals (`apus pairing list imessage`)

Check:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups` allowlist behavior
- mention gating: explicit patterns or the routed agent's identity name/emoji; set `requireMention: false` for the chat in the effective root or account `groups` map to process all messages from allowed senders

Check:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- SSH/SCP key auth from the gateway host
- host key exists in `~/.ssh/known_hosts` on the gateway host
- remote path readability on the Mac running Messages

Re-run in an interactive GUI terminal in the same user/session context and approve prompts:

```bash
imsg chats --limit 1
imsg send <handle> "test"
```

Confirm Full Disk Access + Automation are granted for the process context that runs Apus/`imsg`.