chore: release 1.2.2

- 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

AGENTS.md

@@ -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`).

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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.
+
+## 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

README.md

@@ -13,7 +13,7 @@
 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/claude-config.md`](https://github.com/steipete/warelay/blob/main/docs/claude-config.md).
+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.

docs/clawd.md

@@ -161,14 +161,20 @@ Claude is instructed to reply with exactly `HEARTBEAT_OK` if nothing needs atten
 
 ### What Can Heartbeats Do?
 
-Clawd uses heartbeats to:
+Clawd uses heartbeats to do **real work**, not just check in:
-- 🔋 **Monitor battery** - warns when laptop is low
-- ⏰ **Wake-up alarms** - checks the time and triggers alarms (voice + music!)
-- 📅 **Calendar reminders** - surfaces upcoming events
-- 🌤️ **Contextual updates** - weather, travel info, whatever's relevant
-- 💡 **Surprise check-ins** - occasionally just says hi with something fun
 
-The key insight: heartbeats let your AI be **proactive**, not just reactive.
+- 🔋 **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
 
@@ -323,6 +329,7 @@ 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 |
@@ -395,6 +402,83 @@ mcporter handles OAuth flows for services like Linear and Notion, and keeps your
 
 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!
+
 ---
 
-*Built by [@steipete](https://twitter.com/steipete). PRs welcome!*
+## 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!*

docs/images.md

@@ -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

package.json

@@ -1,6 +1,6 @@
 {
   "name": "warelay",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "WhatsApp relay CLI (send, monitor, webhook, auto-reply) using Twilio",
   "type": "module",
   "main": "dist/index.js",

src/cli/program.ts

@@ -17,6 +17,7 @@ import {
   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 {
@@ -179,8 +180,10 @@ Examples:
 
   program
     .command("heartbeat")
-    .description("Trigger a heartbeat poll once (web provider, no tmux)")
+    .description(
-    .option("--provider <provider>", "auto | web", "auto")
+      "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>",
@@ -191,6 +194,12 @@ Examples:
       "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",
@@ -200,6 +209,7 @@ Examples:
   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) => {
@@ -233,27 +243,43 @@ Examples:
         defaultRuntime.exit(1);
       }
       const providerPref = String(opts.provider ?? "auto");
-      if (!["auto", "web"].includes(providerPref)) {
+      if (!["auto", "web", "twilio"].includes(providerPref)) {
-        defaultRuntime.error("--provider must be auto or web");
+        defaultRuntime.error("--provider must be auto, web, or twilio");
-        defaultRuntime.exit(1);
-      }
-      const provider = await pickProvider(providerPref as "auto" | "web");
-      if (provider !== "web") {
-        defaultRuntime.error(
-          danger(
-            "Heartbeat is only supported for the web provider. Link with `warelay login --verbose`.",
-          ),
-        );
         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) {
-          await runWebHeartbeatOnce({
+          if (provider === "web") {
-            to,
+            await runWebHeartbeatOnce({
-            verbose: Boolean(opts.verbose),
+              to,
-            runtime: defaultRuntime,
+              verbose: Boolean(opts.verbose),
-            sessionId: opts.sessionId,
+              runtime: defaultRuntime,
-          });
+              sessionId: opts.sessionId,
+              overrideBody,
+              dryRun,
+            });
+          } else {
+            await runTwilioHeartbeatOnce({
+              to,
+              verbose: Boolean(opts.verbose),
+              runtime: defaultRuntime,
+              overrideBody,
+              dryRun,
+            });
+          }
         }
       } catch {
         defaultRuntime.exit(1);

src/media/mime.ts

@@ -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);
+}

src/media/store.test.ts

@@ -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);
+  });
 });

src/media/store.ts

@@ -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>,
-) {
+): Promise<{ headerMime?: string; sniffBuffer: Buffer; size: number }> {
-  await new Promise<void>((resolve, reject) => {
+  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 tempDest = path.join(dir, `${id}.tmp`);
-    const stat = await fs.stat(dest);
+    const { headerMime, sniffBuffer, size } = await downloadToFile(
-    return { id, path: dest, size: stat.size };
+      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);
+  const buffer = await fs.readFile(source);
-  return { id, path: dest, size: stat.size };
+  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 };
 }

src/twilio/heartbeat.test.ts

@@ -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(),
+    );
+  });
+});

src/twilio/heartbeat.ts

@@ -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;
+  }
+}

src/web/auto-reply.test.ts

@@ -351,6 +351,45 @@ describe("runWebHeartbeatOnce", () => {
     expect(stored["+1999"]?.sessionId).toBe(sessionId);
     expect(stored["+1999"]?.updatedAt).toBeDefined();
   });
+
+  it("sends overrideBody directly and skips resolver", async () => {
+    const sender: typeof sendMessageWeb = vi
+      .fn()
+      .mockResolvedValue({ messageId: "m1", toJid: "jid" });
+    const resolver = vi.fn();
+    setLoadConfigMock({
+      inbound: { allowFrom: ["+1555"], reply: { mode: "command" } },
+    });
+    await runWebHeartbeatOnce({
+      to: "+1555",
+      verbose: false,
+      sender,
+      replyResolver: resolver,
+      overrideBody: "manual ping",
+    });
+    expect(sender).toHaveBeenCalledWith("+1555", "manual ping", {
+      verbose: false,
+    });
+    expect(resolver).not.toHaveBeenCalled();
+  });
+
+  it("dry-run overrideBody prints and skips send", async () => {
+    const sender: typeof sendMessageWeb = vi.fn();
+    const resolver = vi.fn();
+    setLoadConfigMock({
+      inbound: { allowFrom: ["+1555"], reply: { mode: "command" } },
+    });
+    await runWebHeartbeatOnce({
+      to: "+1555",
+      verbose: false,
+      sender,
+      replyResolver: resolver,
+      overrideBody: "dry",
+      dryRun: true,
+    });
+    expect(sender).not.toHaveBeenCalled();
+    expect(resolver).not.toHaveBeenCalled();
+  });
 });
 
 describe("web auto-reply", () => {

src/web/auto-reply.ts

@@ -81,8 +81,17 @@ export async function runWebHeartbeatOnce(opts: {
   runtime?: RuntimeEnv;
   sender?: typeof sendMessageWeb;
   sessionId?: string;
+  overrideBody?: string;
+  dryRun?: boolean;
 }) {
-  const { cfg: cfgOverride, to, verbose = false, sessionId } = opts;
+  const {
+    cfg: cfgOverride,
+    to,
+    verbose = false,
+    sessionId,
+    overrideBody,
+    dryRun = false,
+  } = opts;
   const _runtime = opts.runtime ?? defaultRuntime;
   const replyResolver = opts.replyResolver ?? getReplyFromConfig;
   const sender = opts.sender ?? sendMessageWeb;
@@ -118,7 +127,38 @@ export async function runWebHeartbeatOnce(opts: {
     );
   }
 
+  if (overrideBody && overrideBody.trim().length === 0) {
+    throw new Error("Override body must be non-empty when provided.");
+  }
+
   try {
+    if (overrideBody) {
+      if (dryRun) {
+        console.log(
+          success(
+            `[dry-run] web send -> ${to}: ${overrideBody.trim()} (manual message)`,
+          ),
+        );
+        return;
+      }
+      const sendResult = await sender(to, overrideBody, { verbose });
+      heartbeatLogger.info(
+        {
+          to,
+          messageId: sendResult.messageId,
+          chars: overrideBody.length,
+          reason: "manual-message",
+        },
+        "manual heartbeat message sent",
+      );
+      console.log(
+        success(
+          `sent manual message to ${to} (web), id ${sendResult.messageId}`,
+        ),
+      );
+      return;
+    }
+
     const replyResult = await replyResolver(
       {
         Body: HEARTBEAT_PROMPT,
@@ -177,6 +217,17 @@ export async function runWebHeartbeatOnce(opts: {
     }
 
     const finalText = stripped.text || replyResult.text || "";
+    if (dryRun) {
+      heartbeatLogger.info(
+        { to, reason: "dry-run", chars: finalText.length },
+        "heartbeat dry-run",
+      );
+      console.log(
+        success(`[dry-run] heartbeat -> ${to}: ${finalText.slice(0, 200)}`),
+      );
+      return;
+    }
+
     const sendResult = await sender(to, finalText, { verbose });
     heartbeatLogger.info(
       { to, messageId: sendResult.messageId, chars: finalText.length },

src/web/inbound.media.test.ts

@@ -0,0 +1,104 @@
+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";
+
+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();
+  });
+});

src/web/media.test.ts

@@ -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");
+  });
 });

src/web/media.ts

@@ -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 = detectMime({ buffer: data, filePath: 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 kind = mediaKindFromMime(mime);
   const cap = Math.min(
     maxBytes ?? maxBytesForKind(kind),