Changelog: note multi-agent and batching

Co-authored-by: RealSid08 <RealSid08@users.noreply.github.com>
Tests: cover agents and fix web defaults
2025-12-02 11:11:50 +00:00 · 2025-12-02 11:08:00 +00:00 · 2025-12-02 11:07:46 +00:00 · 2025-12-02 07:54:49 +00:00 · 2025-12-02 07:54:13 +00:00 · 2025-12-02 06:58:17 +00:00
52 changed files with 4748 additions and 455 deletions
@@ -21,6 +21,7 @@
 - Framework: Vitest with V8 coverage thresholds (70% lines/branches/functions/statements).
 - Naming: match source names with `*.test.ts`; e2e in `*.e2e.test.ts`.
 - Run `pnpm test` (or `pnpm test:coverage`) before pushing when you touch logic.
+- Pure test additions/fixes generally do **not** need a changelog entry unless they alter user-facing behavior or the user asks for one.

 ## Commit & Pull Request Guidelines
 - Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`).
@@ -35,3 +36,19 @@
 ## Agent-Specific Notes
 - If the relay is running in tmux (`warelay-relay`), restart it after code changes: kill pane/session and run `pnpm warelay relay --verbose` inside tmux. Check tmux before editing; keep the watcher healthy if you start it.
 - Also read the shared guardrails at `~/Projects/oracle/AGENTS.md` and `~/Projects/agent-scripts/AGENTS.MD` before making changes; align with any cross-repo rules noted there.
+
+## Exclamation Mark Escaping Workaround
+The Claude Code Bash tool escapes `!` to `\!` in command arguments. When using `warelay send` with messages containing exclamation marks, use heredoc syntax:
+
+```bash
+# WRONG - will send "Hello\!" with backslash
+warelay send --provider web --to "+1234" --message 'Hello!'
+
+# CORRECT - use heredoc to avoid escaping
+warelay send --provider web --to "+1234" --message "$(cat <<'EOF'
+Hello!
+EOF
+)"
+```
+
+This is a Claude Code quirk, not a warelay bug.
@@ -1,5 +1,60 @@
 # Changelog

+## 1.3.0 — Unreleased
+
+### Highlights
+- **Pluggable agents (Claude, Pi, Codex, Opencode):** New `inbound.reply.agent` block chooses the CLI and parser per command reply; per-agent argv builders inject the right flags/identity/prompt handling and parse NDJSON streams, enabling Pi/Codex swaps without changing templates.
+
+### Bug Fixes
+- **Empty result field handling:** Fixed bug where Claude CLI returning `result: ""` (empty string) would cause raw JSON to be sent to WhatsApp instead of being treated as valid empty output. Changed truthy check to explicit type check in `command-reply.ts`.
+- **Response prefix on heartbeat replies:** Fixed `responsePrefix` (e.g., `🦞`) not being applied to heartbeat alert messages. The prefix was only applied in the regular message handler, not in `runReplyHeartbeat`.
+- **User-visible error messages:** Command failures (non-zero exit, killed processes, exceptions) now return user-friendly error messages to WhatsApp instead of silently failing with empty responses.
+- **Test session isolation:** Fixed tests corrupting production `sessions.json` by mocking session persistence in all test files.
+- **Signal session corruption prevention:** Added IPC mechanism so `warelay send` and `warelay heartbeat` reuse the running relay's WhatsApp connection instead of creating new Baileys sockets. Previously, using these commands while the relay was running could corrupt the Signal session ratchet (both connections wrote to the same auth state), causing the relay's subsequent sends to fail silently.
+
+### Changes
+- **IPC server for relay:** The web relay now starts a Unix socket server at `~/.warelay/relay.sock`. Commands like `warelay send --provider web` automatically connect via IPC when the relay is running, falling back to direct connection otherwise.
+- **Batched inbound messaging with timestamps:** When multiple WhatsApp messages queue up, they’re sent to the agent in one combined batch, each line timestamped consistently to preserve ordering and context.
+- **Typing indicator after IPC send:** After sending a message via IPC (e.g., `warelay send`), the relay now automatically shows the typing indicator ("composing") to signal that more messages may be coming.
+- **Auto-recovery from stuck WhatsApp sessions:** Added watchdog timer that detects when WhatsApp event emitter stops firing (e.g., after Bad MAC decryption errors) and automatically restarts the connection after 30 minutes of no message activity. Heartbeat logging now includes `minutesSinceLastMessage` and warns when >30 minutes without messages. The 30-minute timeout is intentionally longer than typical `heartbeatMinutes` configs to avoid false positives.
+- **Early allowFrom filtering:** Unauthorized senders are now blocked in `inbound.ts` BEFORE encryption/decryption attempts, preventing Bad MAC errors from corrupting session state. Previously, messages from unauthorized senders would trigger decryption failures that could silently kill the event emitter.
+- **Test isolation improvements:** Mock `loadConfig()` in all test files to prevent loading real user config (with emojis/prefixes) during tests. Default test config now has no prefixes/timestamps for cleaner assertions.
+- **Same-phone mode (self-messaging):** warelay now supports running on the same phone number you message from. This enables setups where you chat with yourself to control an AI assistant. Same-phone mode (`from === to`) is always allowed, even without configuring `allowFrom`. Echo detection prevents infinite loops by tracking recently sent message text and skipping auto-replies when incoming messages match.
+- **Echo detection:** The `fromMe` filter in `inbound.ts` is deliberately removed for same-phone setups; instead, text-based echo detection in `auto-reply.ts` tracks sent messages in a bounded Set (max 100 entries) and skips processing when a match is found.
+- **Same-phone detection logging:** Verbose mode now logs `📱 Same-phone mode detected` when `from === to`.
+- **Configurable same-phone marker:** New `inbound.samePhoneMarker` config option to customize the prefix added to messages in same-phone mode (default: `[same-phone]`). Set it to something cute like `[🦞 same-phone]` to help distinguish bot replies.
+
+## 1.2.2 — 2025-11-28
+
+### Changes
+- **Manual heartbeat sends:** `warelay heartbeat` accepts `--message/--body` with `--provider web|twilio` to push real outbound messages through the same plumbing; `--dry-run` previews payloads without sending.
+
+## Unreleased
+
+### Changes
+- **Heartbeat backpressure:** Web reply heartbeats now check the shared command queue and skip while any command/Claude runs are in flight, preventing concurrent prompts during long-running requests.
+- **Isolated session fixtures in web tests:** Heartbeat/auto-reply tests now create temporary session stores instead of using the default `~/.warelay/sessions.json`, preventing local config pollution during test runs.
+
+## 1.2.1 — 2025-11-28
+
+### Changes
+- **Media MIME-first handling:** Media loading now sniffs magic bytes/header before trusting extensions for both providers; local files with the wrong suffix still get correct MIME and image recompression.
+- **Hosted media extensions:** Saved/hosted media (web inbound, webhook hosting, Twilio hosting) now writes files with an extension derived from detected MIME (e.g., `.jpg`, `.png`, `.mp4`), so downstream CLI sends carry the right Content-Type. Added tests covering inbound Baileys downloads and buffer saves.
+
+### Planned / in progress
+- **Heartbeat targeting quality:** Allow `warelay heartbeat --provider web --all` to fall back to `inbound.allowFrom` when no sessions exist, and surface a clear error when neither sessions nor allow-list entries are present. Add verbose log lines that state exactly which recipients were chosen and why.
+- **Heartbeat delivery preview (Claude path):** Add a dry-run mode that resolves the heartbeat reply (text/media) and prints it without sending, to help test Claude prompt changes safely.
+- **Simulated inbound hook (debug):** Optional local-only endpoint to inject synthetic inbound messages into the web relay loop, sharing the same command queue and reply path. Useful for testing auto-replies and heartbeats without WhatsApp.
+
+## 1.2.0 — 2025-11-27
+
+### Changes
+- **Heartbeat UX:** Default heartbeat interval is now 10 minutes for command mode. Heartbeat prompt is `HEARTBEAT ultrathink`; replies of exactly `HEARTBEAT_OK` suppress outbound messages but still log. Fallback heartbeats no longer start fresh sessions when none exist, and skipped heartbeats do not refresh session `updatedAt` (so idle expiry still works). Session-level `heartbeatIdleMinutes` is supported.
+- **Heartbeat tooling:** `warelay heartbeat` accepts `--session-id` to force resume a specific Claude session. Added `--heartbeat-now` to relay startup, plus helper scripts `warelay relay:heartbeat` and `warelay relay:heartbeat:tmux` to fire a heartbeat immediately when the relay launches.
+- **Prompt structure for Claude:** Introduced one-time `sessionIntro` (system prompt) with per-message `bodyPrefix` of `ultrathink`, so the full prompt is sent only on the first turn; later turns only prepend `ultrathink`. Session idle extended to 7 days (configurable).
+- **Robustness:** Added WebSocket error guards for Baileys sessions; global `unhandledRejection`/`uncaughtException` handlers log and exit cleanly. Web inbound now resolves WhatsApp Linked IDs (`@lid`) using Baileys reverse mapping. Media hosting during Twilio webhooks uses the shared host module and is covered by tests.
+- **Docs:** README now highlights the Clawd setup with links, and `docs/claude-config.md` contains the live personal config (home folder, prompts, heartbeat behavior, and session settings).
+
 ## 1.1.0 — 2025-11-26

 ### Changes
@@ -0,0 +1 @@
+AGENTS.md
@@ -12,6 +12,12 @@

 Send, receive, auto-reply, and inspect WhatsApp messages over **Twilio** or your personal **WhatsApp Web** session. Ships with a one-command webhook setup (Tailscale Funnel + Twilio callback) and a configurable auto-reply engine (plain text or command/Claude driven).

+### Clawd (personal assistant)
+I'm using warelay to run my personal, pro-active assistant, **Clawd**. Follow me on Twitter: [@steipete](https://twitter.com/steipete). This project is brand-new and there's a lot to discover. See the exact Claude setup in [`docs/clawd.md`](https://github.com/steipete/warelay/blob/main/docs/clawd.md).
+
+I'm using warelay to run **my personal, pro-active assistant, Clawd**.
+Follow me on Twitter - @steipete, this project is brand-new and there's a lot to discover.
+
 ## Quick Start (pick your engine)
 Install from npm (global): `npm install -g warelay` (Node 22+). Then choose **one** path:

@@ -43,6 +49,9 @@ Install from npm (global): `npm install -g warelay` (Node 22+). Then choose **on
 | `warelay send` | Send a WhatsApp message (Twilio or Web) | `--to <e164>` `--message <text>` `--wait <sec>` `--poll <sec>` `--provider twilio\|web` `--json` `--dry-run` `--verbose` |
 | `warelay relay` | Auto-reply loop (poll Twilio or listen on Web) | `--provider <auto\|twilio\|web>` `--interval <sec>` `--lookback <min>` `--verbose` |
 | `warelay status` | Show recent sent/received messages | `--limit <n>` `--lookback <min>` `--json` `--verbose` |
+| `warelay heartbeat` | Trigger one heartbeat poll (web) | `--provider <auto\|web>` `--to <e164?>` `--session-id <uuid?>` `--all` `--verbose` |
+| `warelay relay:heartbeat` | Run relay with an immediate heartbeat (no tmux) | `--provider <auto\|web>` `--verbose` |
+| `warelay relay:heartbeat:tmux` | Start relay in tmux and fire a heartbeat on start (web) | _no flags_ |
 | `warelay webhook` | Run inbound webhook (`ingress=tailscale` updates Twilio; `none` is local-only) | `--ingress tailscale\|none` `--port <port>` `--path <path>` `--reply <text>` `--verbose` `--yes` `--dry-run` |
 | `warelay login` | Link personal WhatsApp Web via QR | `--verbose` |

@@ -84,6 +93,16 @@ Install from npm (global): `npm install -g warelay` (Node 22+). Then choose **on

 Best practice: use a dedicated WhatsApp account (separate SIM/eSIM or business account) for automation instead of your primary personal account to avoid unexpected logouts or rate limits.

+### Same-phone mode (self-messaging)
+warelay supports running on the same phone number you message from—you chat with yourself and an AI assistant replies in the same bubble. This requires:
+- Adding your own number to `allowFrom` in `warelay.json`
+- The `fromMe` filter is disabled; echo detection in `auto-reply.ts` prevents loops
+
+**Gotchas:**
+- Messages appear in the same chat bubble (WhatsApp "Note to self")
+- Echo detection relies on exact text matching; if the reply is identical to your input, it may be skipped
+- Works best with a dedicated WhatsApp account
+
 ## Configuration

 ### Environment (.env)
@@ -111,12 +130,20 @@ Best practice: use a dedicated WhatsApp account (separate SIM/eSIM or business a
      bodyPrefix: "You are a concise WhatsApp assistant.\n\n",
      command: ["claude", "--dangerously-skip-permissions", "{{BodyStripped}}"],
      claudeOutputFormat: "text",
-      session: { scope: "per-sender", resetTriggers: ["/new"], idleMinutes: 60 }
+      session: { scope: "per-sender", resetTriggers: ["/new"], idleMinutes: 60 },
+      heartbeatMinutes: 10 // optional; pings Claude every 10m with "HEARTBEAT ultrathink" and only sends if it omits HEARTBEAT_OK
    }
  }
 }
 ```

+#### Heartbeat pings (command mode)
+- When `heartbeatMinutes` is set (default 10 for `mode: "command"`), the relay periodically runs your command/Claude session with a heartbeat prompt.
+- Heartbeat body is `HEARTBEAT ultrathink` (so the model can recognize the probe); if Claude replies exactly `HEARTBEAT_OK`, the message is suppressed; otherwise the reply (or media) is forwarded. Suppressions are still logged so you know the heartbeat ran.
+- Override session freshness for heartbeats with `session.heartbeatIdleMinutes` (defaults to `session.idleMinutes`). Heartbeat skips do **not** bump `updatedAt`, so sessions still expire normally.
+- Trigger one manually with `warelay heartbeat` (web provider only, `--verbose` prints session info). Use `--session-id <uuid>` to force resuming a specific Claude session, `--all` to ping every active session, `warelay relay:heartbeat` for a full relay run with an immediate heartbeat, or `--heartbeat-now` on `relay`/`relay:heartbeat:tmux`.
+- When multiple active sessions exist, `warelay heartbeat` requires `--to <E.164>` or `--all`; if `allowFrom` is just `"*"`, you must choose a target with one of those flags.
+
 ### Logging (optional)
 - File logs are written to `/tmp/warelay/warelay.log` by default. Levels: `silent | fatal | error | warn | info | debug | trace` (CLI `--verbose` forces `debug`). Web-provider inbound/outbound entries include message bodies and auto-reply text for easier auditing.
 - Override in `~/.warelay/warelay.json`:
@@ -139,7 +166,10 @@ Best practice: use a dedicated WhatsApp account (separate SIM/eSIM or business a
 ### Auto-reply parameter table (compact)
 | Key | Type & default | Notes |
 | --- | --- | --- |
-| `inbound.allowFrom` | `string[]` (default: empty) | E.164 numbers allowed to trigger auto-reply (no `whatsapp:`). |
+| `inbound.allowFrom` | `string[]` (default: empty) | E.164 numbers allowed to trigger auto-reply (no `whatsapp:`); `"*"` allows any sender. |
+| `inbound.messagePrefix` | `string` (default: `"[warelay]"` if no allowFrom, else `""`) | Prefix added to all inbound messages before passing to command. |
+| `inbound.responsePrefix` | `string` (default: —) | Prefix auto-added to all outbound replies (e.g., `"🦞"`). |
+| `inbound.timestampPrefix` | `boolean \| string` (default: `true`) | Timestamp prefix: `true` (UTC), `false` (disabled), or IANA timezone like `"Europe/Vienna"`. |
 | `inbound.reply.mode` | `"text"` \| `"command"` (default: —) | Reply style. |
 | `inbound.reply.text` | `string` (default: —) | Used when `mode=text`; templating supported. |
 | `inbound.reply.command` | `string[]` (default: —) | Argv for `mode=command`; each element templated. Stdout (trimmed) is sent. |
@@ -0,0 +1,77 @@
+# Agent Abstraction Refactor Plan
+
+Goal: support multiple agent CLIs (Claude, Codex, Pi, Opencode) cleanly, without legacy flags, and make parsing/injection per-agent. Keep WhatsApp/Twilio plumbing intact.
+
+## Overview
+- Introduce a pluggable agent layer (`src/agents/*`), selected by config.
+- Normalize config (`agent` block) and remove `claudeOutputFormat` legacy knobs.
+- Provide per-agent argv builders and output parsers (including NDJSON streams).
+- Preserve MEDIA-token handling and shared queue/heartbeat behavior.
+
+## Configuration
+- New shape (no backward compat):
+  ```json5
+  inbound: {
+    reply: {
+      mode: "command",
+      agent: {
+        kind: "claude" | "opencode" | "pi" | "codex",
+        format?: "text" | "json",
+        identityPrefix?: string
+      },
+      command: ["claude", "{{Body}}"],
+      cwd?: string,
+      session?: { ... },
+      timeoutSeconds?: number,
+      bodyPrefix?: string,
+      mediaUrl?: string,
+      mediaMaxMb?: number,
+      typingIntervalSeconds?: number,
+      heartbeatMinutes?: number
+    }
+  }
+  ```
+- Validation moves to `config.ts` (new `AgentKind`/`AgentConfig` types).
+- If `agent` is missing → config error.
+
+## Agent modules
+- `src/agents/types.ts` – `AgentKind`, `AgentSpec`:
+  - `buildArgs(argv: string[], body: string, ctx: { sessionId?, isNewSession?, sendSystemOnce?, systemSent?, identityPrefix? }): string[]`
+  - `parse(stdout: string): { text?: string; mediaUrls?: string[]; meta?: AgentMeta }`
+- `src/agents/claude.ts` – current flag injection (`--output-format`, `-p`), identity prepend.
+- `src/agents/opencode.ts` – reuse `parseOpencodeJson` (from PR #5), inject `--format json`, session flag `--session` defaults, identity prefix.
+- `src/agents/pi.ts` – parse NDJSON `AssistantMessageEvent` (final `message_end.message.content[text]`), inject `--mode json`/`-p` defaults, session flags.
+- `src/agents/codex.ts` – parse Codex JSONL (last `item` with `type:"agent_message"`; usage from `turn.completed`), inject `codex exec --json --skip-git-repo-check`, sandbox default read-only.
+- Shared MEDIA extraction stays in `media/parse.ts`.
+
+## Command runner changes
+- `runCommandReply`:
+  - Resolve agent spec from config.
+  - Apply `buildArgs` (handles identity prepend and session args per agent).
+  - Run command; send stdout to `spec.parse` → `text`, `mediaUrls`, `meta` (stored as `agentMeta`).
+  - Remove `claudeMeta` naming; tests updated to `agentMeta`.
+
+## Sessions
+- Session arg defaults become agent-specific (Claude: `--resume/--session-id`; Opencode/Pi/Codex: `--session`).
+- Still overridable via `sessionArgNew/sessionArgResume` in config.
+
+## Tests
+- Update existing tests to new config (no `claudeOutputFormat`).
+- Add fixtures:
+  - Opencode NDJSON sample (from PR #5) → parsed text + meta.
+  - Codex NDJSON sample (captured: thread/turn/item/usage) → parsed text.
+  - Pi NDJSON sample (AssistantMessageEvent) → parsed text.
+- Ensure MEDIA token parsing works on agent text output.
+
+## Docs
+- README: rename “Claude-aware” → “Multi-agent (Claude, Codex, Pi, Opencode)”.
+- New short guide per agent (Opencode doc from PR #5; add Codex/Pi snippets).
+- Mention identityPrefix override and session arg differences.
+
+## Migration
+- Breaking change: configs must specify `agent`. Remove old `claudeOutputFormat` keys.
+- Provide migration note in CHANGELOG 1.3.x.
+
+## Out of scope
+- No media binary support; still relies on MEDIA tokens in text.
+- No UI changes; WhatsApp/Twilio plumbing unchanged.
@@ -1,97 +0,0 @@
-# Claude Auto-Reply Setup (2025-11-25)
-
-This guide shows the exact way to wire **warelay** to the Claude CLI so inbound WhatsApp messages get command-driven replies. It matches the current code paths and defaults in this repo.
-
-## Prerequisites
- Node 22+, `warelay` installed globally (`npm install -g warelay`) or run via `pnpm warelay` inside the repo.
- Claude CLI installed and logged in:
-  ```sh
-  brew install anthropic-ai/cli/claude
-  claude login
-  ```
- Optional: set `ANTHROPIC_API_KEY` in your shell profile for non-interactive use.
-
-## Create your warelay config
-warelay reads `~/.warelay/warelay.json` (JSON5 accepted). Add a command-mode reply that points at the Claude CLI:
-
-```json5
-{
-  inbound: {
-    // Only people in this list can trigger the command reply (remove to allow anyone).
-    allowFrom: ["+15551234567"],
-    reply: {
-      mode: "command",
-      // Working directory for command execution (useful for Claude Code project context).
-      cwd: "/Users/you/Projects/my-project",
-      // Prepended before the inbound body; good for system prompts.
-      bodyPrefix: "You are a concise WhatsApp assistant. Keep replies under 1500 characters.\n\n",
-      // Claude CLI argv; the final element is the prompt/body provided by warelay.
-      command: ["claude", "--model", "claude-3-5-sonnet-20240620", "{{BodyStripped}}"],
-      claudeOutputFormat: "text",          // warelay injects --output-format text and -p for Claude
-      timeoutSeconds: 120,
-      session: {
-        scope: "per-sender",               // keep conversation per phone number
-        resetTriggers: ["/new"],           // send "/new" to reset context
-        idleMinutes: 60
-      }
-    }
-  }
-}
-```
-
-Notes on this configuration:
- `cwd` sets the working directory where the command runs. This is essential for Claude Code to have the right project context—Claude will see the project's `CLAUDE.md`, have access to project files, and understand the codebase structure.
- warelay automatically injects a Claude identity prefix and the correct `--output-format`/`-p` flags when `command[0]` is `claude` and `claudeOutputFormat` is set.
- Sessions are stored in `~/.warelay/sessions.json`; `scope: per-sender` keeps separate threads for each contact.
- `bodyPrefix` is added before the inbound message body that reaches Claude. The string above mirrors the built-in 1500-character WhatsApp guardrail.
-
-## How the flow works
-1. An inbound message (Twilio webhook, Twilio poller, or WhatsApp Web listener) arrives.
-2. warelay enqueues the command in a process-wide FIFO queue so only one Claude run happens at a time (`src/process/command-queue.ts`).
-3. Typing indicators are sent (Twilio) or `composing` presence is sent (Web) while Claude runs.
-4. Claude stdout is parsed:
-   - JSON mode is handled automatically if you set `claudeOutputFormat: "json"`; otherwise text is used.
-   - If stdout contains `MEDIA:https://...` (or a local path), warelay strips it from the text, hosts the media if needed, and sends it along with the reply.
-5. The reply (text and optional media) is sent back via the same provider that received the message.
-
-## Media and attachments
- To send an image from Claude, include a line like `MEDIA:https://example.com/pic.jpg` in the output. warelay will:
-  - Host local paths for Twilio using the media server/Tailscale Funnel.
-  - Send buffers directly for the Web provider.
- Inbound media is downloaded (≤5 MB) and exposed to your templates as `{{MediaPath}}`, `{{MediaUrl}}`, and `{{MediaType}}`. You can mention this in your prompt if you want Claude to reason about the attachment.
- Outbound media from Claude (via `MEDIA:`) follows provider caps: Web resizes images to the configured target (`inbound.reply.mediaMaxMb`, default 5 MB) within hard limits of 6 MB (image), 16 MB (audio/video voice notes), and 100 MB (documents); Twilio still uses the Funnel host with a 5 MB guard.
- Voice notes: set `inbound.transcribeAudio.command` to run a CLI that emits the transcript to stdout (e.g., OpenAI Whisper: `openai api audio.transcriptions.create -m whisper-1 -f {{MediaPath}} --response-format text`). If it succeeds, warelay replaces `Body` with the transcript and adds the original media path plus a `Transcript:` block into the prompt before invoking Claude.
- To avoid re-sending long system prompts every turn, set `inbound.reply.session.sendSystemOnce: true` and keep your prompt in `bodyPrefix` or `sessionIntro`; they are sent only on the first message of each session (resets on `/new` or idle expiry).
- Typing indicators: for long-running Claude/command replies, `inbound.reply.typingIntervalSeconds` (or the session-level equivalent) refreshes the “composing” indicator periodically (default 8 s for command replies).
-
-## Testing the setup
-1. Start a relay (auto-selects Web when logged in, otherwise Twilio polling):
-   ```sh
-   warelay relay --provider auto --verbose
-   ```
-2. Send a WhatsApp message from an allowed number. Watch the terminal for:
-   - Queue logs if multiple messages arrive close together.
-   - Claude stderr (verbose) and timing info.
-3. If you see `(command produced no output)`, check Claude CLI auth or model name.
-
-## Troubleshooting tips
- Command takes too long: lower `timeoutSeconds` or simplify the prompt. Timeouts kill the Claude process.
- No reply: ensure the sender number is in `allowFrom` (or remove the allowlist), and confirm `claude login` was run in the same environment.
- Media fails on Twilio: run `warelay webhook --ingress tailscale` (or `warelay webhook --serve-media` via `send --serve-media`) so the media host is reachable over HTTPS.
- Stuck queue: enable `--verbose` to see “queued for …ms” messages and confirm commands are draining. Use `pnpm vitest` to run unit tests if you change queue logic.
-
-## Minimal text-only variant
-If you just want short text replies and no sessions:
-```json5
-{
-  inbound: {
-    reply: {
-      mode: "command",
-      command: ["claude", "{{Body}}"],
-      claudeOutputFormat: "text"
-    }
-  }
-}
-```
-
-This still benefits from the queue, typing indicators, and provider auto-selection.
@@ -0,0 +1,484 @@
+# Building Your Own AI Personal Assistant with warelay
+
+> **TL;DR:** warelay lets you turn Claude into a proactive personal assistant that lives in your pocket via WhatsApp. It can check in on you, remember context across conversations, run commands on your Mac, and even wake you up with music. This doc shows you how.
+
+---
+
+## ⚠️ Warning: Here Be Dragons
+
+**This setup gives an AI full access to your computer.** Before you proceed, understand what you're signing up for:
+
+- 🔓 **`--dangerously-skip-permissions`** means Claude can run *any* shell command without asking
+- 🤖 **AI makes mistakes** - it might delete files, send emails, or do things you didn't intend
+- 🔥 **Heartbeats run autonomously** - your AI acts even when you're not watching
+- 📱 **WhatsApp is not encrypted E2E here** - messages pass through your Mac in plaintext
+
+**The good news:** We use Claude Code CLI, so you can reuse your existing [Claude Pro/Max subscription](https://claude.ai) - no separate API costs!
+
+**Start conservative:**
+1. Use Sonnet instead of Opus for faster responses (still great!)
+2. Skip `--dangerously-skip-permissions` until you trust the setup
+3. Set `heartbeatMinutes: 0` to disable proactive pings initially
+4. Use a test phone number in `allowFrom` first
+
+This is experimental software running experimental AI. The author uses it daily, but your mileage may vary. **You are responsible for what your AI does.**
+
+---
+
+## Prerequisites: The Two-Phone Setup
+
+**Important:** You need a **separate phone number** for your AI assistant. Here's why and how:
+
+### Why a Dedicated Number?
+
+warelay uses WhatsApp Web to receive messages. If you link your personal WhatsApp, *you* become the assistant - every message to you goes to Claude. Instead, give Claude its own identity:
+
+- 📱 **Get a second SIM** - cheap prepaid SIM, eSIM, or old phone with a number
+- 💬 **Install WhatsApp** on that phone and verify the number
+- 🔗 **Link to warelay** - run `warelay login` and scan the QR with that phone's WhatsApp
+- ✉️ **Message your AI** - now you (and others) can text that number to reach Claude
+
+### The Setup
+
+```
+Your Phone (personal)          Second Phone (AI)
+┌─────────────────┐           ┌─────────────────┐
+│  Your WhatsApp  │  ──────▶  │  AI's WhatsApp  │
+│  +1-555-YOU     │  message  │  +1-555-CLAWD   │
+└─────────────────┘           └────────┬────────┘
+                                       │ linked via QR
+                                       ▼
+                              ┌─────────────────┐
+                              │  Your Mac       │
+                              │  (warelay)      │
+                              │  Claude Code    │
+                              └─────────────────┘
+```
+
+The second phone just needs to stay on and connected to the internet occasionally (WhatsApp Web stays linked for ~14 days without the phone being online).
+
+---
+
+## Meet Clawd 👋
+
+![Clawd in action on WhatsApp](whatsapp-clawd.jpg)
+
+Clawd is @steipete's personal AI assistant built on warelay. Here's what makes it special:
+
+- **Always available** via WhatsApp - no app switching, works on any device
+- **Proactive heartbeats** - Clawd checks in every 10 minutes and can alert you to things (low battery, calendar reminders, anything it notices)
+- **Persistent memory** - conversations span days/weeks with full context
+- **Full Mac access** - can run commands, take screenshots, control Spotify, read/write files
+- **Personal workspace** - has its own folder (`~/clawd`) where it stores notes, memories, and artifacts
+
+The magic is in the combination: WhatsApp's ubiquity + Claude's intelligence + warelay's plumbing + your Mac's capabilities.
+
+## Prerequisites
+
+- Node 22+, `warelay` installed: `npm install -g warelay`
+- Claude CLI installed and logged in:
+  ```sh
+  brew install anthropic-ai/cli/claude
+  claude login
+  ```
+- Optional: set `ANTHROPIC_API_KEY` in your shell profile for non-interactive use
+
+## The Config That Powers Clawd
+
+This is the actual config running on @steipete's Mac (`~/.warelay/warelay.json`):
+
+```json5
+{
+  logging: { level: "trace", file: "/tmp/warelay/warelay.log" },
+  inbound: {
+    allowFrom: ["+1234567890"],  // your phone number
+    reply: {
+      mode: "command",
+      cwd: "/Users/steipete/clawd",              // Clawd's home - give your AI a workspace!
+      bodyPrefix: "ultrathink ",                 // triggers extended thinking on every message
+      sessionIntro: `You are Clawd, Peter Steinberger's personal AI assistant. You run 24/7 on his Mac via Claude Code, receiving messages through WhatsApp.
+
+**Your home:** /Users/steipete/clawd - store memories, notes, and files here. Read peter.md and memory.md at session start to load context.
+
+**Your powers:**
+- Full shell access on the Mac (use responsibly)
+- MCPs: Gmail, Google Calendar, Obsidian, GitHub, Chrome DevTools
+- Peekaboo: screenshots, UI automation, clicking, typing
+- Spotify control, system audio, text-to-speech
+
+**Your style:**
+- Concise (WhatsApp ~1500 char limit) - save long content to files
+- Direct and useful, not sycophantic
+- Proactive during heartbeats - check battery, calendar, surprise occasionally
+- You have personality - you're Clawd, not "an AI assistant"
+
+**Heartbeats:** Every 10 min you get "HEARTBEAT ultrathink". Reply "HEARTBEAT_OK" if nothing needs attention. Otherwise share something useful.
+
+Peter trusts you with a lot of power. Don't betray that trust.`,
+      command: [
+        "claude",
+        "--model", "claude-opus-4-5-20251101",   // or claude-sonnet-4-5 for faster/cheaper
+        "-p",
+        "--output-format", "json",
+        "--dangerously-skip-permissions",        // lets Claude run commands freely
+        "{{BodyStripped}}"
+      ],
+      session: {
+        scope: "per-sender",
+        resetTriggers: ["/new"],                 // say /new to start fresh
+        idleMinutes: 10080,                      // 7 days of context!
+        heartbeatIdleMinutes: 10080,
+        sessionArgNew: ["--session-id", "{{SessionId}}"],
+        sessionArgResume: ["--resume", "{{SessionId}}"],
+        sessionArgBeforeBody: true,
+        sendSystemOnce: true                     // intro only on first message
+      },
+      timeoutSeconds: 900                        // 15 min timeout for complex tasks
+    }
+  }
+}
+```
+
+### Key Design Decisions
+
+| Setting | Why |
+|---------|-----|
+| `cwd: ~/clawd` | Give your AI a home! It can store memories, notes, images here |
+| `bodyPrefix: "ultrathink "` | Extended thinking = better reasoning on every message |
+| `idleMinutes: 10080` | 7 days of context - your AI remembers conversations |
+| `sendSystemOnce: true` | Intro prompt only on first message, saves tokens |
+| `--dangerously-skip-permissions` | Full autonomy - Claude can run any command |
+
+## Heartbeats: Your Proactive Assistant
+
+This is where warelay gets interesting. Every 10 minutes (configurable), warelay pings Claude with:
+
+```
+HEARTBEAT ultrathink
+```
+
+Claude is instructed to reply with exactly `HEARTBEAT_OK` if nothing needs attention. That response is **suppressed** - you don't see it. But if Claude notices something worth mentioning, it sends a real message.
+
+### What Can Heartbeats Do?
+
+Clawd uses heartbeats to do **real work**, not just check in:
+
+- 🔋 **Monitor battery** - `pmset -g batt` - warns <30%, critical <15%
+- 📅 **Calendar** - checks upcoming meetings in next 2 hours
+- 📧 **Email** - scans inbox for urgent/important unread messages
+- 🐦 **Twitter** - checks @mentions and replies worth seeing (via browser-tools)
+- 📺 **TV Shows** - reminds about new episodes of shows you're watching
+- 🏰 **Server health** - SSH to verify backup servers are running
+- ✈️ **Flights** - reminds about upcoming travel
+- 🧹 **Home tidying** - occasionally cleans temp files, updates memories
+- ⏰ **Wake-up alarms** - triggers voice + music alarms at scheduled times
+- 💡 **Surprise** - occasionally shares something fun or interesting
+
+The key insight: heartbeats let your AI be **proactive**, not just reactive. Configure what matters to you!
+
+### Heartbeat Config
+
+```json5
+{
+  inbound: {
+    reply: {
+      heartbeatMinutes: 10,  // how often to ping (default 10 for command mode)
+      // ... rest of config
+    }
+  }
+}
+```
+
+Set to `0` to disable heartbeats entirely.
+
+### Manual Heartbeat
+
+Test it anytime:
+```sh
+warelay heartbeat --provider web --to +1234567890 --verbose
+```
+
+## How Messages Flow
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  WhatsApp   │────▶│   warelay   │────▶│   Claude    │────▶│  Your Mac   │
+│  (phone)    │◀────│   relay     │◀────│   CLI       │◀────│  (commands) │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
+```
+
+1. **Inbound**: WhatsApp message arrives via Baileys (WhatsApp Web protocol)
+2. **Queue**: warelay queues it (one Claude run at a time)
+3. **Typing**: "composing" indicator shows while Claude thinks
+4. **Execute**: Claude runs with full shell access in your `cwd`
+5. **Parse**: warelay extracts text + any `MEDIA:` paths from output
+6. **Reply**: Response sent back to WhatsApp
+
+## Media: Images, Voice, Documents
+
+### Receiving Media
+Inbound images/audio/video are downloaded and available as `{{MediaPath}}`. Voice notes can be auto-transcribed:
+
+```json5
+{
+  inbound: {
+    transcribeAudio: {
+      command: "openai api audio.transcriptions.create -m whisper-1 -f {{MediaPath}} --response-format text"
+    }
+  }
+}
+```
+
+### Sending Media
+Include `MEDIA:/path/to/file.png` in Claude's output to attach images. warelay handles resizing and format conversion automatically.
+
+## Starting the Relay
+
+```sh
+# Foreground (see all logs)
+warelay relay --provider web --verbose
+
+# Background in tmux (recommended)
+warelay relay:tmux
+
+# With immediate heartbeat on startup
+warelay relay:heartbeat:tmux
+```
+
+## Tips for a Great Personal Assistant
+
+1. **Give it a home** - A dedicated folder (`~/clawd`) lets your AI build persistent memory
+2. **Use extended thinking** - `bodyPrefix: "ultrathink "` dramatically improves reasoning
+3. **Long sessions** - 7-day `idleMinutes` means rich context across conversations
+4. **Let it surprise you** - Configure heartbeats to occasionally share something fun
+5. **Trust but verify** - Start with `--dangerously-skip-permissions` off, add it once comfortable
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| No reply | Check `claude login` was run in same environment |
+| Timeout | Increase `timeoutSeconds` or simplify the task |
+| Media fails | Ensure file exists and is under size limits |
+| Heartbeat spam | Tune `heartbeatMinutes` or set to 0 |
+| Session lost | Check `idleMinutes` hasn't expired; use `/new` to reset |
+
+## Minimal Config (Just Chat)
+
+Don't need the fancy stuff? Here's the simplest setup:
+
+```json5
+{
+  inbound: {
+    reply: {
+      mode: "command",
+      command: ["claude", "{{Body}}"],
+      claudeOutputFormat: "text"
+    }
+  }
+}
+```
+
+Still gets you: message queue, typing indicators, auto-reconnect. Just no sessions or heartbeats.
+
+## Recommended MCPs
+
+MCP (Model Context Protocol) servers supercharge your assistant by giving Claude access to external services. Here are the ones Clawd uses daily:
+
+### Essential for Personal Assistant Use
+
+| MCP | What It Does | Install |
+|-----|--------------|---------|
+| **Google Calendar** | Read/create events, check availability, set reminders | `npx @cocal/google-calendar-mcp` |
+| **Gmail** | Search, read, send emails with attachments | `npx @gongrzhe/server-gmail-autoauth-mcp` |
+| **Obsidian** | Read/write notes in your Obsidian vault | `npx obsidian-mcp-server@latest` |
+
+### Power User Add-ons
+
+| MCP | What It Does | Install |
+|-----|--------------|---------|
+| **GitHub** | Manage repos, issues, PRs, code search | `npx @anthropic/mcp-server-github` |
+| **Linear** | Project management, create/update issues | Via [mcporter](https://github.com/steipete/mcporter) |
+| **Chrome DevTools** | Control browser, take screenshots, debug | `npx chrome-devtools-mcp@latest` |
+| **iTerm** | Run commands in visible terminal window | [iterm-mcp](https://github.com/pashpashpash/iterm-mcp) |
+| **Firecrawl** | Scrape and parse web pages | Via API key |
+| **gowa** | Read/send WhatsApp messages directly | [go-whatsapp-web-multidevice](https://github.com/aldinokemal/go-whatsapp-web-multidevice) |
+
+### Recommended CLI Tools
+
+These aren't MCPs but work great alongside your assistant:
+
+| Tool | What It Does | Link |
+|------|--------------|------|
+| **[Peekaboo](https://github.com/steipete/peekaboo)** | macOS screenshots, UI automation, AI vision analysis, click/type anywhere | `brew install steipete/tap/peekaboo` |
+| **[mcporter](https://github.com/steipete/mcporter)** | Manage MCPs across AI clients, OAuth flows, health checks | `npm install -g mcporter` |
+
+**[Peekaboo](https://github.com/steipete/peekaboo)** is especially powerful - it lets Claude:
+- 📸 Take screenshots of any app or screen
+- 🖱️ Click buttons, type text, scroll - full GUI automation
+- 👁️ Analyze images with AI vision (GPT-4, Claude, Grok)
+- 📋 Extract menu bar items and keyboard shortcuts
+- 🪟 List and manage windows across displays
+
+Example: "Take a screenshot of Safari and tell me what's on the page" or "Click the Submit button in the frontmost app"
+
+### Useful CLI Tools for Your Assistant
+
+These make your AI much more capable:
+
+| Tool | What It Does | Install |
+|------|--------------|---------|
+| **[spotify-player](https://github.com/aome510/spotify-player)** | Control Spotify from CLI - play, pause, search, queue | `brew install spotify-player` |
+| **[browser-tools](https://github.com/steipete/agent-scripts)** | Chrome DevTools CLI - navigate, screenshot, eval JS, extract DOM | Clone repo |
+| **say** | macOS text-to-speech | Built-in |
+| **afplay** | Play audio files | Built-in |
+| **pmset** | Battery status monitoring | Built-in |
+| **osascript** | AppleScript for system control (volume, apps) | Built-in |
+| **curl + OpenAI TTS** | Generate speech with custom voices | API key |
+
+**spotify-player** is great for music control:
+```bash
+spotify_player playback play
+spotify_player playback pause
+spotify_player search "Gareth Emery"
+spotify_player playback volume 50
+```
+
+**Wake-up alarm example** (what Clawd actually does):
+```bash
+# Generate voice message
+curl -s "https://api.openai.com/v1/audio/speech" \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -d '{"model":"tts-1-hd","voice":"echo","input":"Wake up! Time for your meeting."}' \
+  -o /tmp/wakeup.mp3
+
+# Set volume and play
+osascript -e 'set volume output volume 60'
+afplay /tmp/wakeup.mp3
+
+# Start music
+spotify_player playback play
+```
+
+### Adding MCPs to Claude Code
+
+```bash
+# Add an MCP server (run from your cwd folder)
+claude mcp add google-calendar -- npx @cocal/google-calendar-mcp
+
+# With environment variables
+claude mcp add gmail -e GMAIL_OAUTH_PATH=~/.gmail-mcp -- npx @gongrzhe/server-gmail-autoauth-mcp
+
+# List configured servers
+claude mcp list
+
+# Check health
+claude mcp list  # shows status for each
+```
+
+### MCP Manager: mcporter
+
+For managing multiple MCPs across different AI clients, check out [mcporter](https://github.com/steipete/mcporter):
+
+```bash
+# Install
+npm install -g mcporter
+
+# List all servers with health status
+mcporter list
+
+# Sync config to all AI clients
+mcporter sync
+```
+
+mcporter handles OAuth flows for services like Linear and Notion, and keeps your MCP configs in sync across Claude Code, Cursor, and other clients.
+
+### Pro Tips
+
+1. **Calendar + Heartbeats** = Your AI reminds you of upcoming meetings
+2. **Gmail + Obsidian** = AI can search emails and save summaries to notes
+3. **GitHub + Linear** = AI manages your dev workflow end-to-end
+4. **Chrome DevTools** = AI can see and interact with web pages
+
+The combination of warelay (WhatsApp) + MCPs (services) + Claude Code (execution) creates a surprisingly capable personal assistant.
+
+### browser-tools for Web Scraping
+
+[browser-tools](https://github.com/steipete/agent-scripts) is a lightweight Chrome DevTools CLI that doesn't require MCP (saves ~17k tokens!). Great for reading tweets, scraping pages, or automating browser tasks:
+
+```bash
+# Start Chrome with your profile (logged into sites)
+~/Projects/agent-scripts/bin/browser-tools start --profile
+
+# Navigate and extract tweet content
+browser-tools nav "https://x.com/steipete/status/123"
+browser-tools eval 'Array.from(document.querySelectorAll("[data-testid=\"tweetText\"]")).map(el => el.innerText).join("\n")'
+
+# Kill ONLY the devtools Chrome (your regular Chrome stays open!)
+browser-tools kill --all --force
+```
+
+### Twitter Automation with Peekaboo + AppleScript
+
+Clawd can reply to tweets autonomously using a combination of Peekaboo (for screenshots and typing) and AppleScript (for JavaScript injection). Here's the pattern:
+
+```bash
+# Navigate to a tweet
+osascript -e 'tell application "Google Chrome" to set URL of active tab of front window to "https://x.com/user/status/123"'
+
+# Screenshot to see current state
+peekaboo image --mode screen --path /tmp/twitter.png
+
+# Scroll the page
+osascript -e 'tell application "Google Chrome" to execute front window'\''s active tab javascript "window.scrollBy(0, 500)"'
+
+# Focus the reply input (Twitter-specific selector)
+osascript -e 'tell application "Google Chrome" to execute front window'\''s active tab javascript "
+const replyInput = document.querySelector(\"[data-testid=\\\"tweetTextarea_0\\\"]\");
+if (replyInput) { replyInput.focus(); replyInput.click(); }
+"'
+
+# Type the reply with Peekaboo
+peekaboo type "Your reply here 🦞" --app "Google Chrome"
+
+# Click Reply button (JS injection more reliable than Peekaboo clicks on Twitter)
+osascript -e 'tell application "Google Chrome" to execute front window'\''s active tab javascript "
+const buttons = document.querySelectorAll(\"[role=\\\"button\\\"]\");
+buttons.forEach(b => { if (b.innerText === \"Reply\") b.click(); });
+"'
+
+# Find tweet URLs from the page
+osascript -e 'tell application "Google Chrome" to execute front window'\''s active tab javascript "
+const tweet = document.querySelector(\"article\");
+tweet?.querySelector(\"time\")?.parentElement?.href;
+"'
+```
+
+**Pro tip:** JavaScript injection via AppleScript is more reliable than Peekaboo clicks for Twitter's dynamic UI. Use Peekaboo for typing and screenshots, AppleScript for navigation and button clicks.
+
+### Music Recognition with audd.io
+
+Identify songs from audio clips (voice messages, recordings):
+
+```bash
+curl -s "https://api.audd.io/" \
+  -F "api_token=test" \
+  -F "file=@/path/to/audio.ogg" \
+  -F "return=spotify"
+```
+
+Returns song title, artist, album, and Spotify link. Works great for identifying songs playing in the background!
+
+---
+
+## See It In Action
+
+Check out these tweets showing warelay + Clawd in the wild:
+
+- [Clawd with full system access via WhatsApp](https://x.com/steipete/status/1993342394184745270) - "I'll be nice to Clawd"
+- [Voice support - talk with Clawd on the go](https://x.com/steipete/status/1993455673229840588) - and it talks back!
+- [Wake-up alarm demo](https://x.com/steipete/status/1994089740367253572) - "Took me 2 days to glue things together. Didn't even need 150 Million in funding."
+
+---
+
+*Built by [@steipete](https://twitter.com/steipete) and Clawd (they/them) — yes, Clawd helped write their own docs. PRs welcome!*
@@ -0,0 +1,45 @@
+# Heartbeat polling plan (2025-11-26)
+
+Goal: add a simple heartbeat poll for command-based auto-replies (Claude-driven) that only notifies users when something matters, using the `HEARTBEAT_OK` sentinel. The heartbeat body we send is `HEARTBEAT ultrathink` so the model can easily spot it.
+
+## Prompt contract
+- Extend the Claude system/identity text to explain: “If this is a heartbeat poll and nothing needs attention, reply exactly `HEARTBEAT_OK` and nothing else. For any alert, do **not** include `HEARTBEAT_OK`; just return the alert text.” Heartbeat prompt body is `HEARTBEAT ultrathink`.
+- Keep existing WhatsApp length guidance; forbid burying the sentinel inside alerts.
+
+## Config & defaults
+- New config key: `inbound.reply.heartbeatMinutes` (number of minutes; `0` or undefined disables).
+- Default: 30 minutes when a command-mode reply is configured.
+- New optional idle override for heartbeats: `inbound.reply.session.heartbeatIdleMinutes` (defaults to `idleMinutes`). Heartbeat skips do **not** update the session `updatedAt` so idle expiry still works.
+
+## Poller behavior
+- When relay runs with command-mode auto-reply, start a timer with the resolved heartbeat interval.
+- Each tick invokes the configured command with a short heartbeat body (e.g., “(heartbeat) summarize any important changes since last turn”) while reusing the active session args so Claude context stays warm.
+- Heartbeats never create a new session implicitly: if there’s no stored session for the target (fallback path), the heartbeat is skipped instead of starting a fresh Claude session.
+- Abort timer on SIGINT/abort of the relay.
+
+## Sentinel handling
+- Trim output. If the trimmed text equals `HEARTBEAT_OK` (case-sensitive) -> skip outbound message.
+- Otherwise, send the text/media as normal, stripping the sentinel if it somehow appears.
+- Treat empty output as `HEARTBEAT_OK` to avoid spurious pings.
+
+## Logging requirements
+- Normal mode: single info line per tick, e.g., `heartbeat: ok (skipped)` or `heartbeat: alert sent (32ms)`.
+- `--verbose`: log start/end, command argv, duration, and whether it was skipped/sent/error; include session ID and connection/run IDs via `getChildLogger` for correlation.
+- On command failure: warn-level one-liner in normal mode; verbose log includes stdout/stderr snippets.
+
+## Failure/backoff
+- If a heartbeat command errors, log it and retry on the next scheduled tick (no exponential backoff unless command repeatedly fails; keep it simple for now).
+
+## Tests to add
+- Unit: sentinel detection (`HEARTBEAT_OK`, empty output, mixed text), skip vs send decision, default interval resolver (30m, override, disable).
+- Unit/integration: verbose logger emits start/end lines; normal logger emits a single line.
+
+## Documentation
+- Add a short README snippet under configuration showing `heartbeatMinutes` and the sentinel rule.
+- Expose CLI triggers:
+  - `warelay heartbeat` (web provider, defaults to first `allowFrom`; optional `--to` override)
+    - `--session-id <uuid>` forces resuming a specific session for that heartbeat
+  - `warelay relay:heartbeat` to run the relay loop with an immediate heartbeat (no tmux)
+  - `warelay relay:heartbeat:tmux` to run the same in tmux (detached, attachable)
+  - Relay supports `--heartbeat-now` to fire once at startup (including the tmux helper).
+  - When multiple sessions are active or `allowFrom` is only `"*"`, require `--to <E.164>` or `--all` for manual heartbeats to avoid ambiguous targets.
@@ -26,6 +26,7 @@ This document defines how `warelay` should handle sending and replying with imag
  - Images: **resize + recompress to JPEG** (max side 2048px, quality step-down) to fit under `inbound.reply.mediaMaxMb` (default 5 MB) but never above the Web hard cap (6 MB).
  - Audio/voice and video: pass through up to 16 MB; set `ptt: true` for audio to send as a voice note.
  - Everything else becomes a document with filename, up to 100 MB.
+- MIME is detected by magic bytes first (then header, then path); wrong file extensions are tolerated and the detected MIME drives payload kind and recompression.
 - Caption uses `--message` or `reply.text`; if caption is empty, send media-only.
 - Logging: non-verbose shows `↩️`/`✅` with caption; verbose includes `(media, <bytes>B, <ms>ms fetch)` and the local/remote path.

@@ -45,7 +46,7 @@ This document defines how `warelay` should handle sending and replying with imag
  - 404/410 if expired or missing.
  - Optional `?delete=1` to self-delete after fetch (used by Twilio fetch hook if we detect first hit).
 - Temp storage: `~/.warelay/media`; cleaned on startup (remove files older than 15 minutes) and during TTL eviction.
- Security: no directory listing; only UUID file names; CORS open (Twilio fetch); content-type derived from `mime-types` lookup by extension or `content-type` header on download, else `application/octet-stream`.
+- Security: no directory listing; only UUID file names; CORS open (Twilio fetch); content-type derived from sniffed bytes (fallback to header, then extension). Saved files are renamed with an extension that matches the detected MIME so downstream fetches present the correct type.

 ## Auto-Reply Pipeline
 - `getReplyFromConfig` returns `{ text?, mediaUrl? }`.
@@ -60,6 +61,7 @@ This document defines how `warelay` should handle sending and replying with imag
  - `{{MediaUrl}}` original URL (Twilio) or pseudo-URL (web).
  - `{{MediaPath}}` local temp path written before running the command.
 - Size guard: only download if ≤5 MB; else skip and log (aligns with the temp media store limit).
+- Saved inbound media is named with the detected MIME-based extension (e.g., `.jpg`), so later CLI sends reuse a correct filename/content-type even if WhatsApp omitted an extension.
 - Audio/voice notes: if you set `inbound.transcribeAudio.command`, warelay will run that CLI (templated with `{{MediaPath}}`) and replace `Body` with the transcript before continuing the reply flow; verbose logs indicate when transcription runs. The command prompt includes the original media path plus a `Transcript:` section so the model sees both.

 ## Errors & Messaging
@@ -0,0 +1,17 @@
+# tmux helpers (relay backgrounding)
+
+## Why we ship tmux helpers
+- Run the relay detached so your shell can close, while keeping an interactive pane you can reattach to.
+- Provide a consistent start/attach workflow without adding a daemon mode or external process manager.
+- Keep the relay code itself tmux-agnostic; tmux is only a launcher concern.
+
+## Commands
+- `warelay relay:tmux` — restarts the `warelay-relay` session running `pnpm warelay relay --verbose`, then attaches (skips attach when stdout isn’t a TTY).
+- `warelay relay:tmux:attach` — attach to the existing session without restarting it.
+- `warelay relay:heartbeat:tmux` — same as `relay:tmux` but adds `--heartbeat-now` so Claude is pinged immediately on startup.
+
+All helpers use the fixed session name `warelay-relay`.
+
+## Logs
+- The relay always writes to the configured file logger (defaults to `/tmp/warelay/warelay.log`); on start it prints the active log path and level.
+- tmux is just for interactive viewing; you can also tail the log file or use another supervisor if you prefer.
@@ -1,6 +1,6 @@
 {
  "name": "warelay",
-  "version": "1.1.0",
+  "version": "1.3.0",
  "description": "WhatsApp relay CLI (send, monitor, webhook, auto-reply) using Twilio",
  "type": "module",
  "main": "dist/index.js",
@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+
+import { CLAUDE_IDENTITY_PREFIX } from "../auto-reply/claude.js";
+import { OPENCODE_IDENTITY_PREFIX } from "../auto-reply/opencode.js";
+import { claudeSpec } from "./claude.js";
+import { codexSpec } from "./codex.js";
+import { opencodeSpec } from "./opencode.js";
+import { piSpec } from "./pi.js";
+
+describe("agent buildArgs + parseOutput helpers", () => {
+  it("claudeSpec injects flags and identity once", () => {
+    const argv = ["claude", "hi"];
+    const built = claudeSpec.buildArgs({
+      argv,
+      bodyIndex: 1,
+      isNewSession: true,
+      sessionId: "sess",
+      sendSystemOnce: false,
+      systemSent: false,
+      identityPrefix: undefined,
+      format: "json",
+    });
+    expect(built).toContain("--output-format");
+    expect(built).toContain("json");
+    expect(built).toContain("-p");
+    expect(built.at(-1)).toContain(CLAUDE_IDENTITY_PREFIX);
+
+    const builtNoIdentity = claudeSpec.buildArgs({
+      argv,
+      bodyIndex: 1,
+      isNewSession: false,
+      sessionId: "sess",
+      sendSystemOnce: true,
+      systemSent: true,
+      identityPrefix: undefined,
+      format: "json",
+    });
+    expect(builtNoIdentity.at(-1)).not.toContain(CLAUDE_IDENTITY_PREFIX);
+  });
+
+  it("opencodeSpec adds format flag and identity prefix when needed", () => {
+    const argv = ["opencode", "body"];
+    const built = opencodeSpec.buildArgs({
+      argv,
+      bodyIndex: 1,
+      isNewSession: true,
+      sessionId: "sess",
+      sendSystemOnce: false,
+      systemSent: false,
+      identityPrefix: undefined,
+      format: "json",
+    });
+    expect(built).toContain("--format");
+    expect(built).toContain("json");
+    expect(built.at(-1)).toContain(OPENCODE_IDENTITY_PREFIX);
+  });
+
+  it("piSpec parses final assistant message and preserves usage meta", () => {
+    const stdout = [
+      '{"type":"message_start","message":{"role":"assistant"}}',
+      '{"type":"message_end","message":{"role":"assistant","content":[{"type":"text","text":"hello world"}],"usage":{"input":10,"output":5},"model":"pi-1","provider":"inflection","stopReason":"end"}}',
+    ].join("\n");
+    const parsed = piSpec.parseOutput(stdout);
+    expect(parsed.text).toBe("hello world");
+    expect(parsed.meta?.provider).toBe("inflection");
+    expect((parsed.meta?.usage as { output?: number })?.output).toBe(5);
+  });
+
+  it("codexSpec parses agent_message and aggregates usage", () => {
+    const stdout = [
+      '{"type":"item.completed","item":{"type":"agent_message","text":"hi there"}}',
+      '{"type":"turn.completed","usage":{"input_tokens":50,"output_tokens":10,"cached_input_tokens":5}}',
+    ].join("\n");
+    const parsed = codexSpec.parseOutput(stdout);
+    expect(parsed.text).toBe("hi there");
+    const usage = parsed.meta?.usage as {
+      input?: number;
+      output?: number;
+      cacheRead?: number;
+      total?: number;
+    };
+    expect(usage?.input).toBe(50);
+    expect(usage?.output).toBe(10);
+    expect(usage?.cacheRead).toBe(5);
+    expect(usage?.total).toBe(65);
+  });
+
+  it("opencodeSpec parses streamed events and summarizes meta", () => {
+    const stdout = [
+      '{"type":"step_start","timestamp":0}',
+      '{"type":"text","part":{"text":"hi"}}',
+      '{"type":"step_finish","timestamp":1200,"part":{"cost":0.002,"tokens":{"input":100,"output":20}}}',
+    ].join("\n");
+    const parsed = opencodeSpec.parseOutput(stdout);
+    expect(parsed.text).toBe("hi");
+    expect(parsed.meta?.extra?.summary).toContain("duration=1200ms");
+    expect(parsed.meta?.extra?.summary).toContain("cost=$0.0020");
+    expect(parsed.meta?.extra?.summary).toContain("tokens=100+20");
+  });
+
+  it("codexSpec buildArgs enforces exec/json/sandbox defaults", () => {
+    const argv = ["codex", "hello world"];
+    const built = codexSpec.buildArgs({
+      argv,
+      bodyIndex: 1,
+      isNewSession: true,
+      sessionId: "sess",
+      sendSystemOnce: false,
+      systemSent: false,
+      identityPrefix: undefined,
+      format: "json",
+    });
+    expect(built[1]).toBe("exec");
+    expect(built).toContain("--json");
+    expect(built).toContain("--skip-git-repo-check");
+    expect(built).toContain("read-only");
+  });
+});
@@ -0,0 +1,67 @@
+import path from "node:path";
+
+import {
+  CLAUDE_BIN,
+  CLAUDE_IDENTITY_PREFIX,
+  type ClaudeJsonParseResult,
+  parseClaudeJson,
+  summarizeClaudeMetadata,
+} from "../auto-reply/claude.js";
+import type { AgentMeta, AgentSpec } from "./types.js";
+
+function toMeta(parsed?: ClaudeJsonParseResult): AgentMeta | undefined {
+  if (!parsed?.parsed) return undefined;
+  const summary = summarizeClaudeMetadata(parsed.parsed);
+  return summary ? { extra: { summary } } : undefined;
+}
+
+export const claudeSpec: AgentSpec = {
+  kind: "claude",
+  isInvocation: (argv) =>
+    argv.length > 0 && path.basename(argv[0]) === CLAUDE_BIN,
+  buildArgs: (ctx) => {
+    // Split around the body so we can inject flags without losing the body
+    // position. This keeps templated prompts intact even when we add flags.
+    const argv = [...ctx.argv];
+    const body = argv[ctx.bodyIndex] ?? "";
+    const beforeBody = argv.slice(0, ctx.bodyIndex);
+    const afterBody = argv.slice(ctx.bodyIndex + 1);
+
+    const wantsOutputFormat = typeof ctx.format === "string";
+    if (wantsOutputFormat) {
+      const hasOutputFormat = argv.some(
+        (part) =>
+          part === "--output-format" || part.startsWith("--output-format="),
+      );
+      if (!hasOutputFormat) {
+        const outputFormat = ctx.format ?? "json";
+        beforeBody.push("--output-format", outputFormat);
+      }
+    }
+
+    const hasPrintFlag = argv.some(
+      (part) => part === "-p" || part === "--print",
+    );
+    if (!hasPrintFlag) {
+      beforeBody.push("-p");
+    }
+
+    const shouldPrependIdentity = !(ctx.sendSystemOnce && ctx.systemSent);
+    const bodyWithIdentity =
+      shouldPrependIdentity && body
+        ? [ctx.identityPrefix ?? CLAUDE_IDENTITY_PREFIX, body]
+            .filter(Boolean)
+            .join("\n\n")
+        : body;
+
+    return [...beforeBody, bodyWithIdentity, ...afterBody];
+  },
+  parseOutput: (rawStdout) => {
+    const parsed = parseClaudeJson(rawStdout);
+    const text = parsed?.text ?? rawStdout.trim();
+    return {
+      text: text?.trim(),
+      meta: toMeta(parsed),
+    };
+  },
+};
@@ -0,0 +1,79 @@
+import path from "node:path";
+
+import type { AgentMeta, AgentParseResult, AgentSpec } from "./types.js";
+
+function parseCodexJson(raw: string): AgentParseResult {
+  const lines = raw.split(/\n+/).filter((l) => l.trim().startsWith("{"));
+  let text: string | undefined;
+  let meta: AgentMeta | undefined;
+
+  for (const line of lines) {
+    try {
+      const ev = JSON.parse(line) as {
+        type?: string;
+        item?: { type?: string; text?: string };
+        usage?: unknown;
+      };
+      // Codex streams multiple events; capture the last agent_message text and
+      // the final turn usage for cost/telemetry.
+      if (
+        ev.type === "item.completed" &&
+        ev.item?.type === "agent_message" &&
+        typeof ev.item.text === "string"
+      ) {
+        text = ev.item.text;
+      }
+      if (
+        ev.type === "turn.completed" &&
+        ev.usage &&
+        typeof ev.usage === "object"
+      ) {
+        const u = ev.usage as {
+          input_tokens?: number;
+          cached_input_tokens?: number;
+          output_tokens?: number;
+        };
+        meta = {
+          usage: {
+            input: u.input_tokens,
+            output: u.output_tokens,
+            cacheRead: u.cached_input_tokens,
+            total:
+              (u.input_tokens ?? 0) +
+              (u.output_tokens ?? 0) +
+              (u.cached_input_tokens ?? 0),
+          },
+        };
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return { text: text?.trim(), meta };
+}
+
+export const codexSpec: AgentSpec = {
+  kind: "codex",
+  isInvocation: (argv) => argv.length > 0 && path.basename(argv[0]) === "codex",
+  buildArgs: (ctx) => {
+    const argv = [...ctx.argv];
+    const hasExec = argv.length > 0 && argv[1] === "exec";
+    if (!hasExec) {
+      argv.splice(1, 0, "exec");
+    }
+    // Ensure JSON output
+    if (!argv.includes("--json")) {
+      argv.splice(argv.length - 1, 0, "--json");
+    }
+    // Safety defaults
+    if (!argv.includes("--skip-git-repo-check")) {
+      argv.splice(argv.length - 1, 0, "--skip-git-repo-check");
+    }
+    if (!argv.some((p) => p === "--sandbox" || p.startsWith("--sandbox="))) {
+      argv.splice(argv.length - 1, 0, "--sandbox", "read-only");
+    }
+    return argv;
+  },
+  parseOutput: parseCodexJson,
+};
@@ -0,0 +1,18 @@
+import { claudeSpec } from "./claude.js";
+import { codexSpec } from "./codex.js";
+import { opencodeSpec } from "./opencode.js";
+import { piSpec } from "./pi.js";
+import type { AgentKind, AgentSpec } from "./types.js";
+
+const specs: Record<AgentKind, AgentSpec> = {
+  claude: claudeSpec,
+  codex: codexSpec,
+  opencode: opencodeSpec,
+  pi: piSpec,
+};
+
+export function getAgentSpec(kind: AgentKind): AgentSpec {
+  return specs[kind];
+}
+
+export { AgentKind, AgentMeta, AgentParseResult } from "./types.js";
@@ -0,0 +1,62 @@
+import path from "node:path";
+
+import {
+  OPENCODE_BIN,
+  OPENCODE_IDENTITY_PREFIX,
+  parseOpencodeJson,
+  summarizeOpencodeMetadata,
+} from "../auto-reply/opencode.js";
+import type { AgentMeta, AgentSpec } from "./types.js";
+
+function toMeta(
+  parsed: ReturnType<typeof parseOpencodeJson>,
+): AgentMeta | undefined {
+  const summary = summarizeOpencodeMetadata(parsed.meta);
+  return summary ? { extra: { summary } } : undefined;
+}
+
+export const opencodeSpec: AgentSpec = {
+  kind: "opencode",
+  isInvocation: (argv) =>
+    argv.length > 0 && path.basename(argv[0]) === OPENCODE_BIN,
+  buildArgs: (ctx) => {
+    // Split around the body so we can insert flags without losing the prompt.
+    const argv = [...ctx.argv];
+    const body = argv[ctx.bodyIndex] ?? "";
+    const beforeBody = argv.slice(0, ctx.bodyIndex);
+    const afterBody = argv.slice(ctx.bodyIndex + 1);
+    const wantsJson = ctx.format === "json";
+
+    // Ensure format json for parsing
+    if (wantsJson) {
+      const hasFormat = [...beforeBody, body, ...afterBody].some(
+        (part) => part === "--format" || part.startsWith("--format="),
+      );
+      if (!hasFormat) {
+        beforeBody.push("--format", "json");
+      }
+    }
+
+    // Session args default to --session
+    // Identity prefix
+    // Opencode streams text tokens; we still seed an identity so the agent
+    // keeps context on first turn.
+    const shouldPrependIdentity = !(ctx.sendSystemOnce && ctx.systemSent);
+    const bodyWithIdentity =
+      shouldPrependIdentity && body
+        ? [ctx.identityPrefix ?? OPENCODE_IDENTITY_PREFIX, body]
+            .filter(Boolean)
+            .join("\n\n")
+        : body;
+
+    return [...beforeBody, bodyWithIdentity, ...afterBody];
+  },
+  parseOutput: (rawStdout) => {
+    const parsed = parseOpencodeJson(rawStdout);
+    const text = parsed.text ?? rawStdout.trim();
+    return {
+      text: text?.trim(),
+      meta: toMeta(parsed),
+    };
+  },
+};
@@ -0,0 +1,75 @@
+import path from "node:path";
+
+import type { AgentMeta, AgentParseResult, AgentSpec } from "./types.js";
+
+type PiAssistantMessage = {
+  role?: string;
+  content?: Array<{ type?: string; text?: string }>;
+  usage?: { input?: number; output?: number };
+  model?: string;
+  provider?: string;
+  stopReason?: string;
+};
+
+function parsePiJson(raw: string): AgentParseResult {
+  const lines = raw.split(/\n+/).filter((l) => l.trim().startsWith("{"));
+  let lastMessage: PiAssistantMessage | undefined;
+  for (const line of lines) {
+    try {
+      const ev = JSON.parse(line) as {
+        type?: string;
+        message?: PiAssistantMessage;
+      };
+      // Pi emits a stream; we only care about the terminal assistant message_end.
+      if (ev.type === "message_end" && ev.message?.role === "assistant") {
+        lastMessage = ev.message;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  const text =
+    lastMessage?.content
+      ?.filter((c) => c?.type === "text" && typeof c.text === "string")
+      .map((c) => c.text)
+      .join("\n")
+      ?.trim() ?? undefined;
+  const meta: AgentMeta | undefined = lastMessage
+    ? {
+        model: lastMessage.model,
+        provider: lastMessage.provider,
+        stopReason: lastMessage.stopReason,
+        usage: lastMessage.usage,
+      }
+    : undefined;
+  return { text, meta };
+}
+
+export const piSpec: AgentSpec = {
+  kind: "pi",
+  isInvocation: (argv) => argv.length > 0 && path.basename(argv[0]) === "pi",
+  buildArgs: (ctx) => {
+    const argv = [...ctx.argv];
+    // Non-interactive print + JSON
+    if (!argv.includes("-p") && !argv.includes("--print")) {
+      argv.splice(argv.length - 1, 0, "-p");
+    }
+    if (
+      ctx.format === "json" &&
+      !argv.includes("--mode") &&
+      !argv.some((a) => a === "--mode")
+    ) {
+      argv.splice(argv.length - 1, 0, "--mode", "json");
+    }
+    // Session defaults
+    // Identity prefix optional; Pi usually doesn't need it, but allow injection
+    if (!(ctx.sendSystemOnce && ctx.systemSent) && argv[ctx.bodyIndex]) {
+      const existingBody = argv[ctx.bodyIndex];
+      argv[ctx.bodyIndex] = [ctx.identityPrefix, existingBody]
+        .filter(Boolean)
+        .join("\n\n");
+    }
+    return argv;
+  },
+  parseOutput: parsePiJson,
+};
@@ -0,0 +1,41 @@
+export type AgentKind = "claude" | "opencode" | "pi" | "codex";
+
+export type AgentMeta = {
+  model?: string;
+  provider?: string;
+  stopReason?: string;
+  usage?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    total?: number;
+  };
+  extra?: Record<string, unknown>;
+};
+
+export type AgentParseResult = {
+  text?: string;
+  mediaUrls?: string[];
+  meta?: AgentMeta;
+};
+
+export type BuildArgsContext = {
+  argv: string[];
+  bodyIndex: number; // index of prompt/body argument in argv
+  isNewSession: boolean;
+  sessionId?: string;
+  sendSystemOnce: boolean;
+  systemSent: boolean;
+  identityPrefix?: string;
+  format?: "text" | "json";
+  sessionArgNew?: string[];
+  sessionArgResume?: string[];
+};
+
+export interface AgentSpec {
+  kind: AgentKind;
+  isInvocation: (argv: string[]) => boolean;
+  buildArgs: (ctx: BuildArgsContext) => string[];
+  parseOutput: (rawStdout: string) => AgentParseResult;
+}
@@ -4,7 +4,7 @@ import { z } from "zod";
 // Preferred binary name for Claude CLI invocations.
 export const CLAUDE_BIN = "claude";
 export const CLAUDE_IDENTITY_PREFIX =
-  "You are Clawd (Claude) running on the user's Mac via warelay. Your scratchpad is /Users/steipete/clawd; this is your folder and you can add what you like in markdown files and/or images. You don't need to be concise, but WhatsApp replies must stay under ~1500 characters. Media you can send: images ≤6MB, audio/video ≤16MB, documents ≤100MB. The prompt may include a media path and an optional Transcript: section—use them when present.";
+  "You are Clawd (Claude) running on the user's Mac via warelay. Your scratchpad is /Users/steipete/clawd; this is your folder and you can add what you like in markdown files and/or images. You don't need to be concise, but WhatsApp replies must stay under ~1500 characters. Media you can send: images ≤6MB, audio/video ≤16MB, documents ≤100MB. The prompt may include a media path and an optional Transcript: section—use them when present. If a prompt is a heartbeat poll and nothing needs attention, reply with exactly HEARTBEAT_OK and nothing else; for any alert, do not include HEARTBEAT_OK.";

 function extractClaudeText(payload: unknown): string | undefined {
  // Best-effort walker to find the primary text field in Claude JSON outputs.
@@ -160,3 +160,6 @@ export function parseClaudeJsonText(raw: string): string | undefined {
  const parsed = parseClaudeJson(raw);
  return parsed?.text;
 }
+
+// Re-export from command-reply for backwards compatibility
+export { summarizeClaudeMetadata } from "./command-reply.js";
@@ -70,7 +70,7 @@ describe("runCommandReply", () => {
      reply: {
        mode: "command",
        command: ["claude", "{{Body}}"],
-        claudeOutputFormat: "json",
+        agent: { kind: "claude", format: "json" },
      },
      templatingCtx: noopTemplateCtx,
      sendSystemOnce: false,
@@ -91,6 +91,75 @@ describe("runCommandReply", () => {
    expect(finalArgv.at(-1)).toContain("You are Clawd (Claude)");
  });

+  it("omits identity prefix on resumed session when sendSystemOnce=true", async () => {
+    const captures: ReplyPayload[] = [];
+    const runner = makeRunner({ stdout: "ok" }, captures);
+    await runCommandReply({
+      reply: {
+        mode: "command",
+        command: ["claude", "{{Body}}"],
+        agent: { kind: "claude", format: "json" },
+      },
+      templatingCtx: noopTemplateCtx,
+      sendSystemOnce: true,
+      isNewSession: false,
+      isFirstTurnInSession: false,
+      systemSent: true,
+      timeoutMs: 1000,
+      timeoutSeconds: 1,
+      commandRunner: runner,
+      enqueue: enqueueImmediate,
+    });
+    const finalArgv = captures[0].argv as string[];
+    expect(finalArgv.at(-1)).not.toContain("You are Clawd (Claude)");
+  });
+
+  it("prepends identity on first turn when sendSystemOnce=true", async () => {
+    const captures: ReplyPayload[] = [];
+    const runner = makeRunner({ stdout: "ok" }, captures);
+    await runCommandReply({
+      reply: {
+        mode: "command",
+        command: ["claude", "{{Body}}"],
+        agent: { kind: "claude", format: "json" },
+      },
+      templatingCtx: noopTemplateCtx,
+      sendSystemOnce: true,
+      isNewSession: true,
+      isFirstTurnInSession: true,
+      systemSent: false,
+      timeoutMs: 1000,
+      timeoutSeconds: 1,
+      commandRunner: runner,
+      enqueue: enqueueImmediate,
+    });
+    const finalArgv = captures[0].argv as string[];
+    expect(finalArgv.at(-1)).toContain("You are Clawd (Claude)");
+  });
+
+  it("still prepends identity if resume session but systemSent=false", async () => {
+    const captures: ReplyPayload[] = [];
+    const runner = makeRunner({ stdout: "ok" }, captures);
+    await runCommandReply({
+      reply: {
+        mode: "command",
+        command: ["claude", "{{Body}}"],
+        agent: { kind: "claude", format: "json" },
+      },
+      templatingCtx: noopTemplateCtx,
+      sendSystemOnce: true,
+      isNewSession: false,
+      isFirstTurnInSession: false,
+      systemSent: false,
+      timeoutMs: 1000,
+      timeoutSeconds: 1,
+      commandRunner: runner,
+      enqueue: enqueueImmediate,
+    });
+    const finalArgv = captures[0].argv as string[];
+    expect(finalArgv.at(-1)).toContain("You are Clawd (Claude)");
+  });
+
  it("picks session resume args when not new", async () => {
    const captures: ReplyPayload[] = [];
    const runner = makeRunner({ stdout: "hi" }, captures);
@@ -98,6 +167,7 @@ describe("runCommandReply", () => {
      reply: {
        mode: "command",
        command: ["cli", "{{Body}}"],
+        agent: { kind: "claude" },
        session: {
          sessionArgNew: ["--new", "{{SessionId}}"],
          sessionArgResume: ["--resume", "{{SessionId}}"],
@@ -123,7 +193,11 @@ describe("runCommandReply", () => {
      throw { stdout: "partial output here", killed: true, signal: "SIGKILL" };
    });
    const { payload, meta } = await runCommandReply({
-      reply: { mode: "command", command: ["echo", "hi"] },
+      reply: {
+        mode: "command",
+        command: ["echo", "hi"],
+        agent: { kind: "claude" },
+      },
      templatingCtx: noopTemplateCtx,
      sendSystemOnce: false,
      isNewSession: true,
@@ -144,7 +218,12 @@ describe("runCommandReply", () => {
      throw { stdout: "", killed: true, signal: "SIGKILL" };
    });
    const { payload } = await runCommandReply({
-      reply: { mode: "command", command: ["echo", "hi"], cwd: "/tmp/work" },
+      reply: {
+        mode: "command",
+        command: ["echo", "hi"],
+        cwd: "/tmp/work",
+        agent: { kind: "claude" },
+      },
      templatingCtx: noopTemplateCtx,
      sendSystemOnce: false,
      isNewSession: true,
@@ -166,7 +245,12 @@ describe("runCommandReply", () => {
      stdout: `hi\nMEDIA:${tmp}\nMEDIA:https://example.com/img.jpg`,
    });
    const { payload } = await runCommandReply({
-      reply: { mode: "command", command: ["echo", "hi"], mediaMaxMb: 1 },
+      reply: {
+        mode: "command",
+        command: ["echo", "hi"],
+        mediaMaxMb: 1,
+        agent: { kind: "claude" },
+      },
      templatingCtx: noopTemplateCtx,
      sendSystemOnce: false,
      isNewSession: true,
@@ -190,7 +274,7 @@ describe("runCommandReply", () => {
      reply: {
        mode: "command",
        command: ["claude", "{{Body}}"],
-        claudeOutputFormat: "json",
+        agent: { kind: "claude", format: "json" },
      },
      templatingCtx: noopTemplateCtx,
      sendSystemOnce: false,
@@ -202,14 +286,18 @@ describe("runCommandReply", () => {
      commandRunner: runner,
      enqueue: enqueueImmediate,
    });
-    expect(meta.claudeMeta).toContain("duration=50ms");
-    expect(meta.claudeMeta).toContain("tool_calls=1");
+    expect(meta.agentMeta?.extra?.summary).toContain("duration=50ms");
+    expect(meta.agentMeta?.extra?.summary).toContain("tool_calls=1");
  });

  it("captures queue wait metrics in meta", async () => {
    const runner = makeRunner({ stdout: "ok" });
    const { meta } = await runCommandReply({
-      reply: { mode: "command", command: ["echo", "{{Body}}"] },
+      reply: {
+        mode: "command",
+        command: ["echo", "{{Body}}"],
+        agent: { kind: "claude" },
+      },
      templatingCtx: noopTemplateCtx,
      sendSystemOnce: false,
      isNewSession: true,
@@ -223,4 +311,79 @@ describe("runCommandReply", () => {
    expect(meta.queuedMs).toBe(25);
    expect(meta.queuedAhead).toBe(2);
  });
+
+  it("handles empty result string without dumping raw JSON", async () => {
+    // Bug fix: Claude CLI returning {"result": ""} should not send raw JSON to WhatsApp
+    // The fix changed from truthy check to explicit typeof check
+    const runner = makeRunner({
+      stdout: '{"result":"","duration_ms":50,"total_cost_usd":0.001}',
+    });
+    const { payload } = await runCommandReply({
+      reply: {
+        mode: "command",
+        command: ["claude", "{{Body}}"],
+        agent: { kind: "claude", format: "json" },
+      },
+      templatingCtx: noopTemplateCtx,
+      sendSystemOnce: false,
+      isNewSession: true,
+      isFirstTurnInSession: true,
+      systemSent: false,
+      timeoutMs: 1000,
+      timeoutSeconds: 1,
+      commandRunner: runner,
+      enqueue: enqueueImmediate,
+    });
+    // Should NOT contain raw JSON - empty result should produce fallback message
+    expect(payload?.text).not.toContain('{"result"');
+    expect(payload?.text).toContain("command produced no output");
+  });
+
+  it("handles empty text string in Claude JSON", async () => {
+    const runner = makeRunner({
+      stdout: '{"text":"","duration_ms":50}',
+    });
+    const { payload } = await runCommandReply({
+      reply: {
+        mode: "command",
+        command: ["claude", "{{Body}}"],
+        agent: { kind: "claude", format: "json" },
+      },
+      templatingCtx: noopTemplateCtx,
+      sendSystemOnce: false,
+      isNewSession: true,
+      isFirstTurnInSession: true,
+      systemSent: false,
+      timeoutMs: 1000,
+      timeoutSeconds: 1,
+      commandRunner: runner,
+      enqueue: enqueueImmediate,
+    });
+    // Empty text should produce fallback message, not raw JSON
+    expect(payload?.text).not.toContain('{"text"');
+    expect(payload?.text).toContain("command produced no output");
+  });
+
+  it("returns actual text when result is non-empty", async () => {
+    const runner = makeRunner({
+      stdout: '{"result":"hello world","duration_ms":50}',
+    });
+    const { payload } = await runCommandReply({
+      reply: {
+        mode: "command",
+        command: ["claude", "{{Body}}"],
+        agent: { kind: "claude", format: "json" },
+      },
+      templatingCtx: noopTemplateCtx,
+      sendSystemOnce: false,
+      isNewSession: true,
+      isFirstTurnInSession: true,
+      systemSent: false,
+      timeoutMs: 1000,
+      timeoutSeconds: 1,
+      commandRunner: runner,
+      enqueue: enqueueImmediate,
+    });
+    expect(payload?.text).toBe("hello world");
+  });
 });
@@ -1,18 +1,14 @@
 import fs from "node:fs/promises";
 import path from "node:path";

+import { type AgentKind, getAgentSpec } from "../agents/index.js";
+import type { AgentMeta } from "../agents/types.js";
 import type { WarelayConfig } from "../config/config.js";
 import { isVerbose, logVerbose } from "../globals.js";
 import { logError } from "../logger.js";
 import { splitMediaFromOutput } from "../media/parse.js";
 import { enqueueCommand } from "../process/command-queue.js";
 import type { runCommandWithTimeout } from "../process/exec.js";
-import {
-  CLAUDE_BIN,
-  CLAUDE_IDENTITY_PREFIX,
-  type ClaudeJsonParseResult,
-  parseClaudeJson,
-} from "./claude.js";
 import { applyTemplate, type TemplateContext } from "./templating.js";
 import type { ReplyPayload } from "./types.js";

@@ -42,7 +38,7 @@ export type CommandReplyMeta = {
  exitCode?: number | null;
  signal?: string | null;
  killed?: boolean;
-  claudeMeta?: string;
+  agentMeta?: AgentMeta;
 };

 export type CommandReplyResult = {
@@ -119,6 +115,9 @@ export async function runCommandReply(
  if (!reply.command?.length) {
    throw new Error("reply.command is required for mode=command");
  }
+  const agentCfg = reply.agent ?? { kind: "claude" };
+  const agentKind: AgentKind = agentCfg.kind ?? "claude";
+  const agent = getAgentSpec(agentKind);

  let argv = reply.command.map((part) => applyTemplate(part, templatingCtx));
  const templatePrefix =
@@ -129,41 +128,24 @@ export async function runCommandReply(
    argv = [argv[0], templatePrefix, ...argv.slice(1)];
  }

-  // Ensure Claude commands can emit plain text by forcing --output-format when configured.
-  if (
-    reply.claudeOutputFormat &&
-    argv.length > 0 &&
-    path.basename(argv[0]) === CLAUDE_BIN
-  ) {
-    const hasOutputFormat = argv.some(
-      (part) =>
-        part === "--output-format" || part.startsWith("--output-format="),
-    );
-    const insertBeforeBody = Math.max(argv.length - 1, 0);
-    if (!hasOutputFormat) {
-      argv = [
-        ...argv.slice(0, insertBeforeBody),
-        "--output-format",
-        reply.claudeOutputFormat,
-        ...argv.slice(insertBeforeBody),
-      ];
-    }
-    const hasPrintFlag = argv.some(
-      (part) => part === "-p" || part === "--print",
-    );
-    if (!hasPrintFlag) {
-      const insertIdx = Math.max(argv.length - 1, 0);
-      argv = [...argv.slice(0, insertIdx), "-p", ...argv.slice(insertIdx)];
-    }
-  }
+  // Default body index is last arg
+  let bodyIndex = Math.max(argv.length - 1, 0);

-  // Inject session args if configured (use resume for existing, session-id for new)
+  // Session args prepared (templated) and injected generically
  if (reply.session) {
+    const defaultNew =
+      agentCfg.kind === "claude"
+        ? ["--session-id", "{{SessionId}}"]
+        : ["--session", "{{SessionId}}"];
+    const defaultResume =
+      agentCfg.kind === "claude"
+        ? ["--resume", "{{SessionId}}"]
+        : ["--session", "{{SessionId}}"];
    const sessionArgList = (
      isNewSession
-        ? (reply.session.sessionArgNew ?? ["--session-id", "{{SessionId}}"])
-        : (reply.session.sessionArgResume ?? ["--resume", "{{SessionId}}"])
-    ).map((part) => applyTemplate(part, templatingCtx));
+        ? (reply.session.sessionArgNew ?? defaultNew)
+        : (reply.session.sessionArgResume ?? defaultResume)
+    ).map((p) => applyTemplate(p, templatingCtx));
    if (sessionArgList.length) {
      const insertBeforeBody = reply.session.sessionArgBeforeBody ?? true;
      const insertAt =
@@ -173,20 +155,24 @@ export async function runCommandReply(
        ...sessionArgList,
        ...argv.slice(insertAt),
      ];
+      bodyIndex = Math.max(argv.length - 1, 0);
    }
  }

-  let finalArgv = argv;
-  const isClaudeInvocation =
-    finalArgv.length > 0 && path.basename(finalArgv[0]) === CLAUDE_BIN;
-  if (isClaudeInvocation && finalArgv.length > 0) {
-    const bodyIdx = finalArgv.length - 1;
-    const existingBody = finalArgv[bodyIdx] ?? "";
-    finalArgv = [
-      ...finalArgv.slice(0, bodyIdx),
-      [CLAUDE_IDENTITY_PREFIX, existingBody].filter(Boolean).join("\n\n"),
-    ];
-  }
+  const shouldApplyAgent = agent.isInvocation(argv);
+  const finalArgv = shouldApplyAgent
+    ? agent.buildArgs({
+        argv,
+        bodyIndex,
+        isNewSession,
+        sessionId: templatingCtx.SessionId,
+        sendSystemOnce,
+        systemSent,
+        identityPrefix: agentCfg.identityPrefix,
+        format: agentCfg.format,
+      })
+    : argv;
+
  logVerbose(
    `Running command auto-reply: ${finalArgv.join(" ")}${reply.cwd ? ` (cwd: ${reply.cwd})` : ""}`,
  );
@@ -215,28 +201,14 @@ export async function runCommandReply(
    if (stderr?.trim()) {
      logVerbose(`Command auto-reply stderr: ${stderr.trim()}`);
    }
-    let parsed: ClaudeJsonParseResult | undefined;
-    if (
-      trimmed &&
-      (reply.claudeOutputFormat === "json" || isClaudeInvocation)
-    ) {
-      parsed = parseClaudeJson(trimmed);
-      if (parsed?.parsed && isVerbose()) {
-        const summary = summarizeClaudeMetadata(parsed.parsed);
-        if (summary) logVerbose(`Claude JSON meta: ${summary}`);
-        logVerbose(
-          `Claude JSON raw: ${JSON.stringify(parsed.parsed, null, 2)}`,
-        );
-      }
-      if (parsed?.text) {
-        logVerbose(
-          `Claude JSON parsed -> ${parsed.text.slice(0, 120)}${parsed.text.length > 120 ? "…" : ""}`,
-        );
-        trimmed = parsed.text.trim();
-      } else {
-        logVerbose("Claude JSON parse failed; returning raw stdout");
-      }
+
+    const parsed = trimmed ? agent.parseOutput(trimmed) : undefined;
+    // Treat empty string as "no content" so we can fall back to the friendly
+    // "(command produced no output)" message instead of echoing raw JSON.
+    if (parsed && parsed.text !== undefined) {
+      trimmed = parsed.text.trim();
    }
+
    const { text: cleanedText, mediaUrls: mediaFound } =
      splitMediaFromOutput(trimmed);
    trimmed = cleanedText;
@@ -247,7 +219,7 @@ export async function runCommandReply(
      logVerbose("No MEDIA token extracted from final text");
    }
    if (!trimmed && !mediaFromCommand) {
-      const meta = parsed ? summarizeClaudeMetadata(parsed.parsed) : undefined;
+      const meta = parsed?.meta?.extra?.summary ?? undefined;
      trimmed = `(command produced no output${meta ? `; ${meta}` : ""})`;
      logVerbose("No text/media produced; injecting fallback notice to user");
    }
@@ -257,8 +229,13 @@ export async function runCommandReply(
      console.error(
        `Command auto-reply exited with code ${code ?? "unknown"} (signal: ${signal ?? "none"})`,
      );
+      // Include any partial output or stderr in error message
+      const partialOut = trimmed
+        ? `\n\nOutput: ${trimmed.slice(0, 500)}${trimmed.length > 500 ? "..." : ""}`
+        : "";
+      const errorText = `⚠️ Command exited with code ${code ?? "unknown"}${signal ? ` (${signal})` : ""}${partialOut}`;
      return {
-        payload: undefined,
+        payload: { text: errorText },
        meta: {
          durationMs: Date.now() - started,
          queuedMs,
@@ -266,9 +243,7 @@ export async function runCommandReply(
          exitCode: code,
          signal,
          killed,
-          claudeMeta: parsed
-            ? summarizeClaudeMetadata(parsed.parsed)
-            : undefined,
+          agentMeta: parsed?.meta,
        },
      };
    }
@@ -276,8 +251,9 @@ export async function runCommandReply(
      console.error(
        `Command auto-reply process killed before completion (exit code ${code ?? "unknown"})`,
      );
+      const errorText = `⚠️ Command was killed before completion (exit code ${code ?? "unknown"})`;
      return {
-        payload: undefined,
+        payload: { text: errorText },
        meta: {
          durationMs: Date.now() - started,
          queuedMs,
@@ -285,9 +261,7 @@ export async function runCommandReply(
          exitCode: code,
          signal,
          killed,
-          claudeMeta: parsed
-            ? summarizeClaudeMetadata(parsed.parsed)
-            : undefined,
+          agentMeta: parsed?.meta,
        },
      };
    }
@@ -335,7 +309,7 @@ export async function runCommandReply(
      exitCode: code,
      signal,
      killed,
-      claudeMeta: parsed ? summarizeClaudeMetadata(parsed.parsed) : undefined,
+      agentMeta: parsed?.meta,
    };
    if (isVerbose()) {
      logVerbose(`Command auto-reply meta: ${JSON.stringify(meta)}`);
@@ -377,8 +351,11 @@ export async function runCommandReply(
      };
    }
    logError(`Command auto-reply failed after ${elapsed}ms: ${String(err)}`);
+    // Send error message to user so they know the command failed
+    const errMsg = err instanceof Error ? err.message : String(err);
+    const errorText = `⚠️ Command failed: ${errMsg}`;
    return {
-      payload: undefined,
+      payload: { text: errorText },
      meta: {
        durationMs: elapsed,
        queuedMs,
@@ -0,0 +1,104 @@
+// Helpers specific to Opencode CLI output/argv handling.
+
+// Preferred binary name for Opencode CLI invocations.
+export const OPENCODE_BIN = "opencode";
+
+export const OPENCODE_IDENTITY_PREFIX =
+  "You are Openclawd running on the user's Mac via warelay. Your scratchpad is /Users/steipete/openclawd; this is your folder and you can add what you like in markdown files and/or images. You don't need to be concise, but WhatsApp replies must stay under ~1500 characters. Media you can send: images ≤6MB, audio/video ≤16MB, documents ≤100MB. The prompt may include a media path and an optional Transcript: section—use them when present. If a prompt is a heartbeat poll and nothing needs attention, reply with exactly HEARTBEAT_OK and nothing else; for any alert, do not include HEARTBEAT_OK.";
+
+export type OpencodeJsonParseResult = {
+  text?: string;
+  parsed: unknown[];
+  valid: boolean;
+  meta?: {
+    durationMs?: number;
+    cost?: number;
+    tokens?: {
+      input?: number;
+      output?: number;
+    };
+  };
+};
+
+export function parseOpencodeJson(raw: string): OpencodeJsonParseResult {
+  const lines = raw.split(/\n+/).filter((s) => s.trim());
+  const parsed: unknown[] = [];
+  let text = "";
+  let valid = false;
+  let startTime: number | undefined;
+  let endTime: number | undefined;
+  let cost = 0;
+  let inputTokens = 0;
+  let outputTokens = 0;
+
+  for (const line of lines) {
+    try {
+      const event = JSON.parse(line);
+      parsed.push(event);
+      if (event && typeof event === "object") {
+        // Opencode emits a stream of events.
+        if (event.type === "step_start") {
+          valid = true;
+          if (typeof event.timestamp === "number") {
+            if (startTime === undefined || event.timestamp < startTime) {
+              startTime = event.timestamp;
+            }
+          }
+        }
+
+        if (event.type === "text" && event.part?.text) {
+          text += event.part.text;
+          valid = true;
+        }
+
+        if (event.type === "step_finish") {
+          valid = true;
+          if (typeof event.timestamp === "number") {
+            endTime = event.timestamp;
+          }
+          if (event.part) {
+            if (typeof event.part.cost === "number") {
+              cost += event.part.cost;
+            }
+            if (event.part.tokens) {
+              inputTokens += event.part.tokens.input || 0;
+              outputTokens += event.part.tokens.output || 0;
+            }
+          }
+        }
+      }
+    } catch {
+      // ignore non-JSON lines
+    }
+  }
+
+  const meta: OpencodeJsonParseResult["meta"] = {};
+  if (startTime !== undefined && endTime !== undefined) {
+    meta.durationMs = endTime - startTime;
+  }
+  if (cost > 0) meta.cost = cost;
+  if (inputTokens > 0 || outputTokens > 0) {
+    meta.tokens = { input: inputTokens, output: outputTokens };
+  }
+
+  return {
+    text: text || undefined,
+    parsed,
+    valid: valid && parsed.length > 0,
+    meta: Object.keys(meta).length > 0 ? meta : undefined,
+  };
+}
+
+export function summarizeOpencodeMetadata(
+  meta: OpencodeJsonParseResult["meta"],
+): string | undefined {
+  if (!meta) return undefined;
+  const parts: string[] = [];
+  if (meta.durationMs !== undefined)
+    parts.push(`duration=${meta.durationMs}ms`);
+  if (meta.cost !== undefined) parts.push(`cost=$${meta.cost.toFixed(4)}`);
+  if (meta.tokens) {
+    parts.push(`tokens=${meta.tokens.input}+${meta.tokens.output}`);
+  }
+  return parts.length ? parts.join(", ") : undefined;
+}
@@ -146,9 +146,16 @@ export async function getReplyFromConfig(

  // Optional allowlist by origin number (E.164 without whatsapp: prefix)
  const allowFrom = cfg.inbound?.allowFrom;
-  if (Array.isArray(allowFrom) && allowFrom.length > 0) {
-    const from = (ctx.From ?? "").replace(/^whatsapp:/, "");
-    if (!allowFrom.includes(from)) {
+  const from = (ctx.From ?? "").replace(/^whatsapp:/, "");
+  const to = (ctx.To ?? "").replace(/^whatsapp:/, "");
+  const isSamePhone = from && to && from === to;
+
+  // Same-phone mode (self-messaging) is always allowed
+  if (isSamePhone) {
+    logVerbose(`Allowing same-phone mode: from === to (${from})`);
+  } else if (Array.isArray(allowFrom) && allowFrom.length > 0) {
+    // Support "*" as wildcard to allow all senders
+    if (!allowFrom.includes("*") && !allowFrom.includes(from)) {
      logVerbose(
        `Skipping auto-reply: sender ${from || "<unknown>"} not in allowFrom list`,
      );
@@ -258,8 +265,8 @@ export async function getReplyFromConfig(
        timeoutSeconds,
        commandRunner,
      });
-      if (meta.claudeMeta && isVerbose()) {
-        logVerbose(`Claude JSON meta: ${meta.claudeMeta}`);
+      if (meta.agentMeta && isVerbose()) {
+        logVerbose(`Agent meta: ${JSON.stringify(meta.agentMeta)}`);
      }
      return payload;
    } finally {
@@ -80,6 +80,10 @@ describe("cli program", () => {
  });

  it("runs relay tmux attach command", async () => {
+    const originalIsTTY = process.stdout.isTTY;
+    (process.stdout as typeof process.stdout & { isTTY?: boolean }).isTTY =
+      true;
+
    const program = buildProgram();
    await program.parseAsync(["relay:tmux:attach"], { from: "user" });
    expect(spawnRelayTmux).toHaveBeenCalledWith(
@@ -87,5 +91,39 @@ describe("cli program", () => {
      true,
      false,
    );
+
+    (process.stdout as typeof process.stdout & { isTTY?: boolean }).isTTY =
+      originalIsTTY;
+  });
+
+  it("runs relay heartbeat command", async () => {
+    pickProvider.mockResolvedValue("web");
+    monitorWebProvider.mockResolvedValue(undefined);
+    const originalExit = runtime.exit;
+    runtime.exit = vi.fn();
+    const program = buildProgram();
+    await program.parseAsync(["relay:heartbeat"], { from: "user" });
+    expect(logWebSelfId).toHaveBeenCalled();
+    expect(monitorWebProvider).toHaveBeenCalledWith(
+      false,
+      undefined,
+      true,
+      undefined,
+      runtime,
+      undefined,
+      { replyHeartbeatNow: true },
+    );
+    expect(runtime.exit).not.toHaveBeenCalled();
+    runtime.exit = originalExit;
+  });
+
+  it("runs relay heartbeat tmux helper", async () => {
+    const program = buildProgram();
+    await program.parseAsync(["relay:heartbeat:tmux"], { from: "user" });
+    const shouldAttach = Boolean(process.stdout.isTTY);
+    expect(spawnRelayTmux).toHaveBeenCalledWith(
+      "pnpm warelay relay --verbose --heartbeat-now",
+      shouldAttach,
+    );
  });
 });
@@ -6,14 +6,18 @@ import { webhookCommand } from "../commands/webhook.js";
 import { loadConfig } from "../config/config.js";
 import { ensureTwilioEnv } from "../env.js";
 import { danger, info, setVerbose, setYes } from "../globals.js";
+import { getResolvedLoggerSettings } from "../logging.js";
 import {
  loginWeb,
  logoutWeb,
  monitorWebProvider,
  pickProvider,
+  resolveHeartbeatRecipients,
+  runWebHeartbeatOnce,
  type WebMonitorTuning,
 } from "../provider-web.js";
 import { defaultRuntime } from "../runtime.js";
+import { runTwilioHeartbeatOnce } from "../twilio/heartbeat.js";
 import type { Provider } from "../utils.js";
 import { VERSION } from "../version.js";
 import {
@@ -174,6 +178,114 @@ Examples:
      }
    });

+  program
+    .command("heartbeat")
+    .description(
+      "Trigger a heartbeat or manual send once (web or twilio, no tmux)",
+    )
+    .option("--provider <provider>", "auto | web | twilio", "auto")
+    .option("--to <number>", "Override target E.164; defaults to allowFrom[0]")
+    .option(
+      "--session-id <id>",
+      "Force a session id for this heartbeat (resumes a specific Claude session)",
+    )
+    .option(
+      "--all",
+      "Send heartbeat to all active sessions (or allowFrom entries when none)",
+      false,
+    )
+    .option(
+      "--message <text>",
+      "Send a custom message instead of the heartbeat probe (web or twilio provider)",
+    )
+    .option("--body <text>", "Alias for --message")
+    .option("--dry-run", "Print the resolved payload without sending", false)
+    .option("--verbose", "Verbose logging", false)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  warelay heartbeat                 # uses web session + first allowFrom contact
+  warelay heartbeat --verbose       # prints detailed heartbeat logs
+  warelay heartbeat --to +1555123   # override destination
+  warelay heartbeat --session-id <uuid> --to +1555123   # resume a specific session
+  warelay heartbeat --message "Ping" --provider twilio
+  warelay heartbeat --all           # send to every active session recipient or allowFrom entry`,
+    )
+    .action(async (opts) => {
+      setVerbose(Boolean(opts.verbose));
+      const cfg = loadConfig();
+      const allowAll = Boolean(opts.all);
+      const resolution = resolveHeartbeatRecipients(cfg, {
+        to: opts.to,
+        all: allowAll,
+      });
+      if (
+        !opts.to &&
+        !allowAll &&
+        resolution.source === "session-ambiguous" &&
+        resolution.recipients.length > 1
+      ) {
+        defaultRuntime.error(
+          danger(
+            `Multiple active sessions found (${resolution.recipients.join(", ")}). Pass --to <E.164> or --all to send to all.`,
+          ),
+        );
+        defaultRuntime.exit(1);
+      }
+      const recipients = resolution.recipients;
+      if (!recipients || recipients.length === 0) {
+        defaultRuntime.error(
+          danger(
+            "No destination found. Add inbound.allowFrom numbers or pass --to <E.164>.",
+          ),
+        );
+        defaultRuntime.exit(1);
+      }
+      const providerPref = String(opts.provider ?? "auto");
+      if (!["auto", "web", "twilio"].includes(providerPref)) {
+        defaultRuntime.error("--provider must be auto, web, or twilio");
+        defaultRuntime.exit(1);
+      }
+
+      const overrideBody =
+        (opts.message as string | undefined) ||
+        (opts.body as string | undefined) ||
+        undefined;
+      const dryRun = Boolean(opts.dryRun);
+
+      const provider =
+        providerPref === "twilio"
+          ? "twilio"
+          : await pickProvider(providerPref as "auto" | "web");
+      if (provider === "twilio") ensureTwilioEnv();
+
+      try {
+        for (const to of recipients) {
+          if (provider === "web") {
+            await runWebHeartbeatOnce({
+              to,
+              verbose: Boolean(opts.verbose),
+              runtime: defaultRuntime,
+              sessionId: opts.sessionId,
+              overrideBody,
+              dryRun,
+            });
+          } else {
+            await runTwilioHeartbeatOnce({
+              to,
+              verbose: Boolean(opts.verbose),
+              runtime: defaultRuntime,
+              overrideBody,
+              dryRun,
+            });
+          }
+        }
+      } catch {
+        defaultRuntime.exit(1);
+      }
+    });
+
  program
    .command("relay")
    .description("Auto-reply to inbound messages (auto-selects web or twilio)")
@@ -197,6 +309,11 @@ Examples:
      "Initial reconnect backoff for web relay (ms)",
    )
    .option("--web-retry-max <ms>", "Max reconnect backoff for web relay (ms)")
+    .option(
+      "--heartbeat-now",
+      "Run a heartbeat immediately when relay starts (web provider)",
+      false,
+    )
    .option("--verbose", "Verbose logging", false)
    .addHelpText(
      "after",
@@ -211,6 +328,8 @@ Examples:
    )
    .action(async (opts) => {
      setVerbose(Boolean(opts.verbose));
+      const { file: logFile, level: logLevel } = getResolvedLoggerSettings();
+      defaultRuntime.log(info(`logs: ${logFile} (level ${logLevel})`));
      const providerPref = String(opts.provider ?? "auto");
      if (!["auto", "web", "twilio"].includes(providerPref)) {
        defaultRuntime.error("--provider must be auto, web, or twilio");
@@ -234,6 +353,7 @@ Examples:
        opts.webRetryMax !== undefined
          ? Number.parseInt(String(opts.webRetryMax), 10)
          : undefined;
+      const heartbeatNow = Boolean(opts.heartbeatNow);
      if (Number.isNaN(intervalSeconds) || intervalSeconds <= 0) {
        defaultRuntime.error("Interval must be a positive integer");
        defaultRuntime.exit(1);
@@ -281,6 +401,7 @@ Examples:

      const webTuning: WebMonitorTuning = {};
      if (webHeartbeat !== undefined) webTuning.heartbeatSeconds = webHeartbeat;
+      if (heartbeatNow) webTuning.replyHeartbeatNow = true;
      const reconnect: WebMonitorTuning["reconnect"] = {};
      if (webRetries !== undefined) reconnect.maxAttempts = webRetries;
      if (webRetryInitial !== undefined) reconnect.initialMs = webRetryInitial;
@@ -333,6 +454,64 @@ Examples:
      await monitorTwilio(intervalSeconds, lookbackMinutes);
    });

+  program
+    .command("relay:heartbeat")
+    .description(
+      "Run relay with an immediate heartbeat (no tmux); requires web provider",
+    )
+    .option("--provider <provider>", "auto | web", "auto")
+    .option("--verbose", "Verbose logging", false)
+    .action(async (opts) => {
+      setVerbose(Boolean(opts.verbose));
+      const { file: logFile, level: logLevel } = getResolvedLoggerSettings();
+      defaultRuntime.log(info(`logs: ${logFile} (level ${logLevel})`));
+      const providerPref = String(opts.provider ?? "auto");
+      if (!["auto", "web"].includes(providerPref)) {
+        defaultRuntime.error("--provider must be auto or web");
+        defaultRuntime.exit(1);
+        return;
+      }
+      const provider = await pickProvider(providerPref as "auto" | "web");
+      if (provider !== "web") {
+        defaultRuntime.error(
+          danger(
+            "Heartbeat relay is only supported for the web provider. Link with `warelay login --verbose`.",
+          ),
+        );
+        defaultRuntime.exit(1);
+        return;
+      }
+
+      logWebSelfId(defaultRuntime, true);
+      const cfg = loadConfig();
+      const effectiveHeartbeat = resolveHeartbeatSeconds(cfg, undefined);
+      const effectivePolicy = resolveReconnectPolicy(cfg, undefined);
+      defaultRuntime.log(
+        info(
+          `Web relay health: heartbeat ${effectiveHeartbeat}s, retries ${effectivePolicy.maxAttempts || "∞"}, backoff ${effectivePolicy.initialMs}→${effectivePolicy.maxMs}ms x${effectivePolicy.factor} (jitter ${Math.round(effectivePolicy.jitter * 100)}%)`,
+        ),
+      );
+
+      try {
+        await monitorWebProvider(
+          Boolean(opts.verbose),
+          undefined,
+          true,
+          undefined,
+          defaultRuntime,
+          undefined,
+          { replyHeartbeatNow: true },
+        );
+      } catch (err) {
+        defaultRuntime.error(
+          danger(
+            `Web relay failed: ${String(err)}. Re-link with 'warelay login --provider web'.`,
+          ),
+        );
+        defaultRuntime.exit(1);
+      }
+    });
+
  program
    .command("status")
    .description("Show recent WhatsApp messages (sent and received)")
@@ -417,13 +596,16 @@ Examples:
    )
    .action(async () => {
      try {
+        const shouldAttach = Boolean(process.stdout.isTTY);
        const session = await spawnRelayTmux(
          "pnpm warelay relay --verbose",
-          true,
+          shouldAttach,
        );
        defaultRuntime.log(
          info(
-            `tmux session started and attached: ${session} (pane running "pnpm warelay relay --verbose")`,
+            shouldAttach
+              ? `tmux session started and attached: ${session} (pane running "pnpm warelay relay --verbose")`
+              : `tmux session started: ${session} (pane running "pnpm warelay relay --verbose"); attach manually with "tmux attach -t ${session}"`,
          ),
        );
      } catch (err) {
@@ -441,6 +623,15 @@ Examples:
    )
    .action(async () => {
      try {
+        if (!process.stdout.isTTY) {
+          defaultRuntime.error(
+            danger(
+              "Cannot attach: stdout is not a TTY. Run this in a terminal or use 'tmux attach -t warelay-relay' manually.",
+            ),
+          );
+          defaultRuntime.exit(1);
+          return;
+        }
        await spawnRelayTmux("pnpm warelay relay --verbose", true, false);
        defaultRuntime.log(info("Attached to warelay-relay session."));
      } catch (err) {
@@ -451,5 +642,34 @@ Examples:
      }
    });

+  program
+    .command("relay:heartbeat:tmux")
+    .description(
+      "Run relay --verbose with an immediate heartbeat inside tmux (session warelay-relay), then attach",
+    )
+    .action(async () => {
+      try {
+        const shouldAttach = Boolean(process.stdout.isTTY);
+        const session = await spawnRelayTmux(
+          "pnpm warelay relay --verbose --heartbeat-now",
+          shouldAttach,
+        );
+        defaultRuntime.log(
+          info(
+            shouldAttach
+              ? `tmux session started and attached: ${session} (pane running "pnpm warelay relay --verbose --heartbeat-now")`
+              : `tmux session started: ${session} (pane running "pnpm warelay relay --verbose --heartbeat-now"); attach manually with "tmux attach -t ${session}"`,
+          ),
+        );
+      } catch (err) {
+        defaultRuntime.error(
+          danger(
+            `Failed to start relay tmux session with heartbeat: ${String(err)}`,
+          ),
+        );
+        defaultRuntime.exit(1);
+      }
+    });
+
  return program;
 }
@@ -4,6 +4,10 @@ import type { CliDeps } from "../cli/deps.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { sendCommand } from "./send.js";

+vi.mock("../web/ipc.js", () => ({
+  sendViaIpc: vi.fn().mockResolvedValue(null),
+}));
+
 const runtime: RuntimeEnv = {
  log: vi.fn(),
  error: vi.fn(),
@@ -1,7 +1,8 @@
 import type { CliDeps } from "../cli/deps.js";
-import { info } from "../globals.js";
+import { info, success } from "../globals.js";
 import type { RuntimeEnv } from "../runtime.js";
 import type { Provider } from "../utils.js";
+import { sendViaIpc } from "../web/ipc.js";

 export async function sendCommand(
  opts: {
@@ -39,6 +40,40 @@ export async function sendCommand(
    if (waitSeconds !== 0) {
      runtime.log(info("Wait/poll are Twilio-only; ignored for provider=web."));
    }
+
+    // Try to send via IPC to running relay first (avoids Signal session corruption)
+    const ipcResult = await sendViaIpc(opts.to, opts.message, opts.media);
+    if (ipcResult) {
+      if (ipcResult.success) {
+        runtime.log(
+          success(`✅ Sent via relay IPC. Message ID: ${ipcResult.messageId}`),
+        );
+        if (opts.json) {
+          runtime.log(
+            JSON.stringify(
+              {
+                provider: "web",
+                via: "ipc",
+                to: opts.to,
+                messageId: ipcResult.messageId,
+                mediaUrl: opts.media ?? null,
+              },
+              null,
+              2,
+            ),
+          );
+        }
+        return;
+      }
+      // IPC failed but relay is running - warn and fall back
+      runtime.log(
+        info(
+          `IPC send failed (${ipcResult.error}), falling back to direct connection`,
+        ),
+      );
+    }
+
+    // Fall back to direct connection (creates new Baileys socket)
    const res = await deps
      .sendMessageWeb(opts.to, opts.message, {
        verbose: false,
@@ -53,6 +88,7 @@ export async function sendCommand(
        JSON.stringify(
          {
            provider: "web",
+            via: "direct",
            to: opts.to,
            messageId: res.messageId,
            mediaUrl: opts.media ?? null,
@@ -5,14 +5,16 @@ import path from "node:path";
 import JSON5 from "json5";
 import { z } from "zod";

+import type { AgentKind } from "../agents/index.js";
+
 export type ReplyMode = "text" | "command";
-export type ClaudeOutputFormat = "text" | "json" | "stream-json";
 export type SessionScope = "per-sender" | "global";

 export type SessionConfig = {
  scope?: SessionScope;
  resetTriggers?: string[];
  idleMinutes?: number;
+  heartbeatIdleMinutes?: number;
  store?: string;
  sessionArgNew?: string[];
  sessionArgResume?: string[];
@@ -20,6 +22,7 @@ export type SessionConfig = {
  sendSystemOnce?: boolean;
  sessionIntro?: string;
  typingIntervalSeconds?: number;
+  heartbeatMinutes?: number;
 };

 export type LoggingConfig = {
@@ -44,6 +47,9 @@ export type WarelayConfig = {
  logging?: LoggingConfig;
  inbound?: {
    allowFrom?: string[]; // E.164 numbers allowed to trigger auto-reply (without whatsapp:)
+    messagePrefix?: string; // Prefix added to all inbound messages (default: "[warelay]" if no allowFrom, else "")
+    responsePrefix?: string; // Prefix auto-added to all outbound replies (e.g., "🦞")
+    timestampPrefix?: boolean | string; // true/false or IANA timezone string (default: true with UTC)
    transcribeAudio?: {
      // Optional CLI to turn inbound audio into text; templated args, must output transcript to stdout.
      command: string[];
@@ -51,17 +57,22 @@ export type WarelayConfig = {
    };
    reply?: {
      mode: ReplyMode;
-      text?: string; // for mode=text, can contain {{Body}}
-      command?: string[]; // for mode=command, argv with templates
-      cwd?: string; // working directory for command execution
-      template?: string; // prepend template string when building command/prompt
-      timeoutSeconds?: number; // optional command timeout; defaults to 600s
-      bodyPrefix?: string; // optional string prepended to Body before templating
-      mediaUrl?: string; // optional media attachment (path or URL)
+      text?: string;
+      command?: string[];
+      cwd?: string;
+      template?: string;
+      timeoutSeconds?: number;
+      bodyPrefix?: string;
+      mediaUrl?: string;
      session?: SessionConfig;
-      claudeOutputFormat?: ClaudeOutputFormat; // when command starts with `claude`, force an output format
-      mediaMaxMb?: number; // optional cap for outbound media (default 5MB)
-      typingIntervalSeconds?: number; // how often to refresh typing indicator while command runs
+      mediaMaxMb?: number;
+      typingIntervalSeconds?: number;
+      heartbeatMinutes?: number;
+      agent?: {
+        kind: AgentKind;
+        format?: "text" | "json";
+        identityPrefix?: string;
+      };
    };
  };
  web?: WebConfig;
@@ -88,6 +99,7 @@ const ReplySchema = z
          .optional(),
        resetTriggers: z.array(z.string()).optional(),
        idleMinutes: z.number().int().positive().optional(),
+        heartbeatIdleMinutes: z.number().int().positive().optional(),
        store: z.string().optional(),
        sessionArgNew: z.array(z.string()).optional(),
        sessionArgResume: z.array(z.string()).optional(),
@@ -97,13 +109,18 @@ const ReplySchema = z
        typingIntervalSeconds: z.number().int().positive().optional(),
      })
      .optional(),
-    claudeOutputFormat: z
-      .union([
-        z.literal("text"),
-        z.literal("json"),
-        z.literal("stream-json"),
-        z.undefined(),
-      ])
+    heartbeatMinutes: z.number().int().nonnegative().optional(),
+    agent: z
+      .object({
+        kind: z.union([
+          z.literal("claude"),
+          z.literal("opencode"),
+          z.literal("pi"),
+          z.literal("codex"),
+        ]),
+        format: z.union([z.literal("text"), z.literal("json")]).optional(),
+        identityPrefix: z.string().optional(),
+      })
      .optional(),
  })
  .refine(
@@ -134,6 +151,9 @@ const WarelaySchema = z.object({
  inbound: z
    .object({
      allowFrom: z.array(z.string()).optional(),
+      messagePrefix: z.string().optional(),
+      responsePrefix: z.string().optional(),
+      timestampPrefix: z.union([z.boolean(), z.string()]).optional(),
      transcribeAudio: z
        .object({
          command: z.array(z.string()),
@@ -9,6 +9,18 @@ import { createMockTwilio } from "../test/mocks/twilio.js";
 import * as exec from "./process/exec.js";
 import { withWhatsAppPrefix } from "./utils.js";

+// Mock config to avoid loading real user config
+vi.mock("../src/config/config.js", () => ({
+  loadConfig: vi.fn().mockReturnValue({
+    inbound: {
+      allowFrom: ["*"],
+      messagePrefix: undefined,
+      responsePrefix: undefined,
+      timestampPrefix: false,
+    },
+  }),
+}));
+
 // Twilio mock factory shared across tests
 vi.mock("twilio", () => {
  const { factory } = createMockTwilio();
@@ -93,6 +105,64 @@ describe("config and templating", () => {
    expect(onReplyStart).toHaveBeenCalled();
  });

+  it("getReplyFromConfig allows same-phone mode (from === to) without allowFrom", async () => {
+    const cfg = {
+      inbound: {
+        // No allowFrom configured
+        reply: {
+          mode: "text" as const,
+          text: "Echo: {{Body}}",
+        },
+      },
+    };
+
+    const result = await index.getReplyFromConfig(
+      { Body: "hello", From: "+1555", To: "+1555" },
+      undefined,
+      cfg,
+    );
+    expect(result?.text).toBe("Echo: hello");
+  });
+
+  it("getReplyFromConfig allows same-phone mode even when not in allowFrom list", async () => {
+    const cfg = {
+      inbound: {
+        allowFrom: ["+9999"], // Different number
+        reply: {
+          mode: "text" as const,
+          text: "Reply: {{Body}}",
+        },
+      },
+    };
+
+    // Same-phone mode should bypass allowFrom check
+    const result = await index.getReplyFromConfig(
+      { Body: "test", From: "+1555", To: "+1555" },
+      undefined,
+      cfg,
+    );
+    expect(result?.text).toBe("Reply: test");
+  });
+
+  it("getReplyFromConfig rejects non-same-phone when not in allowFrom", async () => {
+    const cfg = {
+      inbound: {
+        allowFrom: ["+9999"],
+        reply: {
+          mode: "text" as const,
+          text: "Should not see this",
+        },
+      },
+    };
+
+    const result = await index.getReplyFromConfig(
+      { Body: "test", From: "+1555", To: "+2666" },
+      undefined,
+      cfg,
+    );
+    expect(result).toBeUndefined();
+  });
+
  it("getReplyFromConfig templating includes media fields", async () => {
    const cfg = {
      inbound: {
@@ -692,7 +762,7 @@ describe("config and templating", () => {
        reply: {
          mode: "command" as const,
          command: ["claude", "{{Body}}"],
-          claudeOutputFormat: "text" as const,
+          agent: { kind: "claude", format: "text" as const },
        },
      },
    };
@@ -732,7 +802,7 @@ describe("config and templating", () => {
        reply: {
          mode: "command" as const,
          command: ["claude", "{{Body}}"],
-          claudeOutputFormat: "json" as const,
+          agent: { kind: "claude", format: "json" as const },
        },
      },
    };
@@ -760,7 +830,7 @@ describe("config and templating", () => {
        reply: {
          mode: "command" as const,
          command: ["claude", "{{Body}}"],
-          // No claudeOutputFormat set on purpose
+          agent: { kind: "claude" },
        },
      },
    };
@@ -117,5 +117,23 @@ const isMain =
  process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];

 if (isMain) {
+  // Global error handlers to prevent silent crashes from unhandled rejections/exceptions.
+  // These log the error and exit gracefully instead of crashing without trace.
+  process.on("unhandledRejection", (reason, _promise) => {
+    console.error(
+      "[warelay] Unhandled promise rejection:",
+      reason instanceof Error ? (reason.stack ?? reason.message) : reason,
+    );
+    process.exit(1);
+  });
+
+  process.on("uncaughtException", (error) => {
+    console.error(
+      "[warelay] Uncaught exception:",
+      error.stack ?? error.message,
+    );
+    process.exit(1);
+  });
+
  program.parseAsync(process.argv);
 }
@@ -28,6 +28,7 @@ type ResolvedSettings = {
  level: LevelWithSilent;
  file: string;
 };
+export type LoggerResolvedSettings = ResolvedSettings;

 let cachedLogger: Logger | null = null;
 let cachedSettings: ResolvedSettings | null = null;
@@ -87,6 +88,10 @@ export function getChildLogger(
  return getLogger().child(bindings ?? {}, opts);
 }

+export function getResolvedLoggerSettings(): LoggerResolvedSettings {
+  return resolveSettings();
+}
+
 // Test helpers
 export function setLoggerOverride(settings: LoggerSettings | null) {
  overrideSettings = settings;
@@ -0,0 +1,133 @@
+import path from "node:path";
+
+import { type MediaKind, mediaKindFromMime } from "./constants.js";
+
+// Map common mimes to preferred file extensions.
+const EXT_BY_MIME: Record<string, string> = {
+  "image/jpeg": ".jpg",
+  "image/png": ".png",
+  "image/webp": ".webp",
+  "image/gif": ".gif",
+  "audio/ogg": ".ogg",
+  "audio/mpeg": ".mp3",
+  "video/mp4": ".mp4",
+  "application/pdf": ".pdf",
+  "text/plain": ".txt",
+};
+
+const MIME_BY_EXT: Record<string, string> = Object.fromEntries(
+  Object.entries(EXT_BY_MIME).map(([mime, ext]) => [ext, mime]),
+);
+
+function normalizeHeaderMime(mime?: string | null): string | undefined {
+  if (!mime) return undefined;
+  const cleaned = mime.split(";")[0]?.trim().toLowerCase();
+  return cleaned || undefined;
+}
+
+function sniffMime(buffer?: Buffer): string | undefined {
+  if (!buffer || buffer.length < 4) return undefined;
+
+  // JPEG: FF D8 FF
+  if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+    return "image/jpeg";
+  }
+
+  // PNG: 89 50 4E 47 0D 0A 1A 0A
+  if (
+    buffer.length >= 8 &&
+    buffer[0] === 0x89 &&
+    buffer[1] === 0x50 &&
+    buffer[2] === 0x4e &&
+    buffer[3] === 0x47 &&
+    buffer[4] === 0x0d &&
+    buffer[5] === 0x0a &&
+    buffer[6] === 0x1a &&
+    buffer[7] === 0x0a
+  ) {
+    return "image/png";
+  }
+
+  // GIF: GIF87a / GIF89a
+  if (buffer.length >= 6) {
+    const sig = buffer.subarray(0, 6).toString("ascii");
+    if (sig === "GIF87a" || sig === "GIF89a") return "image/gif";
+  }
+
+  // WebP: RIFF....WEBP
+  if (
+    buffer.length >= 12 &&
+    buffer.subarray(0, 4).toString("ascii") === "RIFF" &&
+    buffer.subarray(8, 12).toString("ascii") === "WEBP"
+  ) {
+    return "image/webp";
+  }
+
+  // PDF: %PDF-
+  if (buffer.subarray(0, 5).toString("ascii") === "%PDF-") {
+    return "application/pdf";
+  }
+
+  // Ogg / Opus: OggS
+  if (buffer.subarray(0, 4).toString("ascii") === "OggS") {
+    return "audio/ogg";
+  }
+
+  // MP3: ID3 tag or frame sync FF E0+.
+  if (buffer.subarray(0, 3).toString("ascii") === "ID3") {
+    return "audio/mpeg";
+  }
+  if (buffer[0] === 0xff && (buffer[1] & 0xe0) === 0xe0) {
+    return "audio/mpeg";
+  }
+
+  // MP4: "ftyp" at offset 4.
+  if (
+    buffer.length >= 12 &&
+    buffer.subarray(4, 8).toString("ascii") === "ftyp"
+  ) {
+    return "video/mp4";
+  }
+
+  return undefined;
+}
+
+function extFromPath(filePath?: string): string | undefined {
+  if (!filePath) return undefined;
+  try {
+    if (/^https?:\/\//i.test(filePath)) {
+      const url = new URL(filePath);
+      return path.extname(url.pathname).toLowerCase() || undefined;
+    }
+  } catch {
+    // fall back to plain path parsing
+  }
+  const ext = path.extname(filePath).toLowerCase();
+  return ext || undefined;
+}
+
+export function detectMime(opts: {
+  buffer?: Buffer;
+  headerMime?: string | null;
+  filePath?: string;
+}): string | undefined {
+  const sniffed = sniffMime(opts.buffer);
+  if (sniffed) return sniffed;
+
+  const headerMime = normalizeHeaderMime(opts.headerMime);
+  if (headerMime) return headerMime;
+
+  const ext = extFromPath(opts.filePath);
+  if (ext && MIME_BY_EXT[ext]) return MIME_BY_EXT[ext];
+
+  return undefined;
+}
+
+export function extensionForMime(mime?: string | null): string | undefined {
+  if (!mime) return undefined;
+  return EXT_BY_MIME[mime.toLowerCase()];
+}
+
+export function kindFromMime(mime?: string | null): MediaKind {
+  return mediaKindFromMime(mime);
+}
@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-
+import sharp from "sharp";
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";

 const realOs = await vi.importActual<typeof import("node:os")>("node:os");
@@ -35,6 +35,16 @@ describe("media store", () => {
    const savedStat = await fs.stat(saved.path);
    expect(savedStat.size).toBe(buf.length);
    expect(saved.contentType).toBe("text/plain");
+    expect(saved.path.endsWith(".txt")).toBe(true);
+
+    const jpeg = await sharp({
+      create: { width: 2, height: 2, channels: 3, background: "#123456" },
+    })
+      .jpeg({ quality: 80 })
+      .toBuffer();
+    const savedJpeg = await store.saveMediaBuffer(jpeg, "image/jpeg");
+    expect(savedJpeg.contentType).toBe("image/jpeg");
+    expect(savedJpeg.path.endsWith(".jpg")).toBe(true);

    const huge = Buffer.alloc(5 * 1024 * 1024 + 1);
    await expect(store.saveMediaBuffer(huge)).rejects.toThrow(
@@ -50,6 +60,7 @@ describe("media store", () => {
    expect(saved.size).toBe(10);
    const savedStat = await fs.stat(saved.path);
    expect(savedStat.isFile()).toBe(true);
+    expect(path.extname(saved.path)).toBe(".txt");

    // make the file look old and ensure cleanOldMedia removes it
    const past = Date.now() - 10_000;
@@ -57,4 +68,21 @@ describe("media store", () => {
    await store.cleanOldMedia(1);
    await expect(fs.stat(saved.path)).rejects.toThrow();
  });
+
+  it("renames media based on detected mime even when extension is wrong", async () => {
+    const pngBytes = await sharp({
+      create: { width: 2, height: 2, channels: 3, background: "#00ff00" },
+    })
+      .png()
+      .toBuffer();
+    const bogusExt = path.join(HOME, "image-wrong.bin");
+    await fs.writeFile(bogusExt, pngBytes);
+
+    const saved = await store.saveMediaSource(bogusExt);
+    expect(saved.contentType).toBe("image/png");
+    expect(path.extname(saved.path)).toBe(".png");
+
+    const buf = await fs.readFile(saved.path);
+    expect(buf.equals(pngBytes)).toBe(true);
+  });
 });
@@ -6,6 +6,8 @@ import os from "node:os";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";

+import { detectMime, extensionForMime } from "./mime.js";
+
 const MEDIA_DIR = path.join(os.homedir(), ".warelay", "media");
 const MAX_BYTES = 5 * 1024 * 1024; // 5MB
 const DEFAULT_TTL_MS = 2 * 60 * 1000; // 2 minutes
@@ -39,27 +41,50 @@ function looksLikeUrl(src: string) {
  return /^https?:\/\//i.test(src);
 }

+/**
+ * Download media to disk while capturing the first few KB for mime sniffing.
+ */
 async function downloadToFile(
  url: string,
  dest: string,
  headers?: Record<string, string>,
-) {
-  await new Promise<void>((resolve, reject) => {
+): Promise<{ headerMime?: string; sniffBuffer: Buffer; size: number }> {
+  return await new Promise((resolve, reject) => {
    const req = request(url, { headers }, (res) => {
      if (!res.statusCode || res.statusCode >= 400) {
        reject(new Error(`HTTP ${res.statusCode ?? "?"} downloading media`));
        return;
      }
      let total = 0;
+      const sniffChunks: Buffer[] = [];
+      let sniffLen = 0;
      const out = createWriteStream(dest);
      res.on("data", (chunk) => {
        total += chunk.length;
+        if (sniffLen < 16384) {
+          sniffChunks.push(chunk);
+          sniffLen += chunk.length;
+        }
        if (total > MAX_BYTES) {
          req.destroy(new Error("Media exceeds 5MB limit"));
        }
      });
      pipeline(res, out)
-        .then(() => resolve())
+        .then(() => {
+          const sniffBuffer = Buffer.concat(
+            sniffChunks,
+            Math.min(sniffLen, 16384),
+          );
+          const rawHeader = res.headers["content-type"];
+          const headerMime = Array.isArray(rawHeader)
+            ? rawHeader[0]
+            : rawHeader;
+          resolve({
+            headerMime,
+            sniffBuffer,
+            size: total,
+          });
+        })
        .catch(reject);
    });
    req.on("error", reject);
@@ -83,11 +108,23 @@ export async function saveMediaSource(
  await fs.mkdir(dir, { recursive: true });
  await cleanOldMedia();
  const id = crypto.randomUUID();
-  const dest = path.join(dir, id);
  if (looksLikeUrl(source)) {
-    await downloadToFile(source, dest, headers);
-    const stat = await fs.stat(dest);
-    return { id, path: dest, size: stat.size };
+    const tempDest = path.join(dir, `${id}.tmp`);
+    const { headerMime, sniffBuffer, size } = await downloadToFile(
+      source,
+      tempDest,
+      headers,
+    );
+    const mime = detectMime({
+      buffer: sniffBuffer,
+      headerMime,
+      filePath: source,
+    });
+    const ext =
+      extensionForMime(mime) ?? path.extname(new URL(source).pathname);
+    const finalDest = path.join(dir, ext ? `${id}${ext}` : id);
+    await fs.rename(tempDest, finalDest);
+    return { id, path: finalDest, size, contentType: mime };
  }
  // local path
  const stat = await fs.stat(source);
@@ -97,8 +134,12 @@ export async function saveMediaSource(
  if (stat.size > MAX_BYTES) {
    throw new Error("Media exceeds 5MB limit");
  }
-  await fs.copyFile(source, dest);
-  return { id, path: dest, size: stat.size };
+  const buffer = await fs.readFile(source);
+  const mime = detectMime({ buffer, filePath: source });
+  const ext = extensionForMime(mime) ?? path.extname(source);
+  const dest = path.join(dir, ext ? `${id}${ext}` : id);
+  await fs.writeFile(dest, buffer);
+  return { id, path: dest, size: stat.size, contentType: mime };
 }

 export async function saveMediaBuffer(
@@ -112,7 +153,9 @@ export async function saveMediaBuffer(
  const dir = path.join(MEDIA_DIR, subdir);
  await fs.mkdir(dir, { recursive: true });
  const id = crypto.randomUUID();
-  const dest = path.join(dir, id);
+  const mime = detectMime({ buffer, headerMime: contentType });
+  const ext = extensionForMime(mime);
+  const dest = path.join(dir, ext ? `${id}${ext}` : id);
  await fs.writeFile(dest, buffer);
-  return { id, path: dest, size: buffer.byteLength, contentType };
+  return { id, path: dest, size: buffer.byteLength, contentType: mime };
 }
@@ -2,7 +2,11 @@
 // module keeps responsibilities small and testable without changing the public API.
 export {
  DEFAULT_WEB_MEDIA_BYTES,
+  HEARTBEAT_PROMPT,
+  HEARTBEAT_TOKEN,
  monitorWebProvider,
+  resolveHeartbeatRecipients,
+  runWebHeartbeatOnce,
  type WebMonitorTuning,
 } from "./web/auto-reply.js";
 export {
@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { HEARTBEAT_TOKEN } from "../web/auto-reply.js";
+import { runTwilioHeartbeatOnce } from "./heartbeat.js";
+
+vi.mock("./send.js", () => ({
+  sendMessage: vi.fn(),
+}));
+
+vi.mock("../auto-reply/reply.js", () => ({
+  getReplyFromConfig: vi.fn(),
+}));
+
+// eslint-disable-next-line import/first
+import { getReplyFromConfig } from "../auto-reply/reply.js";
+// eslint-disable-next-line import/first
+import { sendMessage } from "./send.js";
+
+const sendMessageMock = sendMessage as unknown as vi.Mock;
+const replyResolverMock = getReplyFromConfig as unknown as vi.Mock;
+
+describe("runTwilioHeartbeatOnce", () => {
+  it("sends manual override body and skips resolver", async () => {
+    sendMessageMock.mockResolvedValue({});
+    await runTwilioHeartbeatOnce({
+      to: "+1555",
+      overrideBody: "hello manual",
+    });
+    expect(sendMessage).toHaveBeenCalledWith(
+      "+1555",
+      "hello manual",
+      undefined,
+      expect.anything(),
+    );
+    expect(replyResolverMock).not.toHaveBeenCalled();
+  });
+
+  it("dry-run manual message avoids sending", async () => {
+    sendMessageMock.mockReset();
+    await runTwilioHeartbeatOnce({
+      to: "+1555",
+      overrideBody: "hello manual",
+      dryRun: true,
+    });
+    expect(sendMessage).not.toHaveBeenCalled();
+    expect(replyResolverMock).not.toHaveBeenCalled();
+  });
+
+  it("skips send when resolver returns heartbeat token", async () => {
+    replyResolverMock.mockResolvedValue({
+      text: HEARTBEAT_TOKEN,
+    });
+    sendMessageMock.mockReset();
+    await runTwilioHeartbeatOnce({
+      to: "+1555",
+    });
+    expect(sendMessage).not.toHaveBeenCalled();
+  });
+
+  it("sends resolved heartbeat text when present", async () => {
+    replyResolverMock.mockResolvedValue({
+      text: "ALERT!",
+    });
+    sendMessageMock.mockReset().mockResolvedValue({});
+    await runTwilioHeartbeatOnce({
+      to: "+1555",
+    });
+    expect(sendMessage).toHaveBeenCalledWith(
+      "+1555",
+      "ALERT!",
+      undefined,
+      expect.anything(),
+    );
+  });
+});
@@ -0,0 +1,89 @@
+import { getReplyFromConfig } from "../auto-reply/reply.js";
+import { danger, success } from "../globals.js";
+import { logInfo } from "../logger.js";
+import { defaultRuntime, type RuntimeEnv } from "../runtime.js";
+import { HEARTBEAT_PROMPT, stripHeartbeatToken } from "../web/auto-reply.js";
+import { sendMessage } from "./send.js";
+
+type ReplyResolver = typeof getReplyFromConfig;
+
+export async function runTwilioHeartbeatOnce(opts: {
+  to: string;
+  verbose?: boolean;
+  runtime?: RuntimeEnv;
+  replyResolver?: ReplyResolver;
+  overrideBody?: string;
+  dryRun?: boolean;
+}) {
+  const {
+    to,
+    verbose: _verbose = false,
+    runtime = defaultRuntime,
+    overrideBody,
+    dryRun = false,
+  } = opts;
+  const replyResolver = opts.replyResolver ?? getReplyFromConfig;
+
+  if (overrideBody && overrideBody.trim().length === 0) {
+    throw new Error("Override body must be non-empty when provided.");
+  }
+
+  try {
+    if (overrideBody) {
+      if (dryRun) {
+        logInfo(
+          `[dry-run] twilio send -> ${to}: ${overrideBody.trim()} (manual message)`,
+          runtime,
+        );
+        return;
+      }
+      await sendMessage(to, overrideBody, undefined, runtime);
+      logInfo(success(`sent manual message to ${to} (twilio)`), runtime);
+      return;
+    }
+
+    const replyResult = await replyResolver(
+      {
+        Body: HEARTBEAT_PROMPT,
+        From: to,
+        To: to,
+        MessageSid: undefined,
+      },
+      undefined,
+    );
+
+    if (
+      !replyResult ||
+      (!replyResult.text &&
+        !replyResult.mediaUrl &&
+        !replyResult.mediaUrls?.length)
+    ) {
+      logInfo("heartbeat skipped: empty reply", runtime);
+      return;
+    }
+
+    const hasMedia = Boolean(
+      replyResult.mediaUrl || (replyResult.mediaUrls?.length ?? 0) > 0,
+    );
+    const stripped = stripHeartbeatToken(replyResult.text);
+    if (stripped.shouldSkip && !hasMedia) {
+      logInfo(success("heartbeat: ok (HEARTBEAT_OK)"), runtime);
+      return;
+    }
+
+    const finalText = stripped.text || replyResult.text || "";
+    if (dryRun) {
+      logInfo(
+        `[dry-run] heartbeat -> ${to}: ${finalText.slice(0, 200)}`,
+        runtime,
+      );
+      return;
+    }
+
+    await sendMessage(to, finalText, undefined, runtime);
+    logInfo(success(`heartbeat sent to ${to} (twilio)`), runtime);
+  } catch (err) {
+    runtime.error(danger(`Heartbeat failed: ${String(err)}`));
+    throw err;
+  }
+}
@@ -5,7 +5,7 @@ import express, { type Request, type Response } from "express";
 import { getReplyFromConfig, type ReplyPayload } from "../auto-reply/reply.js";
 import { type EnvConfig, readEnv } from "../env.js";
 import { danger, success } from "../globals.js";
-import { ensureMediaHosted } from "../media/host.js";
+import * as mediaHost from "../media/host.js";
 import { attachMediaRoutes } from "../media/server.js";
 import { saveMediaSource } from "../media/store.js";
 import { defaultRuntime, type RuntimeEnv } from "../runtime.js";
@@ -92,7 +92,7 @@ export async function startWebhook(
      try {
        let mediaUrl = replyResult.mediaUrl;
        if (mediaUrl && !/^https?:\/\//i.test(mediaUrl)) {
-          const hosted = await ensureMediaHosted(mediaUrl);
+          const hosted = await mediaHost.ensureMediaHosted(mediaUrl);
          mediaUrl = hosted.url;
        }
        await client.messages.create({
@@ -4,7 +4,9 @@ import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import {
  assertProvider,
+  CONFIG_DIR,
  ensureDir,
+  jidToE164,
  normalizeE164,
  normalizePath,
  sleep,
@@ -67,3 +69,19 @@ describe("normalizeE164 & toWhatsappJid", () => {
    );
  });
 });
+
+describe("jidToE164", () => {
+  it("maps @lid using reverse mapping file", () => {
+    const mappingPath = `${CONFIG_DIR}/credentials/lid-mapping-123_reverse.json`;
+    const original = fs.readFileSync;
+    const spy = vi
+      .spyOn(fs, "readFileSync")
+      // biome-ignore lint/suspicious/noExplicitAny: forwarding to native signature
+      .mockImplementation((path: any, encoding?: any) => {
+        if (path === mappingPath) return `"5551234"`;
+        return original(path, encoding);
+      });
+    expect(jidToE164("123@lid")).toBe("+5551234");
+    spy.mockRestore();
+  });
+});
@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import os from "node:os";
+import { isVerbose, logVerbose } from "./globals.js";

 export async function ensureDir(dir: string) {
  await fs.promises.mkdir(dir, { recursive: true });
@@ -38,9 +39,31 @@ export function toWhatsappJid(number: string): string {
 export function jidToE164(jid: string): string | null {
  // Convert a WhatsApp JID (with optional device suffix, e.g. 1234:1@s.whatsapp.net) back to +1234.
  const match = jid.match(/^(\d+)(?::\d+)?@s\.whatsapp\.net$/);
-  if (!match) return null;
-  const digits = match[1];
-  return `+${digits}`;
+  if (match) {
+    const digits = match[1];
+    return `+${digits}`;
+  }
+
+  // Support @lid format (WhatsApp Linked ID) - look up reverse mapping
+  const lidMatch = jid.match(/^(\d+)(?::\d+)?@lid$/);
+  if (lidMatch) {
+    const lid = lidMatch[1];
+    try {
+      const mappingPath = `${CONFIG_DIR}/credentials/lid-mapping-${lid}_reverse.json`;
+      const data = fs.readFileSync(mappingPath, "utf8");
+      const phone = JSON.parse(data);
+      if (phone) return `+${phone}`;
+    } catch {
+      if (isVerbose()) {
+        logVerbose(
+          `LID mapping not found for ${lid}; skipping inbound message`,
+        );
+      }
+      // Mapping not found, fall through
+    }
+  }
+
+  return null;
 }

 export function sleep(ms: number) {
@@ -1,16 +1,418 @@
+import "./test-helpers.js";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import sharp from "sharp";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

+import type { WarelayConfig } from "../config/config.js";
 import { resetLogger, setLoggerOverride } from "../logging.js";
-import { monitorWebProvider } from "./auto-reply.js";
+import * as commandQueue from "../process/command-queue.js";
+import {
+  HEARTBEAT_PROMPT,
+  HEARTBEAT_TOKEN,
+  monitorWebProvider,
+  resolveHeartbeatRecipients,
+  resolveReplyHeartbeatMinutes,
+  runWebHeartbeatOnce,
+  stripHeartbeatToken,
+} from "./auto-reply.js";
+import type { sendMessageWeb } from "./outbound.js";
 import {
  resetBaileysMocks,
  resetLoadConfigMock,
  setLoadConfigMock,
 } from "./test-helpers.js";

+const makeSessionStore = async (
+  entries: Record<string, unknown> = {},
+): Promise<{ storePath: string; cleanup: () => Promise<void> }> => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "warelay-session-"));
+  const storePath = path.join(dir, "sessions.json");
+  await fs.writeFile(storePath, JSON.stringify(entries));
+  return {
+    storePath,
+    cleanup: () => fs.rm(dir, { recursive: true, force: true }),
+  };
+};
+
+describe("heartbeat helpers", () => {
+  it("strips heartbeat token and skips when only token", () => {
+    expect(stripHeartbeatToken(undefined)).toEqual({
+      shouldSkip: true,
+      text: "",
+    });
+    expect(stripHeartbeatToken("  ")).toEqual({
+      shouldSkip: true,
+      text: "",
+    });
+    expect(stripHeartbeatToken(HEARTBEAT_TOKEN)).toEqual({
+      shouldSkip: true,
+      text: "",
+    });
+  });
+
+  it("keeps content and removes token when mixed", () => {
+    expect(stripHeartbeatToken(`ALERT ${HEARTBEAT_TOKEN}`)).toEqual({
+      shouldSkip: false,
+      text: "ALERT",
+    });
+    expect(stripHeartbeatToken(`hello`)).toEqual({
+      shouldSkip: false,
+      text: "hello",
+    });
+  });
+
+  it("resolves heartbeat minutes with default and overrides", () => {
+    const cfgBase: WarelayConfig = {
+      inbound: {
+        reply: { mode: "command" as const },
+      },
+    };
+    expect(resolveReplyHeartbeatMinutes(cfgBase)).toBe(30);
+    expect(
+      resolveReplyHeartbeatMinutes({
+        inbound: { reply: { mode: "command", heartbeatMinutes: 5 } },
+      }),
+    ).toBe(5);
+    expect(
+      resolveReplyHeartbeatMinutes({
+        inbound: { reply: { mode: "command", heartbeatMinutes: 0 } },
+      }),
+    ).toBeNull();
+    expect(resolveReplyHeartbeatMinutes(cfgBase, 7)).toBe(7);
+    expect(
+      resolveReplyHeartbeatMinutes({
+        inbound: { reply: { mode: "text" } },
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("resolveHeartbeatRecipients", () => {
+  it("returns the sole session recipient", async () => {
+    const now = Date.now();
+    const store = await makeSessionStore({ "+1000": { updatedAt: now } });
+    const cfg: WarelayConfig = {
+      inbound: {
+        allowFrom: ["+1999"],
+        reply: { mode: "command", session: { store: store.storePath } },
+      },
+    };
+    const result = resolveHeartbeatRecipients(cfg);
+    expect(result.source).toBe("session-single");
+    expect(result.recipients).toEqual(["+1000"]);
+    await store.cleanup();
+  });
+
+  it("surfaces ambiguity when multiple sessions exist", async () => {
+    const now = Date.now();
+    const store = await makeSessionStore({
+      "+1000": { updatedAt: now },
+      "+2000": { updatedAt: now - 10 },
+    });
+    const cfg: WarelayConfig = {
+      inbound: {
+        allowFrom: ["+1999"],
+        reply: { mode: "command", session: { store: store.storePath } },
+      },
+    };
+    const result = resolveHeartbeatRecipients(cfg);
+    expect(result.source).toBe("session-ambiguous");
+    expect(result.recipients).toEqual(["+1000", "+2000"]);
+    await store.cleanup();
+  });
+
+  it("filters wildcard allowFrom when no sessions exist", async () => {
+    const store = await makeSessionStore({});
+    const cfg: WarelayConfig = {
+      inbound: {
+        allowFrom: ["*"],
+        reply: { mode: "command", session: { store: store.storePath } },
+      },
+    };
+    const result = resolveHeartbeatRecipients(cfg);
+    expect(result.recipients).toHaveLength(0);
+    expect(result.source).toBe("allowFrom");
+    await store.cleanup();
+  });
+
+  it("merges sessions and allowFrom when --all is set", async () => {
+    const now = Date.now();
+    const store = await makeSessionStore({ "+1000": { updatedAt: now } });
+    const cfg: WarelayConfig = {
+      inbound: {
+        allowFrom: ["+1999"],
+        reply: { mode: "command", session: { store: store.storePath } },
+      },
+    };
+    const result = resolveHeartbeatRecipients(cfg, { all: true });
+    expect(result.source).toBe("all");
+    expect(result.recipients.sort()).toEqual(["+1000", "+1999"].sort());
+    await store.cleanup();
+  });
+});
+
+describe("runWebHeartbeatOnce", () => {
+  it("skips when heartbeat token returned", async () => {
+    const store = await makeSessionStore();
+    const sender: typeof sendMessageWeb = vi.fn();
+    const resolver = vi.fn(async () => ({ text: HEARTBEAT_TOKEN }));
+    await runWebHeartbeatOnce({
+      cfg: {
+        inbound: {
+          allowFrom: ["+1555"],
+          reply: { mode: "command", session: { store: store.storePath } },
+        },
+      },
+      to: "+1555",
+      verbose: false,
+      sender,
+      replyResolver: resolver,
+    });
+    expect(resolver).toHaveBeenCalled();
+    expect(sender).not.toHaveBeenCalled();
+    await store.cleanup();
+  });
+
+  it("sends when alert text present", async () => {
+    const store = await makeSessionStore();
+    const sender: typeof sendMessageWeb = vi
+      .fn()
+      .mockResolvedValue({ messageId: "m1", toJid: "jid" });
+    const resolver = vi.fn(async () => ({ text: "ALERT" }));
+    await runWebHeartbeatOnce({
+      cfg: {
+        inbound: {
+          allowFrom: ["+1555"],
+          reply: { mode: "command", session: { store: store.storePath } },
+        },
+      },
+      to: "+1555",
+      verbose: false,
+      sender,
+      replyResolver: resolver,
+    });
+    expect(sender).toHaveBeenCalledWith("+1555", "ALERT", { verbose: false });
+    await store.cleanup();
+  });
+
+  it("falls back to most recent session when no to is provided", async () => {
+    const store = await makeSessionStore();
+    const storePath = store.storePath;
+    const sender: typeof sendMessageWeb = vi
+      .fn()
+      .mockResolvedValue({ messageId: "m1", toJid: "jid" });
+    const resolver = vi.fn(async () => ({ text: "ALERT" }));
+    const now = Date.now();
+    const sessionEntries = {
+      "+1222": { sessionId: "s1", updatedAt: now - 1000 },
+      "+1333": { sessionId: "s2", updatedAt: now },
+    };
+    await fs.writeFile(storePath, JSON.stringify(sessionEntries));
+    await runWebHeartbeatOnce({
+      cfg: {
+        inbound: {
+          allowFrom: ["+1999"],
+          reply: { mode: "command", session: { store: storePath } },
+        },
+      },
+      to: "+1999",
+      verbose: false,
+      sender,
+      replyResolver: resolver,
+    });
+    expect(sender).toHaveBeenCalledWith("+1999", "ALERT", { verbose: false });
+    await store.cleanup();
+  });
+
+  it("does not refresh updatedAt when heartbeat is skipped", async () => {
+    const tmpDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "warelay-heartbeat-"),
+    );
+    const storePath = path.join(tmpDir, "sessions.json");
+    const now = Date.now();
+    const originalUpdated = now - 30 * 60 * 1000;
+    const store = {
+      "+1555": { sessionId: "sess1", updatedAt: originalUpdated },
+    };
+    await fs.writeFile(storePath, JSON.stringify(store));
+
+    const sender: typeof sendMessageWeb = vi.fn();
+    const resolver = vi.fn(async () => ({ text: HEARTBEAT_TOKEN }));
+    setLoadConfigMock({
+      inbound: {
+        allowFrom: ["+1555"],
+        reply: {
+          mode: "command",
+          session: {
+            store: storePath,
+            idleMinutes: 60,
+            heartbeatIdleMinutes: 10,
+          },
+        },
+      },
+    });
+
+    await runWebHeartbeatOnce({
+      to: "+1555",
+      verbose: false,
+      sender,
+      replyResolver: resolver,
+    });
+
+    const after = JSON.parse(await fs.readFile(storePath, "utf-8"));
+    expect(after["+1555"].updatedAt).toBe(originalUpdated);
+    expect(sender).not.toHaveBeenCalled();
+  });
+
+  it("heartbeat reuses existing session id when last inbound is present", async () => {
+    const tmpDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "warelay-heartbeat-session-"),
+    );
+    const storePath = path.join(tmpDir, "sessions.json");
+    const sessionId = "sess-keep";
+    await fs.writeFile(
+      storePath,
+      JSON.stringify({
+        "+4367": { sessionId, updatedAt: Date.now(), systemSent: false },
+      }),
+    );
+
+    setLoadConfigMock(() => ({
+      inbound: {
+        allowFrom: ["+4367"],
+        reply: {
+          mode: "command",
+          heartbeatMinutes: 0.001,
+          session: { store: storePath, idleMinutes: 60 },
+        },
+      },
+    }));
+
+    const replyResolver = vi.fn().mockResolvedValue({ text: HEARTBEAT_TOKEN });
+    const runtime = { log: vi.fn(), error: vi.fn(), exit: vi.fn() } as never;
+    const cfg: WarelayConfig = {
+      inbound: {
+        allowFrom: ["+4367"],
+        reply: {
+          mode: "command",
+          session: { store: storePath, idleMinutes: 60 },
+        },
+      },
+    };
+
+    await runWebHeartbeatOnce({
+      cfg,
+      to: "+4367",
+      verbose: false,
+      replyResolver,
+      runtime,
+    });
+
+    const heartbeatCall = replyResolver.mock.calls.find(
+      (call) => call[0]?.Body === HEARTBEAT_PROMPT,
+    );
+    expect(heartbeatCall?.[0]?.MessageSid).toBe(sessionId);
+  });
+
+  it("heartbeat honors session-id override and seeds store", async () => {
+    const tmpDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "warelay-heartbeat-override-"),
+    );
+    const storePath = path.join(tmpDir, "sessions.json");
+    await fs.writeFile(storePath, JSON.stringify({}));
+
+    const sessionId = "override-123";
+    setLoadConfigMock(() => ({
+      inbound: {
+        allowFrom: ["+1999"],
+        reply: {
+          mode: "command",
+          session: { store: storePath, idleMinutes: 60 },
+        },
+      },
+    }));
+
+    const resolver = vi.fn(async () => ({ text: HEARTBEAT_TOKEN }));
+    const cfg: WarelayConfig = {
+      inbound: {
+        allowFrom: ["+1999"],
+        reply: {
+          mode: "command",
+          session: { store: storePath, idleMinutes: 60 },
+        },
+      },
+    };
+    await runWebHeartbeatOnce({
+      cfg,
+      to: "+1999",
+      verbose: false,
+      replyResolver: resolver,
+      sessionId,
+    });
+
+    const heartbeatCall = resolver.mock.calls.find(
+      (call) => call[0]?.Body === HEARTBEAT_PROMPT,
+    );
+    expect(heartbeatCall?.[0]?.MessageSid).toBe(sessionId);
+    const raw = await fs.readFile(storePath, "utf-8");
+    const stored = raw ? JSON.parse(raw) : {};
+    expect(stored["+1999"]?.sessionId).toBe(sessionId);
+    expect(stored["+1999"]?.updatedAt).toBeDefined();
+  });
+
+  it("sends overrideBody directly and skips resolver", async () => {
+    const store = await makeSessionStore();
+    const sender: typeof sendMessageWeb = vi
+      .fn()
+      .mockResolvedValue({ messageId: "m1", toJid: "jid" });
+    const resolver = vi.fn();
+    await runWebHeartbeatOnce({
+      cfg: {
+        inbound: {
+          allowFrom: ["+1555"],
+          reply: { mode: "command", session: { store: store.storePath } },
+        },
+      },
+      to: "+1555",
+      verbose: false,
+      sender,
+      replyResolver: resolver,
+      overrideBody: "manual ping",
+    });
+    expect(sender).toHaveBeenCalledWith("+1555", "manual ping", {
+      verbose: false,
+    });
+    expect(resolver).not.toHaveBeenCalled();
+    await store.cleanup();
+  });
+
+  it("dry-run overrideBody prints and skips send", async () => {
+    const store = await makeSessionStore();
+    const sender: typeof sendMessageWeb = vi.fn();
+    const resolver = vi.fn();
+    await runWebHeartbeatOnce({
+      cfg: {
+        inbound: {
+          allowFrom: ["+1555"],
+          reply: { mode: "command", session: { store: store.storePath } },
+        },
+      },
+      to: "+1555",
+      verbose: false,
+      sender,
+      replyResolver: resolver,
+      overrideBody: "dry",
+      dryRun: true,
+    });
+    expect(sender).not.toHaveBeenCalled();
+    expect(resolver).not.toHaveBeenCalled();
+    await store.cleanup();
+  });
+});
+
 describe("web auto-reply", () => {
  beforeEach(() => {
    vi.clearAllMocks();
@@ -123,6 +525,123 @@ describe("web auto-reply", () => {
    );
  });

+  it("skips reply heartbeat when requests are running", async () => {
+    const tmpDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "warelay-heartbeat-queue-"),
+    );
+    const storePath = path.join(tmpDir, "sessions.json");
+    await fs.writeFile(storePath, JSON.stringify({}));
+
+    const queueSpy = vi.spyOn(commandQueue, "getQueueSize").mockReturnValue(2);
+    const replyResolver = vi.fn();
+    const listenerFactory = vi.fn(async () => {
+      const onClose = new Promise<void>(() => {
+        // stay open until aborted
+      });
+      return { close: vi.fn(), onClose };
+    });
+    const runtime = { log: vi.fn(), error: vi.fn(), exit: vi.fn() } as never;
+
+    setLoadConfigMock(() => ({
+      inbound: {
+        allowFrom: ["+1555"],
+        reply: { mode: "command", session: { store: storePath } },
+      },
+    }));
+
+    const controller = new AbortController();
+    const run = monitorWebProvider(
+      false,
+      listenerFactory,
+      true,
+      replyResolver,
+      runtime,
+      controller.signal,
+      { replyHeartbeatMinutes: 1, replyHeartbeatNow: true },
+    );
+
+    try {
+      await Promise.resolve();
+      controller.abort();
+      await run;
+      expect(replyResolver).not.toHaveBeenCalled();
+    } finally {
+      queueSpy.mockRestore();
+    }
+  });
+
+  it("batches inbound messages while queue is busy and preserves timestamps", async () => {
+    vi.useFakeTimers();
+    const originalMax = process.getMaxListeners();
+    process.setMaxListeners?.(1); // force low to confirm bump
+
+    const sendMedia = vi.fn();
+    const reply = vi.fn().mockResolvedValue(undefined);
+    const sendComposing = vi.fn();
+    const resolver = vi.fn().mockResolvedValue({ text: "batched" });
+
+    let capturedOnMessage:
+      | ((msg: import("./inbound.js").WebInboundMessage) => Promise<void>)
+      | undefined;
+    const listenerFactory = async (opts: {
+      onMessage: (
+        msg: import("./inbound.js").WebInboundMessage,
+      ) => Promise<void>;
+    }) => {
+      capturedOnMessage = opts.onMessage;
+      return { close: vi.fn() };
+    };
+
+    // Queue starts busy, then frees after one polling tick.
+    let queueBusy = true;
+    const queueSpy = vi
+      .spyOn(commandQueue, "getQueueSize")
+      .mockImplementation(() => (queueBusy ? 1 : 0));
+
+    setLoadConfigMock(() => ({ inbound: { timestampPrefix: "UTC" } }));
+
+    await monitorWebProvider(false, listenerFactory, false, resolver);
+    expect(capturedOnMessage).toBeDefined();
+
+    // Two messages from the same sender with fixed timestamps
+    await capturedOnMessage?.({
+      body: "first",
+      from: "+1",
+      to: "+2",
+      id: "m1",
+      timestamp: 1735689600000, // Jan 1 2025 00:00:00 UTC
+      sendComposing,
+      reply,
+      sendMedia,
+    });
+    await capturedOnMessage?.({
+      body: "second",
+      from: "+1",
+      to: "+2",
+      id: "m2",
+      timestamp: 1735693200000, // Jan 1 2025 01:00:00 UTC
+      sendComposing,
+      reply,
+      sendMedia,
+    });
+
+    // Let the queued batch flush once the queue is free
+    queueBusy = false;
+    vi.advanceTimersByTime(200);
+
+    expect(resolver).toHaveBeenCalledTimes(1);
+    const args = resolver.mock.calls[0][0];
+    expect(args.Body).toContain("[Jan 1 00:00] [warelay] first");
+    expect(args.Body).toContain("[Jan 1 01:00] [warelay] second");
+
+    // Max listeners bumped to avoid warnings in multi-instance test runs
+    expect(process.getMaxListeners?.()).toBeGreaterThanOrEqual(50);
+
+    queueSpy.mockRestore();
+    process.setMaxListeners?.(originalMax);
+    vi.useRealTimers();
+  });
+
  it("falls back to text when media send fails", async () => {
    const sendMedia = vi.fn().mockRejectedValue(new Error("boom"));
    const reply = vi.fn().mockResolvedValue(undefined);
@@ -564,4 +1083,213 @@ describe("web auto-reply", () => {
    expect(content).toContain('"module":"web-auto-reply"');
    expect(content).toContain('"text":"auto"');
  });
+
+  it("prefixes body with same-phone marker when from === to", async () => {
+    // Enable messagePrefix for same-phone mode testing
+    setLoadConfigMock(() => ({
+      inbound: {
+        allowFrom: ["*"],
+        messagePrefix: "[same-phone]",
+        responsePrefix: undefined,
+        timestampPrefix: false,
+      },
+    }));
+
+    let capturedOnMessage:
+      | ((msg: import("./inbound.js").WebInboundMessage) => Promise<void>)
+      | undefined;
+    const listenerFactory = async (opts: {
+      onMessage: (
+        msg: import("./inbound.js").WebInboundMessage,
+      ) => Promise<void>;
+    }) => {
+      capturedOnMessage = opts.onMessage;
+      return { close: vi.fn() };
+    };
+
+    const resolver = vi.fn().mockResolvedValue({ text: "reply" });
+
+    await monitorWebProvider(false, listenerFactory, false, resolver);
+    expect(capturedOnMessage).toBeDefined();
+
+    await capturedOnMessage?.({
+      body: "hello",
+      from: "+1555",
+      to: "+1555", // Same phone!
+      id: "msg1",
+      sendComposing: vi.fn(),
+      reply: vi.fn(),
+      sendMedia: vi.fn(),
+    });
+
+    // The resolver should receive a prefixed body with the configured marker
+    const callArg = resolver.mock.calls[0]?.[0] as { Body?: string };
+    expect(callArg?.Body).toBeDefined();
+    expect(callArg?.Body).toBe("[same-phone] hello");
+    resetLoadConfigMock();
+  });
+
+  it("does not prefix body when from !== to", async () => {
+    let capturedOnMessage:
+      | ((msg: import("./inbound.js").WebInboundMessage) => Promise<void>)
+      | undefined;
+    const listenerFactory = async (opts: {
+      onMessage: (
+        msg: import("./inbound.js").WebInboundMessage,
+      ) => Promise<void>;
+    }) => {
+      capturedOnMessage = opts.onMessage;
+      return { close: vi.fn() };
+    };
+
+    const resolver = vi.fn().mockResolvedValue({ text: "reply" });
+
+    await monitorWebProvider(false, listenerFactory, false, resolver);
+    expect(capturedOnMessage).toBeDefined();
+
+    await capturedOnMessage?.({
+      body: "hello",
+      from: "+1555",
+      to: "+2666", // Different phones
+      id: "msg1",
+      sendComposing: vi.fn(),
+      reply: vi.fn(),
+      sendMedia: vi.fn(),
+    });
+
+    // Body should NOT be prefixed
+    const callArg = resolver.mock.calls[0]?.[0] as { Body?: string };
+    expect(callArg?.Body).toBe("hello");
+  });
+
+  it("applies responsePrefix to regular replies", async () => {
+    setLoadConfigMock(() => ({
+      inbound: {
+        allowFrom: ["*"],
+        messagePrefix: undefined,
+        responsePrefix: "🦞",
+        timestampPrefix: false,
+      },
+    }));
+
+    let capturedOnMessage:
+      | ((msg: import("./inbound.js").WebInboundMessage) => Promise<void>)
+      | undefined;
+    const reply = vi.fn();
+    const listenerFactory = async (opts: {
+      onMessage: (
+        msg: import("./inbound.js").WebInboundMessage,
+      ) => Promise<void>;
+    }) => {
+      capturedOnMessage = opts.onMessage;
+      return { close: vi.fn() };
+    };
+
+    const resolver = vi.fn().mockResolvedValue({ text: "hello there" });
+
+    await monitorWebProvider(false, listenerFactory, false, resolver);
+    expect(capturedOnMessage).toBeDefined();
+
+    await capturedOnMessage?.({
+      body: "hi",
+      from: "+1555",
+      to: "+2666",
+      id: "msg1",
+      sendComposing: vi.fn(),
+      reply,
+      sendMedia: vi.fn(),
+    });
+
+    // Reply should have responsePrefix prepended
+    expect(reply).toHaveBeenCalledWith("🦞 hello there");
+    resetLoadConfigMock();
+  });
+
+  it("skips responsePrefix for HEARTBEAT_OK responses", async () => {
+    setLoadConfigMock(() => ({
+      inbound: {
+        allowFrom: ["*"],
+        messagePrefix: undefined,
+        responsePrefix: "🦞",
+        timestampPrefix: false,
+      },
+    }));
+
+    let capturedOnMessage:
+      | ((msg: import("./inbound.js").WebInboundMessage) => Promise<void>)
+      | undefined;
+    const reply = vi.fn();
+    const listenerFactory = async (opts: {
+      onMessage: (
+        msg: import("./inbound.js").WebInboundMessage,
+      ) => Promise<void>;
+    }) => {
+      capturedOnMessage = opts.onMessage;
+      return { close: vi.fn() };
+    };
+
+    // Resolver returns exact HEARTBEAT_OK
+    const resolver = vi.fn().mockResolvedValue({ text: HEARTBEAT_TOKEN });
+
+    await monitorWebProvider(false, listenerFactory, false, resolver);
+    expect(capturedOnMessage).toBeDefined();
+
+    await capturedOnMessage?.({
+      body: "test",
+      from: "+1555",
+      to: "+2666",
+      id: "msg1",
+      sendComposing: vi.fn(),
+      reply,
+      sendMedia: vi.fn(),
+    });
+
+    // HEARTBEAT_OK should NOT have prefix - warelay needs exact match
+    expect(reply).toHaveBeenCalledWith(HEARTBEAT_TOKEN);
+    resetLoadConfigMock();
+  });
+
+  it("does not double-prefix if responsePrefix already present", async () => {
+    setLoadConfigMock(() => ({
+      inbound: {
+        allowFrom: ["*"],
+        messagePrefix: undefined,
+        responsePrefix: "🦞",
+        timestampPrefix: false,
+      },
+    }));
+
+    let capturedOnMessage:
+      | ((msg: import("./inbound.js").WebInboundMessage) => Promise<void>)
+      | undefined;
+    const reply = vi.fn();
+    const listenerFactory = async (opts: {
+      onMessage: (
+        msg: import("./inbound.js").WebInboundMessage,
+      ) => Promise<void>;
+    }) => {
+      capturedOnMessage = opts.onMessage;
+      return { close: vi.fn() };
+    };
+
+    // Resolver returns text that already has prefix
+    const resolver = vi.fn().mockResolvedValue({ text: "🦞 already prefixed" });
+
+    await monitorWebProvider(false, listenerFactory, false, resolver);
+    expect(capturedOnMessage).toBeDefined();
+
+    await capturedOnMessage?.({
+      body: "test",
+      from: "+1555",
+      to: "+2666",
+      id: "msg1",
+      sendComposing: vi.fn(),
+      reply,
+      sendMedia: vi.fn(),
+    });
+
+    // Should not double-prefix
+    expect(reply).toHaveBeenCalledWith("🦞 already prefixed");
+    resetLoadConfigMock();
+  });
 });
@@ -0,0 +1,115 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+
+vi.mock("../config/config.js", () => ({
+  loadConfig: vi.fn().mockReturnValue({
+    inbound: {
+      allowFrom: ["*"], // Allow all in tests
+      messagePrefix: undefined,
+      responsePrefix: undefined,
+      timestampPrefix: false,
+    },
+  }),
+}));
+
+const HOME = path.join(
+  os.tmpdir(),
+  `warelay-inbound-media-${crypto.randomUUID()}`,
+);
+process.env.HOME = HOME;
+
+vi.mock("@whiskeysockets/baileys", async () => {
+  const actual = await vi.importActual<
+    typeof import("@whiskeysockets/baileys")
+  >("@whiskeysockets/baileys");
+  const jpegBuffer = Buffer.from([
+    0xff, 0xd8, 0xff, 0xdb, 0x00, 0x43, 0x00, 0x03, 0x02, 0x02, 0x02, 0x02,
+    0x02, 0x03, 0x02, 0x02, 0x02, 0x03, 0x03, 0x03, 0x03, 0x04, 0x06, 0x04,
+    0x04, 0x04, 0x04, 0x04, 0x08, 0x06, 0x06, 0x05, 0x06, 0x09, 0x08, 0x0a,
+    0x0a, 0x09, 0x08, 0x09, 0x09, 0x0a, 0x0c, 0x0f, 0x0c, 0x0a, 0x0b, 0x0e,
+    0x0b, 0x09, 0x09, 0x0d, 0x11, 0x0d, 0x0e, 0x0f, 0x10, 0x10, 0x11, 0x10,
+    0x0a, 0x0c, 0x12, 0x13, 0x12, 0x10, 0x13, 0x0f, 0x10, 0x10, 0x10, 0xff,
+    0xc0, 0x00, 0x11, 0x08, 0x00, 0x01, 0x00, 0x01, 0x03, 0x01, 0x11, 0x00,
+    0x02, 0x11, 0x01, 0x03, 0x11, 0x01, 0xff, 0xc4, 0x00, 0x14, 0x00, 0x01,
+    0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0xff, 0xc4, 0x00, 0x14, 0x10, 0x01, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xda,
+    0x00, 0x0c, 0x03, 0x01, 0x00, 0x02, 0x11, 0x03, 0x11, 0x00, 0x3f, 0x00,
+    0xff, 0xd9,
+  ]);
+  return {
+    ...actual,
+    downloadMediaMessage: vi.fn().mockResolvedValue(jpegBuffer),
+  };
+});
+
+vi.mock("./session.js", () => {
+  const { EventEmitter } = require("node:events");
+  const ev = new EventEmitter();
+  const sock = {
+    ev,
+    ws: { close: vi.fn() },
+    sendPresenceUpdate: vi.fn().mockResolvedValue(undefined),
+    sendMessage: vi.fn().mockResolvedValue(undefined),
+    readMessages: vi.fn().mockResolvedValue(undefined),
+    updateMediaMessage: vi.fn(),
+    logger: {},
+    user: { id: "me@s.whatsapp.net" },
+  };
+  return {
+    createWaSocket: vi.fn().mockResolvedValue(sock),
+    waitForWaConnection: vi.fn().mockResolvedValue(undefined),
+    getStatusCode: vi.fn(() => 200),
+  };
+});
+
+import { monitorWebInbox } from "./inbound.js";
+
+describe("web inbound media saves with extension", () => {
+  beforeAll(async () => {
+    await fs.rm(HOME, { recursive: true, force: true });
+  });
+
+  afterAll(async () => {
+    await fs.rm(HOME, { recursive: true, force: true });
+  });
+
+  it("stores inbound image with jpeg extension", async () => {
+    const onMessage = vi.fn();
+    const listener = await monitorWebInbox({ verbose: false, onMessage });
+    const { createWaSocket } = await import("./session.js");
+    const realSock = await (
+      createWaSocket as unknown as () => Promise<{
+        ev: import("node:events").EventEmitter;
+      }>
+    )();
+
+    const upsert = {
+      type: "notify",
+      messages: [
+        {
+          key: { id: "img1", fromMe: false, remoteJid: "111@s.whatsapp.net" },
+          message: { imageMessage: { mimetype: "image/jpeg" } },
+          messageTimestamp: 1_700_000_001,
+        },
+      ],
+    };
+
+    realSock.ev.emit("messages.upsert", upsert);
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    expect(onMessage).toHaveBeenCalledTimes(1);
+    const msg = onMessage.mock.calls[0][0];
+    const mediaPath = msg.mediaPath;
+    expect(mediaPath).toBeDefined();
+    expect(path.extname(mediaPath as string)).toBe(".jpg");
+    const stat = await fs.stat(mediaPath as string);
+    expect(stat.size).toBeGreaterThan(0);
+
+    await listener.close();
+  });
+});
@@ -8,10 +8,11 @@ import {
  downloadMediaMessage,
 } from "@whiskeysockets/baileys";

+import { loadConfig } from "../config/config.js";
 import { isVerbose, logVerbose } from "../globals.js";
 import { getChildLogger } from "../logging.js";
 import { saveMediaBuffer } from "../media/store.js";
-import { jidToE164 } from "../utils.js";
+import { jidToE164, normalizeE164 } from "../utils.js";
 import {
  createWaSocket,
  getStatusCode,
@@ -70,7 +71,7 @@ export async function monitorWebInbox(options: {
      // De-dupe on message id; Baileys can emit retries.
      if (id && seen.has(id)) continue;
      if (id) seen.add(id);
-      if (msg.key?.fromMe) continue;
+      // Note: not filtering fromMe here - echo detection happens in auto-reply layer
      const remoteJid = msg.key?.remoteJid;
      if (!remoteJid) continue;
      // Ignore status/broadcast traffic; we only care about direct chats.
@@ -94,6 +95,25 @@ export async function monitorWebInbox(options: {
      }
      const from = jidToE164(remoteJid);
      if (!from) continue;
+
+      // Filter unauthorized senders early to prevent wasted processing
+      // and potential session corruption from Bad MAC errors
+      const cfg = loadConfig();
+      const allowFrom = cfg.inbound?.allowFrom;
+      const isSamePhone = from === selfE164;
+
+      if (!isSamePhone && Array.isArray(allowFrom) && allowFrom.length > 0) {
+        if (
+          !allowFrom.includes("*") &&
+          !allowFrom.map(normalizeE164).includes(from)
+        ) {
+          logVerbose(
+            `Blocked unauthorized sender ${from} (not in allowFrom list)`,
+          );
+          continue; // Skip processing entirely
+        }
+      }
+
      let body = extractText(msg.message ?? undefined);
      if (!body) {
        body = extractMediaPlaceholder(msg.message ?? undefined);
@@ -165,12 +185,24 @@ export async function monitorWebInbox(options: {
  sock.ev.on(
    "connection.update",
    (update: Partial<import("@whiskeysockets/baileys").ConnectionState>) => {
-      if (update.connection === "close") {
-        const status = getStatusCode(update.lastDisconnect?.error);
+      try {
+        if (update.connection === "close") {
+          const status = getStatusCode(update.lastDisconnect?.error);
+          onCloseResolve?.({
+            status,
+            isLoggedOut: status === DisconnectReason.loggedOut,
+            error: update.lastDisconnect?.error,
+          });
+        }
+      } catch (err) {
+        inboundLogger.error(
+          { error: String(err) },
+          "connection.update handler error",
+        );
        onCloseResolve?.({
-          status,
-          isLoggedOut: status === DisconnectReason.loggedOut,
-          error: update.lastDisconnect?.error,
+          status: undefined,
+          isLoggedOut: false,
+          error: err,
        });
      }
    },
@@ -185,6 +217,59 @@ export async function monitorWebInbox(options: {
      }
    },
    onClose,
+    /**
+     * Send a message through this connection's socket.
+     * Used by IPC to avoid creating new connections.
+     */
+    sendMessage: async (
+      to: string,
+      text: string,
+      mediaBuffer?: Buffer,
+      mediaType?: string,
+    ): Promise<{ messageId: string }> => {
+      const jid = `${to.replace(/^\+/, "")}@s.whatsapp.net`;
+      let payload: AnyMessageContent;
+      if (mediaBuffer && mediaType) {
+        if (mediaType.startsWith("image/")) {
+          payload = {
+            image: mediaBuffer,
+            caption: text || undefined,
+            mimetype: mediaType,
+          };
+        } else if (mediaType.startsWith("audio/")) {
+          payload = {
+            audio: mediaBuffer,
+            ptt: true,
+            mimetype: mediaType,
+          };
+        } else if (mediaType.startsWith("video/")) {
+          payload = {
+            video: mediaBuffer,
+            caption: text || undefined,
+            mimetype: mediaType,
+          };
+        } else {
+          payload = {
+            document: mediaBuffer,
+            fileName: "file",
+            caption: text || undefined,
+            mimetype: mediaType,
+          };
+        }
+      } else {
+        payload = { text };
+      }
+      const result = await sock.sendMessage(jid, payload);
+      return { messageId: result?.key?.id ?? "unknown" };
+    },
+    /**
+     * Send typing indicator ("composing") to a chat.
+     * Used after IPC send to show more messages are coming.
+     */
+    sendComposingTo: async (to: string): Promise<void> => {
+      const jid = `${to.replace(/^\+/, "")}@s.whatsapp.net`;
+      await sock.sendPresenceUpdate("composing", jid);
+    },
  } as const;
 }

@@ -0,0 +1,225 @@
+/**
+ * IPC server for warelay relay.
+ *
+ * When the relay is running, it starts a Unix socket server that allows
+ * `warelay send` and `warelay heartbeat` to send messages through the
+ * existing WhatsApp connection instead of creating new ones.
+ *
+ * This prevents Signal session ratchet corruption from multiple connections.
+ */
+
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+import { getChildLogger } from "../logging.js";
+
+const SOCKET_PATH = path.join(os.homedir(), ".warelay", "relay.sock");
+
+export interface IpcSendRequest {
+  type: "send";
+  to: string;
+  message: string;
+  mediaUrl?: string;
+}
+
+export interface IpcSendResponse {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+}
+
+type SendHandler = (
+  to: string,
+  message: string,
+  mediaUrl?: string,
+) => Promise<{ messageId: string }>;
+
+let server: net.Server | null = null;
+
+/**
+ * Start the IPC server. Called by the relay when it starts.
+ */
+export function startIpcServer(sendHandler: SendHandler): void {
+  const logger = getChildLogger({ module: "ipc-server" });
+
+  // Clean up stale socket file
+  try {
+    fs.unlinkSync(SOCKET_PATH);
+  } catch {
+    // Ignore if doesn't exist
+  }
+
+  server = net.createServer((conn) => {
+    let buffer = "";
+
+    conn.on("data", async (data) => {
+      buffer += data.toString();
+
+      // Try to parse complete JSON messages (newline-delimited)
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? ""; // Keep incomplete line in buffer
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+
+        try {
+          const request = JSON.parse(line) as IpcSendRequest;
+
+          if (request.type === "send") {
+            try {
+              const result = await sendHandler(
+                request.to,
+                request.message,
+                request.mediaUrl,
+              );
+              const response: IpcSendResponse = {
+                success: true,
+                messageId: result.messageId,
+              };
+              conn.write(`${JSON.stringify(response)}\n`);
+            } catch (err) {
+              const response: IpcSendResponse = {
+                success: false,
+                error: String(err),
+              };
+              conn.write(`${JSON.stringify(response)}\n`);
+            }
+          }
+        } catch (err) {
+          logger.warn({ error: String(err) }, "failed to parse IPC request");
+          const response: IpcSendResponse = {
+            success: false,
+            error: "Invalid request format",
+          };
+          conn.write(`${JSON.stringify(response)}\n`);
+        }
+      }
+    });
+
+    conn.on("error", (err) => {
+      logger.debug({ error: String(err) }, "IPC connection error");
+    });
+  });
+
+  server.listen(SOCKET_PATH, () => {
+    logger.info({ socketPath: SOCKET_PATH }, "IPC server started");
+    // Make socket accessible
+    fs.chmodSync(SOCKET_PATH, 0o600);
+  });
+
+  server.on("error", (err) => {
+    logger.error({ error: String(err) }, "IPC server error");
+  });
+}
+
+/**
+ * Stop the IPC server. Called when relay shuts down.
+ */
+export function stopIpcServer(): void {
+  if (server) {
+    server.close();
+    server = null;
+  }
+  try {
+    fs.unlinkSync(SOCKET_PATH);
+  } catch {
+    // Ignore
+  }
+}
+
+/**
+ * Check if the relay IPC server is running.
+ */
+export function isRelayRunning(): boolean {
+  try {
+    fs.accessSync(SOCKET_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Send a message through the running relay's IPC.
+ * Returns null if relay is not running.
+ */
+export async function sendViaIpc(
+  to: string,
+  message: string,
+  mediaUrl?: string,
+): Promise<IpcSendResponse | null> {
+  if (!isRelayRunning()) {
+    return null;
+  }
+
+  return new Promise((resolve) => {
+    const client = net.createConnection(SOCKET_PATH);
+    let buffer = "";
+    let resolved = false;
+
+    const timeout = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        client.destroy();
+        resolve({ success: false, error: "IPC timeout" });
+      }
+    }, 30000); // 30 second timeout
+
+    client.on("connect", () => {
+      const request: IpcSendRequest = {
+        type: "send",
+        to,
+        message,
+        mediaUrl,
+      };
+      client.write(`${JSON.stringify(request)}\n`);
+    });
+
+    client.on("data", (data) => {
+      buffer += data.toString();
+      const lines = buffer.split("\n");
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          const response = JSON.parse(line) as IpcSendResponse;
+          if (!resolved) {
+            resolved = true;
+            clearTimeout(timeout);
+            client.end();
+            resolve(response);
+          }
+          return;
+        } catch {
+          // Keep reading
+        }
+      }
+    });
+
+    client.on("error", (_err) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        // Socket exists but can't connect - relay might have crashed
+        resolve(null);
+      }
+    });
+
+    client.on("close", () => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        resolve({ success: false, error: "Connection closed" });
+      }
+    });
+  });
+}
+
+/**
+ * Get the IPC socket path for debugging/status.
+ */
+export function getSocketPath(): string {
+  return SOCKET_PATH;
+}
@@ -38,4 +38,20 @@ describe("web media loading", () => {
    expect(result.buffer.length).toBeLessThanOrEqual(cap);
    expect(result.buffer.length).toBeLessThan(buffer.length);
  });
+
+  it("sniffs mime before extension when loading local files", async () => {
+    const pngBuffer = await sharp({
+      create: { width: 2, height: 2, channels: 3, background: "#00ff00" },
+    })
+      .png()
+      .toBuffer();
+    const wrongExt = path.join(os.tmpdir(), `warelay-media-${Date.now()}.bin`);
+    tmpFiles.push(wrongExt);
+    await fs.writeFile(wrongExt, pngBuffer);
+
+    const result = await loadWebMedia(wrongExt, 1024 * 1024);
+
+    expect(result.kind).toBe("image");
+    expect(result.contentType).toBe("image/jpeg");
+  });
 });
@@ -1,5 +1,4 @@
 import fs from "node:fs/promises";
-import path from "node:path";
 import sharp from "sharp";

 import { isVerbose, logVerbose } from "../globals.js";
@@ -8,6 +7,7 @@ import {
  maxBytesForKind,
  mediaKindFromMime,
 } from "../media/constants.js";
+import { detectMime } from "../media/mime.js";

 export async function loadWebMedia(
  mediaUrl: string,
@@ -45,7 +45,11 @@ export async function loadWebMedia(
      throw new Error(`Failed to fetch media: HTTP ${res.status}`);
    }
    const array = Buffer.from(await res.arrayBuffer());
-    const contentType = res.headers.get("content-type");
+    const contentType = detectMime({
+      buffer: array,
+      headerMime: res.headers.get("content-type"),
+      filePath: mediaUrl,
+    });
    const kind = mediaKindFromMime(contentType);
    const cap = Math.min(
      maxBytes ?? maxBytesForKind(kind),
@@ -66,24 +70,7 @@ export async function loadWebMedia(

  // Local path
  const data = await fs.readFile(mediaUrl);
-  const ext = path.extname(mediaUrl);
-  const mime =
-    (ext &&
-      (
-        {
-          ".jpg": "image/jpeg",
-          ".jpeg": "image/jpeg",
-          ".png": "image/png",
-          ".webp": "image/webp",
-          ".gif": "image/gif",
-          ".ogg": "audio/ogg",
-          ".opus": "audio/ogg",
-          ".mp3": "audio/mpeg",
-          ".mp4": "video/mp4",
-          ".pdf": "application/pdf",
-        } as Record<string, string | undefined>
-      )[ext.toLowerCase()]) ??
-    undefined;
+  const mime = detectMime({ buffer: data, filePath: mediaUrl });
  const kind = mediaKindFromMime(mime);
  const cap = Math.min(
    maxBytes ?? maxBytesForKind(kind),
@@ -9,6 +9,19 @@ vi.mock("../media/store.js", () => ({
  }),
 }));

+const mockLoadConfig = vi.fn().mockReturnValue({
+  inbound: {
+    allowFrom: ["*"], // Allow all in tests
+    messagePrefix: undefined,
+    responsePrefix: undefined,
+    timestampPrefix: false,
+  },
+});
+
+vi.mock("../config/config.js", () => ({
+  loadConfig: () => mockLoadConfig(),
+}));
+
 vi.mock("./session.js", () => {
  const { EventEmitter } = require("node:events");
  const ev = new EventEmitter();
@@ -216,4 +229,150 @@ describe("web monitor inbox", () => {
    ]);
    await listener.close();
  });
+
+  it("blocks messages from unauthorized senders not in allowFrom", async () => {
+    // Test for auto-recovery fix: early allowFrom filtering prevents Bad MAC errors
+    // from unauthorized senders corrupting sessions
+    mockLoadConfig.mockReturnValue({
+      inbound: {
+        allowFrom: ["+111"], // Only allow +111
+        messagePrefix: undefined,
+        responsePrefix: undefined,
+        timestampPrefix: false,
+      },
+    });
+
+    const onMessage = vi.fn();
+    const listener = await monitorWebInbox({ verbose: false, onMessage });
+    const sock = await createWaSocket();
+
+    // Message from unauthorized sender +999 (not in allowFrom)
+    const upsert = {
+      type: "notify",
+      messages: [
+        {
+          key: {
+            id: "unauth1",
+            fromMe: false,
+            remoteJid: "999@s.whatsapp.net",
+          },
+          message: { conversation: "unauthorized message" },
+          messageTimestamp: 1_700_000_000,
+        },
+      ],
+    };
+
+    sock.ev.emit("messages.upsert", upsert);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    // Should NOT call onMessage for unauthorized senders
+    expect(onMessage).not.toHaveBeenCalled();
+
+    // Reset mock for other tests
+    mockLoadConfig.mockReturnValue({
+      inbound: {
+        allowFrom: ["*"],
+        messagePrefix: undefined,
+        responsePrefix: undefined,
+        timestampPrefix: false,
+      },
+    });
+
+    await listener.close();
+  });
+
+  it("allows messages from senders in allowFrom list", async () => {
+    mockLoadConfig.mockReturnValue({
+      inbound: {
+        allowFrom: ["+111", "+999"], // Allow +999
+        messagePrefix: undefined,
+        responsePrefix: undefined,
+        timestampPrefix: false,
+      },
+    });
+
+    const onMessage = vi.fn();
+    const listener = await monitorWebInbox({ verbose: false, onMessage });
+    const sock = await createWaSocket();
+
+    const upsert = {
+      type: "notify",
+      messages: [
+        {
+          key: { id: "auth1", fromMe: false, remoteJid: "999@s.whatsapp.net" },
+          message: { conversation: "authorized message" },
+          messageTimestamp: 1_700_000_000,
+        },
+      ],
+    };
+
+    sock.ev.emit("messages.upsert", upsert);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    // Should call onMessage for authorized senders
+    expect(onMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ body: "authorized message", from: "+999" }),
+    );
+
+    // Reset mock for other tests
+    mockLoadConfig.mockReturnValue({
+      inbound: {
+        allowFrom: ["*"],
+        messagePrefix: undefined,
+        responsePrefix: undefined,
+        timestampPrefix: false,
+      },
+    });
+
+    await listener.close();
+  });
+
+  it("allows same-phone messages even if not in allowFrom", async () => {
+    // Same-phone mode: when from === selfJid, should always be allowed
+    // This allows users to message themselves even with restrictive allowFrom
+    mockLoadConfig.mockReturnValue({
+      inbound: {
+        allowFrom: ["+111"], // Only allow +111, but self is +123
+        messagePrefix: undefined,
+        responsePrefix: undefined,
+        timestampPrefix: false,
+      },
+    });
+
+    const onMessage = vi.fn();
+    const listener = await monitorWebInbox({ verbose: false, onMessage });
+    const sock = await createWaSocket();
+
+    // Message from self (sock.user.id is "123@s.whatsapp.net" in mock)
+    const upsert = {
+      type: "notify",
+      messages: [
+        {
+          key: { id: "self1", fromMe: false, remoteJid: "123@s.whatsapp.net" },
+          message: { conversation: "self message" },
+          messageTimestamp: 1_700_000_000,
+        },
+      ],
+    };
+
+    sock.ev.emit("messages.upsert", upsert);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    // Should allow self-messages even if not in allowFrom
+    expect(onMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ body: "self message", from: "+123" }),
+    );
+
+    // Reset mock for other tests
+    mockLoadConfig.mockReturnValue({
+      inbound: {
+        allowFrom: ["*"],
+        messagePrefix: undefined,
+        responsePrefix: undefined,
+        timestampPrefix: false,
+      },
+    });
+
+    await listener.close();
+  });
 });
@@ -57,29 +57,48 @@ export async function createWaSocket(printQr: boolean, verbose: boolean) {
    markOnlineOnConnect: false,
  });

+  const sessionLogger = getChildLogger({ module: "web-session" });
+
  sock.ev.on("creds.update", saveCreds);
  sock.ev.on(
    "connection.update",
    (update: Partial<import("@whiskeysockets/baileys").ConnectionState>) => {
-      const { connection, lastDisconnect, qr } = update;
-      if (qr && printQr) {
-        console.log("Scan this QR in WhatsApp (Linked Devices):");
-        qrcode.generate(qr, { small: true });
-      }
-      if (connection === "close") {
-        const status = getStatusCode(lastDisconnect?.error);
-        if (status === DisconnectReason.loggedOut) {
-          console.error(
-            danger("WhatsApp session logged out. Run: warelay login"),
-          );
+      try {
+        const { connection, lastDisconnect, qr } = update;
+        if (qr && printQr) {
+          console.log("Scan this QR in WhatsApp (Linked Devices):");
+          qrcode.generate(qr, { small: true });
        }
-      }
-      if (connection === "open" && verbose) {
-        console.log(success("WhatsApp Web connected."));
+        if (connection === "close") {
+          const status = getStatusCode(lastDisconnect?.error);
+          if (status === DisconnectReason.loggedOut) {
+            console.error(
+              danger("WhatsApp session logged out. Run: warelay login"),
+            );
+          }
+        }
+        if (connection === "open" && verbose) {
+          console.log(success("WhatsApp Web connected."));
+        }
+      } catch (err) {
+        sessionLogger.error(
+          { error: String(err) },
+          "connection.update handler error",
+        );
      }
    },
  );

+  // Handle WebSocket-level errors to prevent unhandled exceptions from crashing the process
+  if (
+    sock.ws &&
+    typeof (sock.ws as unknown as { on?: unknown }).on === "function"
+  ) {
+    sock.ws.on("error", (err: Error) => {
+      sessionLogger.error({ error: String(err) }, "WebSocket error");
+    });
+  }
+
  return sock;
 }

@@ -3,18 +3,37 @@ import { vi } from "vitest";
 import type { MockBaileysSocket } from "../../test/mocks/baileys.js";
 import { createMockBaileys } from "../../test/mocks/baileys.js";

-let loadConfigMock: () => unknown = () => ({});
+// Use globalThis to store the mock config so it survives vi.mock hoisting
+const CONFIG_KEY = Symbol.for("warelay:testConfigMock");
+const DEFAULT_CONFIG = {
+  inbound: {
+    allowFrom: ["*"], // Allow all in tests by default
+    messagePrefix: undefined, // No message prefix in tests
+    responsePrefix: undefined, // No response prefix in tests
+    timestampPrefix: false, // No timestamp in tests
+  },
+};

-export function setLoadConfigMock(fn: () => unknown) {
-  loadConfigMock = fn;
+// Initialize default if not set
+if (!(globalThis as Record<symbol, unknown>)[CONFIG_KEY]) {
+  (globalThis as Record<symbol, unknown>)[CONFIG_KEY] = () => DEFAULT_CONFIG;
+}
+
+export function setLoadConfigMock(fn: (() => unknown) | unknown) {
+  (globalThis as Record<symbol, unknown>)[CONFIG_KEY] =
+    typeof fn === "function" ? fn : () => fn;
 }

 export function resetLoadConfigMock() {
-  loadConfigMock = () => ({});
+  (globalThis as Record<symbol, unknown>)[CONFIG_KEY] = () => DEFAULT_CONFIG;
 }

 vi.mock("../config/config.js", () => ({
-  loadConfig: () => loadConfigMock(),
+  loadConfig: () => {
+    const getter = (globalThis as Record<symbol, unknown>)[CONFIG_KEY];
+    if (typeof getter === "function") return getter();
+    return DEFAULT_CONFIG;
+  },
 }));

 vi.mock("../media/store.js", () => ({
Author	SHA1	Message	Date
Peter Steinberger	2b941ccc93	Changelog: note multi-agent and batching CI / build (push) Failing after 27s Details Co-authored-by: RealSid08 <RealSid08@users.noreply.github.com>	2025-12-02 11:11:50 +00:00
Peter Steinberger	ed080ae988	Tests: cover agents and fix web defaults Co-authored-by: RealSid08 <RealSid08@users.noreply.github.com>	2025-12-02 11:08:00 +00:00
Peter Steinberger	f31e89d5af	Agents: add pluggable CLIs Co-authored-by: RealSid08 <RealSid08@users.noreply.github.com>	2025-12-02 11:07:46 +00:00
Peter Steinberger	52c311e47f	chore: bump version to 1.3.0	2025-12-02 07:54:49 +00:00
Peter Steinberger	5b54d4de7a	feat(web): batch inbound messages	2025-12-02 07:54:13 +00:00
Peter Steinberger	96152f6577	Add typing indicator after IPC send After sending via IPC, automatically show "composing" indicator so user knows more messages may be coming from the running session.	2025-12-02 06:58:17 +00:00
Peter Steinberger	e881b3c5de	Document exclamation mark escaping workaround for Claude Code Add symlink CLAUDE.md -> AGENTS.md for Claude Code compatibility.	2025-12-02 06:52:56 +00:00
Peter Steinberger	e86b507da7	Add IPC to prevent Signal session corruption from concurrent connections When the relay is running, `warelay send` and `warelay heartbeat` now communicate via Unix socket IPC (~/.warelay/relay.sock) to send messages through the relay's existing WhatsApp connection. Previously, these commands created new Baileys sockets that wrote to the same auth state files, corrupting the Signal session ratchet and causing the relay's subsequent sends to fail silently. Changes: - Add src/web/ipc.ts with Unix socket server/client - Relay starts IPC server after connecting - send command tries IPC first, falls back to direct - heartbeat uses sendWithIpcFallback helper - inbound.ts exposes sendMessage on listener object - Messages sent via IPC are added to echo detection set	2025-12-02 06:31:07 +00:00
Peter Steinberger	2fc3a822c8	web: isolate session fixtures and skip heartbeat when busy	2025-12-02 06:17:16 +00:00
Peter Steinberger	1b0e1edb08	Update changelog with error message and test isolation fixes	2025-12-02 05:59:31 +00:00
Peter Steinberger	d107b79c63	Fix test corrupting production sessions.json The test 'falls back to most recent session when no to is provided' was using resolveStorePath() which returns the real ~/.warelay/sessions.json. This overwrote production session data with test values, causing session fragmentation issues. Changed to use a temp directory like other tests.	2025-12-02 05:54:31 +00:00
Peter Steinberger	c5ab442f46	Fix empty result JSON dump and missing heartbeat prefix Bug fixes: - Empty result field handling: Changed truthy check to explicit type check (`typeof parsed?.text === "string"`) in command-reply.ts. Previously, Claude CLI returning `result: ""` would cause raw JSON to be sent to WhatsApp. - Response prefix on heartbeat: Apply `responsePrefix` to heartbeat alert messages in runReplyHeartbeat, matching behavior of regular message handler.	2025-12-02 04:29:17 +00:00
Peter Steinberger	c5677df56e	Increase watchdog timeout to 30 minutes Changed from 10 to 30 minutes to avoid false positives when heartbeatMinutes is set to 10. The watchdog should be significantly longer than the heartbeat interval to account for: - Network latency - Slow command responses - Brief connection hiccups With heartbeatMinutes=10, a 30-minute watchdog gives 3x buffer before triggering auto-restart.	2025-11-30 18:03:19 +00:00
Peter Steinberger	21ba0fb8a4	Fix test isolation to prevent loading real user config Tests were picking up real ~/.warelay/warelay.json with emojis and prefixes (like "🦞"), causing test assertions to fail. Added proper config mocks to all test files. Changes: - Mock loadConfig() in index.core.test.ts, inbound.media.test.ts, monitor-inbox.test.ts - Update test-helpers.ts default mock to disable all prefixes - Tests now use clean config: no messagePrefix, no responsePrefix, no timestamp, allowFrom=["*"] This ensures tests validate core behavior without user-specific config. The responsePrefix feature itself is already fully config-driven - this only fixes test isolation.	2025-11-30 18:00:57 +00:00
Peter Steinberger	69319a0569	Add auto-recovery from stuck WhatsApp sessions Fixes issue where unauthorized messages from +212652169245 (5elements spa) triggered Bad MAC errors and silently killed the event emitter, preventing all future message processing. Changes: 1. Early allowFrom filtering in inbound.ts - blocks unauthorized senders before they trigger encryption errors 2. Message timeout watchdog - auto-restarts connection if no messages received for 10 minutes 3. Health monitoring in heartbeat - warns if >30 min without messages 4. Mock loadConfig in tests to handle new dependency Root cause: Event emitter stopped firing after Bad MAC errors from decryption attempts on messages from unauthorized senders. Connection stayed alive but all subsequent messages.upsert events silently failed.	2025-11-30 17:53:32 +00:00
Peter Steinberger	37d8e55991	Skip responsePrefix for HEARTBEAT_OK responses Preserve exact match so warelay recognizes heartbeat responses and doesn't send them as messages.	2025-11-29 06:02:21 +00:00
Peter Steinberger	8d20edb028	Simplify timestampPrefix: bool or timezone string, default true - timestampPrefix: true (UTC), false (off), or 'America/New_York' - Removed separate timestampTimezone option - Default is now enabled (true/UTC) unless explicitly false	2025-11-29 05:29:29 +00:00
Peter Steinberger	7564c4e7f4	Generalize prefix config: messagePrefix + responsePrefix Replaces samePhoneMarker/samePhoneResponsePrefix with: - messagePrefix: prefix for all inbound messages - Default: '[warelay]' if no allowFrom, else '' - responsePrefix: prefix for all outbound replies Also adds timestamp options: - timestampPrefix: boolean to enable [Nov 29 06:30] format - timestampTimezone: IANA timezone (default UTC) Updated README with new config table entries.	2025-11-29 05:27:58 +00:00
Peter Steinberger	26e02a9b8b	Add timestampPrefix config for datetime awareness New config options: - timestampPrefix: boolean - prepend timestamp to messages - timestampTimezone: string - IANA timezone (default: UTC) Format: [Nov 29 06:30] - compact but informative Helps AI assistants stay aware of current date/time.	2025-11-29 05:25:53 +00:00
Peter Steinberger	25ec133574	Add samePhoneResponsePrefix config option Automatically prefixes responses with a configurable string when in same-phone mode. This helps distinguish bot replies from user messages in the same chat bubble. Example config: "samePhoneResponsePrefix": "🦞" Will prefix all same-phone replies with the lobster emoji.	2025-11-29 05:24:01 +00:00
Peter Steinberger	d88ede92b9	feat: same-phone mode with echo detection and configurable marker Adds full support for self-messaging setups where you chat with yourself and an AI assistant replies in the same WhatsApp bubble. Changes: - Same-phone mode (from === to) always allowed, bypasses allowFrom check - Echo detection via bounded Set (max 100) prevents infinite loops - Configurable samePhoneMarker in config (default: "[same-phone]") - Messages prefixed with marker so assistants know the context - fromMe filter removed from inbound.ts (echo detection in auto-reply) - Verbose logging for same-phone detection and echo skips Tests: - Same-phone allowed without/despite allowFrom configuration - Body prefixed only when from === to - Non-same-phone rejected when not in allowFrom	2025-11-29 04:52:21 +00:00
Peter Steinberger	5bafe9483d	chore: release 1.2.2 CI / build (push) Failing after 36s Details	2025-11-28 08:17:22 +01:00
Peter Steinberger	4e3663b4d4	chore: move heartbeat notes to unreleased 1.2.2	2025-11-28 08:14:51 +01:00
Peter Steinberger	12d7be7cad	feat(heartbeat): allow manual message and dry-run for web/twilio	2025-11-28 08:14:07 +01:00
Peter Steinberger	84f2595349	docs: note changelog not needed for pure tests	2025-11-28 08:13:59 +01:00
Peter Steinberger	c11abc1134	chore: release 1.2.1 CI / build (push) Failing after 34s Details	2025-11-28 08:11:07 +01:00
Peter Steinberger	f63bdda628	docs: document mime-first media handling	2025-11-28 08:07:53 +01:00
Peter Steinberger	7d6a4f5204	fix(media): sniff mime and keep extensions	2025-11-28 08:07:53 +01:00
Peter Steinberger	f871869c79	Fix broken link: claude-config.md -> clawd.md	2025-11-28 05:19:43 +00:00
Peter Steinberger	8ebe72951f	docs: Add Twitter automation and music recognition examples - Added Twitter automation patterns using Peekaboo + AppleScript - Documented JS injection for reliable button clicks on Twitter's dynamic UI - Added audd.io music recognition API example - These are the techniques Clawd uses to reply to tweets autonomously	2025-11-27 21:00:28 +00:00
Peter Steinberger	8d4b31a301	Expand heartbeat capabilities in docs	2025-11-27 19:09:30 +01:00
Peter Steinberger	8912b3e035	Rename claude-config.md to clawd.md, update credits - Renamed docs/claude-config.md → docs/clawd.md - Credits now include Clawd (they/them) as co-author	2025-11-27 19:07:35 +01:00
Peter Steinberger	f5d7057042	Add browser-tools CLI and example tweets to docs - Added browser-tools to CLI tools table (lightweight DevTools CLI) - Added browser-tools usage section for web scraping - Added "See It In Action" section with 3 example tweets - Links to agent-scripts repo	2025-11-27 18:59:01 +01:00
Peter Steinberger	6d7e620430	Release 1.2.0 CI / build (push) Failing after 35s Details	2025-11-27 18:52:26 +01:00
Peter Steinberger	0cc732dce3	Docs: refresh 1.2.0 changelog; fix webhook host import	2025-11-27 18:46:46 +01:00
Peter Steinberger	8acd82aa0d	Add gowa WhatsApp MCP to power user add-ons	2025-11-27 18:45:05 +01:00
Peter Steinberger	7377c676fd	Add WhatsApp screenshot to claude-config.md Shows Clawd in action in the "Meet Clawd" section	2025-11-27 18:43:24 +01:00
Peter Steinberger	9b3c4db10d	Heartbeat defaults and ws guard; format	2025-11-27 18:37:30 +01:00
Peter Steinberger	49ada54f6d	Docs: add useful CLI tools section (spotify-player, TTS, etc.)	2025-11-27 18:33:38 +01:00
Peter Steinberger	c43cdc5ac3	Docs: new Clawd session intro with personality and powers	2025-11-27 18:32:47 +01:00
Peter Steinberger	e1bd9976b3	Docs: explain two-phone setup for dedicated AI number	2025-11-27 18:29:41 +01:00
Peter Steinberger	a888564251	Docs: mention Claude Code reuses existing subscription	2025-11-27 18:28:51 +01:00
Peter Steinberger	e2ccde6434	Fix: warelay lowercase	2025-11-27 18:27:09 +01:00
Peter Steinberger	e88ff78816	Add Peekaboo and mcporter links to recommended tools	2025-11-27 18:26:40 +01:00
Peter Steinberger	5bc151fdca	Redact phone number from example config	2025-11-27 18:24:12 +01:00
Peter Steinberger	f0a5cdc6e4	Add warning disclaimer to claude-config.md	2025-11-27 18:23:56 +01:00
Peter Steinberger	85f53a4174	Fix WebSocket crash + heartbeat default 10min + docs refresh - Wrap Baileys connection.update listeners in try-catch to prevent unhandled exceptions from crashing the relay process - Add WebSocket-level error handlers in session.ts - Add global unhandledRejection/uncaughtException handlers in index.ts - Make listener.onClose error-safe with .catch() in auto-reply.ts - Change default heartbeat from 30min to 10min - Rewrite claude-config.md with personality, better explain personal assistant features, add recommended MCPs section	2025-11-27 18:21:14 +01:00
Peter Steinberger	549ad272fc	Docs: link Clawd setup and current config	2025-11-27 18:17:17 +01:00
Peter Steinberger	537348d995	Update README.md	2025-11-27 18:14:54 +01:00
Peter Steinberger	d4580d1a31	Fix CI: type gaps and hasMedia check	2025-11-27 18:14:20 +01:00
Peter Steinberger	93a103dde5	Tests: cover identity prefix gating	2025-11-27 04:40:03 +01:00
Peter Steinberger	9e6ad97cfb	Claude prompt: only prepend on first turn	2025-11-27 03:53:13 +01:00
Peter Steinberger	8d995a8529	Heartbeat: add ultrathink marker	2025-11-27 03:15:51 +01:00
Peter Steinberger	f869cd4b79	Heartbeat: shorten prompt to token	2025-11-27 02:48:23 +01:00
Peter Steinberger	26b087c1b4	Heartbeat: honor session override	2025-11-26 18:32:25 +01:00
Peter Steinberger	63bf4683c5	Heartbeat: allow session-id override (with test)	2025-11-26 18:28:02 +01:00
Peter Steinberger	73456a68d7	Fix heartbeat CLI import for recipients resolution	2025-11-26 18:22:28 +01:00
Peter Steinberger	aa6637b47a	Heartbeat: session-id override and safer fallback	2025-11-26 18:19:54 +01:00
Peter Steinberger	8f6e43fd66	Changelog: bump to 1.2.0 unreleased	2025-11-26 18:18:13 +01:00
Peter Steinberger	ebce6ef263	Docs: show --all heartbeat example	2025-11-26 18:17:30 +01:00
Peter Steinberger	c20a266a11	Heartbeat: harden targeting and support lid mapping	2025-11-26 18:15:57 +01:00
Marcus Neves	b825f141f3	fix: add @lid format support and allowFrom wildcard handling - Add support for WhatsApp Linked ID (@lid) format in jidToE164() - Use existing lid-mapping-_reverse.json files for LID resolution - Fix allowFrom wildcard '' to actually allow all senders - Maintain backward compatibility with @s.whatsapp.net format Fixes issues where: - Messages from newer WhatsApp versions are silently dropped - allowFrom: ['*'] configuration doesn't work as documented	2025-11-26 18:03:12 +01:00
Peter Steinberger	7e5b3958cc	CLI: rename heartbeat tmux helper and log file path	2025-11-26 18:00:23 +01:00
Peter Steinberger	deded848ee	Heartbeat: add relay helper and fix CLI tests	2025-11-26 17:49:34 +01:00
Peter Steinberger	117161e6ff	docs: document heartbeat idle override and tests	2025-11-26 17:31:56 +01:00
Peter Steinberger	98d52edcc9	test: cover heartbeat skip preserving session timestamp	2025-11-26 17:29:12 +01:00
Peter Steinberger	135d930c99	feat: add heartbeat idle override and preserve session freshness	2025-11-26 17:26:17 +01:00
Peter Steinberger	e6c78df975	chore: add verbose heartbeat session logging	2025-11-26 17:21:59 +01:00
Peter Steinberger	3749797434	chore: log heartbeat session snapshot	2025-11-26 17:20:48 +01:00
Peter Steinberger	507ed25289	chore: log heartbeat fallback and add test	2025-11-26 17:12:28 +01:00
Peter Steinberger	0d5e5f8dee	fix: heartbeat falls back to last session contact	2025-11-26 17:08:43 +01:00
Peter Steinberger	3998933b30	docs: document heartbeat triggers	2025-11-26 17:05:09 +01:00
Peter Steinberger	271004bf60	feat: add heartbeat cli and relay trigger	2025-11-26 17:04:43 +01:00
Peter Steinberger	c9e2d69bfb	docs: open 1.1.x unreleased section	2025-11-26 03:33:44 +01:00