agent-messenger 2.27.1 → 2.28.0

package/skills/agent-imessage/references/authentication.md

@@ -0,0 +1,66 @@
+# Authentication
+
+iMessage authentication is unlike the other platforms: there are **no tokens, cookies, or login flow**. `agent-imessage` drives the local [imsg](https://github.com/openclaw/imsg) tool, which relies on **macOS permissions** (Full Disk Access + Automation) granted to the process that launches it. "Authentication" here means: imsg is installed, Messages.app is signed into your Apple ID, and the permissions are granted.
+
+## What gets stored
+
+The credential manager stores an **account record with no secrets** in `~/.config/agent-messenger/imessage-credentials.json` (mode `0600`):
+
+```jsonc
+{
+  "current": "default",
+  "accounts": {
+    "default": {
+      "account_id": "default",
+      "provider": "imsg",          // backend-agnostic discriminator
+      "binary_path": "/opt/homebrew/bin/imsg",  // optional; defaults to "imsg" on PATH
+      "region": "US",               // optional; default region for local-format phone numbers
+      "created_at": "…",
+      "updated_at": "…"
+    }
+  }
+}
+```
+
+There is no password/token field — access is governed entirely by macOS TCC permissions.
+
+## Configuring an account
+
+Guided:
+```bash
+agent-imessage setup            # verifies imsg + permissions (honors --bin/--region), then saves
+```
+
+Scriptable:
+```bash
+agent-imessage auth set --bin /opt/homebrew/bin/imsg --region US --current
+agent-imessage auth status      # via: agent-imessage doctor
+agent-imessage auth list
+agent-imessage auth use <account-id>
+agent-imessage auth remove <account-id>
+agent-imessage auth logout      # clears all stored accounts
+```
+
+## Credential resolution order
+
+When a command runs, the active configuration is resolved as:
+
+1. `--account <id>` (explicit account selection), then
+2. `AGENT_IMESSAGE_BIN` / `AGENT_IMESSAGE_REGION` environment variables (runtime override — **never persisted to disk**), then
+3. the stored **current** account, then
+4. defaults (`imsg` on PATH, no region).
+
+If nothing resolves, commands exit with `{ "code": "not_authenticated" }` and point to `agent-imessage setup`.
+
+## Permissions (the real "auth")
+
+imsg needs two macOS permissions, granted to the **parent process** (the terminal / agent runtime that launches `agent-messenger`), not to `imsg` in isolation:
+
+- **Full Disk Access** — to read `~/Library/Messages/chat.db`. Missing → `{ "code": "full_disk_access" }`.
+- **Automation → Messages** — to send. Missing → `{ "code": "automation_denied" }`.
+
+These are user-consent TCC grants and **cannot be scripted**. See [permissions](permissions.md) for the exact steps and the parent-process caveat. Run `agent-imessage doctor` to check status.
+
+## Multi-account
+
+Each account is an imsg configuration (binary path + default region). Messages.app has no from-selector, so **send is single-account per Mac**; multiple accounts are only meaningful if you run distinct imsg setups.

package/skills/agent-imessage/references/permissions.md

@@ -0,0 +1,31 @@
+# macOS Permissions for imsg
+
+`agent-imessage` drives [imsg](https://github.com/openclaw/imsg), which needs two macOS permissions. These are TCC (Transparency, Consent, and Control) grants that **cannot be scripted** — a human must approve them once in System Settings.
+
+## Full Disk Access (required for everything)
+
+imsg reads the Messages database at `~/Library/Messages/chat.db`, which macOS protects behind Full Disk Access.
+
+- **Grant to:** the app/terminal/agent-runtime that launches `agent-messenger` — **the parent process**, not `imsg` alone.
+- **Where:** System Settings → Privacy & Security → Full Disk Access → enable your terminal/app → restart it.
+- **Symptom when missing:** `agent-imessage doctor` reports `full_disk_access: denied`; commands return `{ "code": "full_disk_access" }`.
+
+## Automation → Messages (required to send)
+
+Sending uses AppleScript automation of Messages.app.
+
+- **Grant to:** same parent process.
+- **Where:** System Settings → Privacy & Security → Automation → (your app) → enable **Messages**. macOS prompts automatically on the first send attempt.
+- **Symptom when missing:** sends fail with `{ "code": "automation_denied" }`.
+
+## Contacts (optional)
+
+Used only to resolve sender names. Nothing breaks without it; `from_name` is simply absent.
+
+## Why these can't be automated
+
+TCC grants are deliberately user-consent-only. `tccutil` can reset permissions but cannot grant them, and the TCC database is protected by SIP. There is no supported way to grant Full Disk Access or Automation programmatically on an unmanaged Mac — plan for a one-time manual approval (a quick Screen Sharing/VNC session works for a headless Mac).
+
+## SIP and the advanced bridge
+
+Core features (send/read/watch/standard tapbacks) need **no SIP changes**. Only the advanced bridge (`imsg launch`: typing, edit/unsend, group management, targeted/custom reactions) requires **disabling SIP**, which is a separate, deliberate step and out of scope for the core `agent-imessage` features.

package/skills/agent-imessage/references/setup.md

@@ -0,0 +1,49 @@
+# imsg Setup (Operator Guide)
+
+iMessage has no public API. `agent-imessage` runs **on a Mac** and uses [imsg](https://github.com/openclaw/imsg) — a native Swift CLI — to read the local Messages database and send through Messages.app. The agent must run on the same Mac (imsg is local-only; there is no network/server).
+
+## Requirements
+
+- **macOS 14+** (Sonoma or newer). imsg supports macOS 26/Tahoe with caveats (group sends via AppleScript can fail; imsg reports the failure honestly rather than lying).
+- **Messages.app signed in** to your Apple ID. A **dedicated Apple ID** is recommended to avoid mixing automated traffic with your personal account.
+- **imsg installed**: `brew install steipete/tap/imsg`.
+- **Full Disk Access** and **Automation → Messages** permissions (see below).
+
+## One-time setup
+
+1. **Install imsg**
+   ```bash
+   brew install steipete/tap/imsg
+   imsg --version
+   ```
+2. **Sign Messages.app into iMessage** with your (dedicated) Apple ID.
+3. **Grant Full Disk Access** — System Settings → Privacy & Security → Full Disk Access → add the app/terminal that will launch `agent-messenger`. This is required to read `~/Library/Messages/chat.db`.
+4. **Grant Automation → Messages** — triggered on first send; approve the prompt (System Settings → Privacy & Security → Automation → Messages).
+5. **Verify and save an account**
+   ```bash
+   agent-imessage setup      # guided: checks imsg + permissions, saves account
+   agent-imessage doctor     # re-check anytime
+   ```
+
+### The parent-process permission caveat (important)
+
+macOS grants Full Disk Access and Automation to the **process that launches imsg** — i.e. the terminal, IDE, or agent runtime that runs `agent-imessage`, not `imsg` in isolation. If `doctor` reports `full_disk_access: denied`, grant Full Disk Access to **that launching app** and restart it.
+
+## Feature tiers
+
+- **Core (no SIP):** list/search chats, read history, send text, watch new messages, standard tapbacks (to the most recent incoming message). This is all that `agent-imessage` v1 uses.
+- **Bridge (advanced):** typing indicators, read receipts, edit/unsend, group create/rename/members, and reacting to a *specific* message or with custom emoji. These require `imsg launch` (which injects into IMCore) and **disabling SIP**. Not used by v1; documented for completeness.
+
+## Multi-account
+
+Each `agent-imessage` account is an imsg configuration (binary path + default region). Messages.app has no from-selector, so **send is single-account** per Mac. Configure additional accounts only if you run multiple imsg binaries/setups:
+```bash
+agent-imessage auth set --bin /opt/homebrew/bin/imsg --region US --account home --current
+agent-imessage auth use home
+```
+
+## Reliability notes
+
+- The Mac must stay awake and logged in for live `watch` to keep receiving.
+- imsg's watcher uses filesystem events + polling and re-arms across Messages database (WAL) rotation, so it keeps up on busy/iCloud-synced databases.
+- Pin macOS updates if stability matters — major updates can change AppleScript/IMCore behavior.

package/skills/agent-instagram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-instagram
 description: Interact with Instagram DMs - send messages, read conversations, manage accounts
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-instagram:*)
 metadata:
   openclaw:
@@ -27,7 +27,7 @@ Use one of these entrypoints:
 - **Thread ID** = Instagram's identifier for a DM conversation. Numeric string returned by `chat list`.
 - **Browser cookie extraction** = recommended auth method. Extracts cookies from Chromium browsers (Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium) where you're logged into instagram.com. Zero-config.
 - **Username/password auth** = fallback method. Authenticates using Instagram credentials. Supports two-factor authentication via SMS or authenticator app.
-- **HTTP-based** = each command makes HTTP requests and returns. No persistent connection or background process.
+- **HTTP-based** = each CLI command makes HTTP requests and returns. No persistent connection or background process. The SDK additionally offers real-time listeners (`InstagramHybridListener`, `InstagramRealtimeListener`) for streaming DMs — see [SDK: Real-Time Events](#sdk-real-time-events) below.
 - **Multi-account** = multiple Instagram accounts can be stored. Use `auth list` and `auth use` to switch between them.
 - **DM-only** = this CLI focuses on Instagram Direct Messages. It does not manage posts, stories, or followers.
 
@@ -440,3 +440,73 @@ Instagram invalidates sessions based on device fingerprinting and activity patte
 1. Avoid frequent re-authentication
 2. Space out API calls
 3. Don't switch between multiple IP addresses rapidly
+
+## SDK: Real-Time Events
+
+`InstagramHybridListener` connects over Instagram's MQTToT transport (a persistent TLS connection to `edge-mqtt.facebook.com`) and falls back to polling automatically if the connection fails. It retries realtime with capped exponential backoff. This is the recommended listener for most use cases.
+
+`InstagramRealtimeListener` is the pure-realtime option with no polling fallback — use it when you want direct MQTToT and prefer to handle reconnection yourself.
+
+Both use the unofficial private API, the same risk surface as the existing polling listener.
+
+### Setup
+
+```typescript
+import { InstagramClient, InstagramHybridListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramHybridListener(client, {
+  pollInterval: 5000,         // fallback poll interval in ms
+  realtimeRetryBaseMs: 2000,  // backoff base for realtime reconnect
+  realtimeRetryMaxMs: 60000,  // backoff cap
+})
+```
+
+Or for pure realtime:
+
+```typescript
+import { InstagramClient, InstagramRealtimeListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramRealtimeListener(client)
+```
+
+### Listening for Events
+
+```typescript
+listener.on('connected', ({ userId, transport }) => {
+  // transport is 'realtime' or 'polling' (hybrid only)
+  console.log(`Listening as ${userId} via ${transport}`)
+})
+
+listener.on('message', (msg) => {
+  // msg.id, msg.thread_id, msg.from, msg.timestamp
+  // msg.is_outgoing, msg.type, msg.text, msg.media_url
+  if (msg.is_outgoing) return
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text}`)
+})
+
+listener.on('error', (err) => {
+  console.error(err.message)
+})
+
+listener.on('disconnected', () => {
+  // hybrid listener retries realtime automatically
+})
+```
+
+### Lifecycle
+
+```typescript
+await listener.start()  // connects via MQTToT (or starts polling fallback)
+listener.stop()         // clean shutdown
+```
+
+### Event Types
+
+| Event          | Payload (Hybrid)                                          | Payload (Realtime / Polling) | Description                    |
+| -------------- | --------------------------------------------------------- | ---------------------------- | ------------------------------ |
+| `message`      | `InstagramMessageSummary`                                 | `InstagramMessageSummary`    | New DM received                |
+| `connected`    | `{ userId: string; transport: 'realtime' \| 'polling' }` | `{ userId: string }`         | Listener active                |
+| `disconnected` | —                                                         | —                            | Connection closed              |
+| `error`        | `Error`                                                   | `Error`                      | Connection or API error        |

package/skills/agent-instagram/references/common-patterns.md

@@ -323,6 +323,39 @@ agent-instagram message send-to alice "Hello!"
 agent-instagram message send 12345678901 "Hello!"
 ```
 
+## Pattern 11: Real-Time DM Monitor (SDK)
+
+**Use case**: Receive new DMs as they arrive, without polling
+
+The SDK's `InstagramHybridListener` is the right tool for continuous DM monitoring. It connects over Instagram's MQTToT transport and falls back to polling automatically — no manual loop or `sleep` needed.
+
+```typescript
+import { InstagramClient, InstagramHybridListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramHybridListener(client)
+
+listener.on('connected', ({ userId, transport }) => {
+  console.log(`Listening as ${userId} via ${transport}`)
+})
+
+listener.on('message', (msg) => {
+  if (msg.is_outgoing) return
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text ?? `[${msg.type}]`}`)
+})
+
+listener.on('error', (err) => {
+  console.error('Listener error:', err.message)
+})
+
+await listener.start()
+// Runs until listener.stop() is called
+```
+
+**When to use**: Any time you need to react to incoming DMs in real time — notifications, bots, monitoring dashboards. Prefer this over a polling shell loop.
+
+**Contrast with shell polling**: The `monitor-chat.sh` template uses `sleep` + `message list` in a loop. That works for simple scripts but makes one HTTP request per interval and can't react faster than the interval. The SDK listener holds a persistent connection and delivers messages as they arrive.
+
 ## Anti-Patterns
 
 ### Don't Poll Too Frequently
@@ -341,6 +374,8 @@ while true; do
 done
 ```
 
+For real-time monitoring, the SDK's `InstagramHybridListener` is a better alternative — it holds a persistent connection and avoids repeated HTTP requests entirely. See [Pattern 11](#pattern-11-real-time-dm-monitor-sdk) above.
+
 ### Don't Spam Threads
 
 ```bash
@@ -360,3 +395,4 @@ agent-instagram message send "$THREAD" "$MESSAGE"
 ## See Also
 
 - [Authentication Guide](authentication.md) - Setting up credentials
+- For real-time events, use the `InstagramHybridListener` SDK (see SKILL.md → SDK: Real-Time Events)

package/skills/agent-instagram/templates/monitor-chat.sh

@@ -12,6 +12,11 @@
 # Example:
 #   ./monitor-chat.sh 340282366841710300949128138443434234567
 #   ./monitor-chat.sh 340282366841710300949128138443434234567 10
+#
+# NOTE: For real-time monitoring, prefer the SDK's InstagramHybridListener over
+# this poll-based approach. It connects over Instagram's MQTToT transport and
+# delivers messages as they arrive, with automatic fallback to polling if needed.
+# See SKILL.md -> SDK: Real-Time Events for setup and usage.
 
 set -euo pipefail
 

package/skills/agent-kakaotalk/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-kakaotalk
 description: Interact with KakaoTalk - send messages, read chats, manage conversations
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-kakaotalk:*)
 metadata:
   openclaw:

package/skills/agent-line/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-line
 description: Interact with LINE - send messages, read chats, manage conversations
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-line:*)
 metadata:
   openclaw:

package/skills/agent-slack/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slack
 description: Interact with Slack workspaces - send messages, read channels, manage reactions
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-slack:*)
 metadata:
   openclaw:

package/skills/agent-slackbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slackbot
 description: Interact with Slack workspaces using bot tokens - send messages, read channels, manage reactions
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-slackbot:*)
 metadata:
   openclaw:

package/skills/agent-teams/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-teams
 description: Interact with Microsoft Teams - send messages, read channels, manage reactions
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-teams:*)
 metadata:
   openclaw:

package/skills/agent-telegram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegram
 description: Interact with Telegram through TDLib - authenticate, inspect chats, and send messages
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-telegram:*)
 ---
 

package/skills/agent-telegrambot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegrambot
 description: Interact with Telegram using bot tokens - send messages, read chats, manage reactions
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-telegrambot:*)
 metadata:
   openclaw:

package/skills/agent-webex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webex
 description: Interact with Cisco Webex - send messages, read spaces, manage memberships
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-webex:*)
 metadata:
   openclaw:

package/skills/agent-webexbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webexbot
 description: Interact with Cisco Webex using bot tokens - send messages, reply in threads, upload and download files, look up people, read spaces, manage memberships, stream real-time events
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-webexbot:*)
 metadata:
   openclaw:

package/skills/agent-wechatbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-wechatbot
 description: Interact with WeChat Official Account using API credentials - send messages, manage templates, list followers
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-wechatbot:*)
 metadata:
   openclaw:

package/skills/agent-whatsapp/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsapp
 description: Interact with WhatsApp - send messages, read chats, manage conversations
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-whatsapp:*)
 metadata:
   openclaw:

package/skills/agent-whatsappbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsappbot
 description: Interact with WhatsApp using Cloud API credentials - send messages, manage templates
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-whatsappbot:*)
 metadata:
   openclaw:

package/src/cli.ts

@@ -68,6 +68,10 @@ program.command('channeltalk', 'Interact with Channel Talk', {
   executableFile: join(__dirname, 'platforms', 'channeltalk', `cli${ext}`),
 })
 
+program.command('imessage', 'Interact with iMessage via imsg (local, on-Mac)', {
+  executableFile: join(__dirname, 'platforms', 'imessage', `cli${ext}`),
+})
+
 program.command('channeltalkbot', 'Interact with Channel Talk using API credentials', {
   executableFile: join(__dirname, 'platforms', 'channeltalkbot', `cli${ext}`),
 })

package/src/platforms/imessage/cli.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env bun
+
+import type { Command as CommandType } from 'commander'
+import { Command } from 'commander'
+
+import pkg from '../../../package.json' with { type: 'json' }
+import { authCommand, chatCommand, doctorCommand, messageCommand, setupCommand, whoamiCommand } from './commands/index'
+import { ensureIMessageAuth } from './ensure-auth'
+
+const UNGUARDED = new Set(['auth', 'setup', 'doctor'])
+
+function isUnguarded(command: CommandType): boolean {
+  let cmd: CommandType | null = command
+  while (cmd) {
+    if (UNGUARDED.has(cmd.name())) return true
+    cmd = cmd.parent
+  }
+  return false
+}
+
+const program = new Command()
+
+program.name('agent-imessage').description('CLI tool for iMessage via imsg (local, on-Mac)').version(pkg.version)
+
+program.hook('preAction', async (_thisCommand, actionCommand) => {
+  if (isUnguarded(actionCommand)) return
+  await ensureIMessageAuth()
+})
+
+program.addCommand(authCommand)
+program.addCommand(setupCommand)
+program.addCommand(doctorCommand)
+program.addCommand(chatCommand)
+program.addCommand(messageCommand)
+program.addCommand(whoamiCommand)
+
+program.parse(process.argv)
+
+export default program

package/src/platforms/imessage/client.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'bun:test'
+import { join } from 'node:path'
+
+import { ImsgClient } from './client'
+import { IMessageError } from './types'
+
+const STUB = join(import.meta.dir, 'test-stub-imsg.mjs')
+
+function clientWith(mode = 'ok'): ImsgClient {
+  process.env.IMSG_STUB_MODE = mode
+  return new ImsgClient()
+}
+
+describe('ImsgClient (against stub imsg binary)', () => {
+  it('getVersion returns the imsg version', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    expect(await c.getVersion()).toBe('0.11.1')
+    await c.close()
+  })
+
+  it('connect succeeds and listChats maps group/individual + fields', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    const chats = await c.listChats(10)
+    expect(chats[0]).toMatchObject({ id: 42, name: 'Jane', is_group: false, service: 'iMessage' })
+    expect(chats[1]).toMatchObject({ id: 43, name: 'Crew', is_group: true })
+    expect(chats[1]?.participants).toHaveLength(2)
+    await c.close()
+  })
+
+  it('connect throws full_disk_access when the DB is not readable', async () => {
+    const c = await clientWith('fda_denied').login({ binaryPath: STUB })
+    try {
+      await c.connect()
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('full_disk_access')
+      expect((error as IMessageError).suggestion).toContain('Full Disk Access')
+    } finally {
+      await c.close()
+    }
+  })
+
+  it('getMessages maps fields oldest-first with is_outgoing', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    const msgs = await c.getMessages(42, 10)
+    expect(msgs.map((m) => m.guid)).toEqual(['m1', 'm2'])
+    expect(msgs[0]?.is_outgoing).toBe(false)
+    expect(msgs[1]?.is_outgoing).toBe(true)
+    await c.close()
+  })
+
+  it('sendMessage returns guid/id; send failure maps to send_failed', async () => {
+    const ok = await clientWith('ok').login({ binaryPath: STUB })
+    await ok.connect()
+    expect(await ok.sendMessage({ chatId: 42 }, 'hi')).toMatchObject({ guid: 'sent-guid', id: 99, is_outgoing: true })
+    await ok.close()
+
+    const fail = await clientWith('send_fail').login({ binaryPath: STUB })
+    await fail.connect()
+    try {
+      await fail.sendMessage({ chatId: 42 }, 'hi')
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('send_failed')
+    } finally {
+      await fail.close()
+    }
+  })
+
+  it('watch delivers live notifications', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    const received: string[] = []
+    const stop = await c.watch((m) => received.push(m.guid), { chatId: 42 })
+    await new Promise((r) => setTimeout(r, 120))
+    await stop()
+    await c.close()
+    expect(received).toContain('m3')
+  })
+
+  it('sendReaction: standard via CLI; custom + message-target rejected', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    await expect(c.sendReaction(42, 'love')).resolves.toBeUndefined()
+    await expect(c.sendReaction(42, 'sparkles')).rejects.toMatchObject({ code: 'private_api_required' })
+    await expect(c.sendReaction(42, 'love', 'some-guid')).rejects.toMatchObject({ code: 'private_api_required' })
+    await c.close()
+  })
+
+  it('maps an Automation-denied "imsg react" failure to automation_denied (not send_failed)', async () => {
+    const c = await clientWith('react_automation_denied').login({ binaryPath: STUB })
+    await c.connect()
+    try {
+      await c.sendReaction(42, 'love')
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('automation_denied')
+    } finally {
+      await c.close()
+    }
+  })
+
+  it('maps AppleScript "not authorized" send error to automation_denied (not send_failed)', async () => {
+    const c = await clientWith('automation_denied').login({ binaryPath: STUB })
+    await c.connect()
+    try {
+      await c.sendMessage({ chatId: 42 }, 'hi')
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('automation_denied')
+    } finally {
+      await c.close()
+    }
+  })
+
+  it('close() rejects in-flight requests instead of hanging', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    const pending = c.listChats(1)
+    await c.close()
+    await expect(pending).rejects.toMatchObject({ code: 'rpc_error' })
+  })
+
+  it('imsg_not_found when the binary does not exist', async () => {
+    const c = await new ImsgClient().login({ binaryPath: '/nonexistent/imsg-xyz' })
+    try {
+      await c.connect()
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('imsg_not_found')
+    } finally {
+      await c.close()
+    }
+  })
+})