bloby-bot 0.70.12 → 0.71.0

package/scripts/install.sh

@@ -7,6 +7,23 @@ set -e
 # Downloads Node.js + Bloby into ~/.bloby — no system dependencies needed.
 # ─────────────────────────────────────────────────────────────────────────────
 
+# Repair $HOME before deriving any install path. Under `sudo`, cron, CI, or a
+# minimal shell, $HOME can be empty or "/" — without this we'd install into the
+# wrong place (or /). Colors aren't defined yet, so this early error is plain.
+if [ -z "${HOME:-}" ] || [ ! -d "${HOME:-}" ]; then
+  _whoami=$(id -un 2>/dev/null || echo "")
+  if [ -n "$_whoami" ] && command -v getent >/dev/null 2>&1; then
+    HOME=$(getent passwd "$_whoami" 2>/dev/null | cut -d: -f6)
+  elif [ -n "$_whoami" ] && command -v dscl >/dev/null 2>&1; then
+    HOME=$(dscl . -read "/Users/$_whoami" NFSHomeDirectory 2>/dev/null | awk '{print $2}')
+  fi
+  export HOME
+fi
+if [ -z "${HOME:-}" ] || [ ! -d "$HOME" ]; then
+  printf 'Error: could not determine your home directory ($HOME is unset).\n' >&2
+  exit 1
+fi
+
 MIN_NODE_MAJOR=18
 NODE_VERSION="22.14.0"
 BLOBY_HOME="$HOME/.bloby"
@@ -14,6 +31,11 @@ TOOLS_DIR="$BLOBY_HOME/tools"
 NODE_DIR="$TOOLS_DIR/node"
 BIN_DIR="$BLOBY_HOME/bin"
 USE_SYSTEM_NODE=false
+LIBC=""
+# Temp paths the cleanup trap removes — kept empty until we own them so an early
+# exit can never `rm -rf` an inherited value (e.g. the system $TMPDIR).
+WORK_DIR=""
+TMPFILE=""
 
 # Brand colors: #00ADFE (light) and #0158FB (deep) -- Morphy palette, 24-bit truecolor
 BLUE='\033[38;2;0;173;254m'
@@ -37,15 +59,47 @@ if [ ! -t 1 ]; then
   BLUE='' PINK='' YELLOW='' RED='' DIM='' BOLD='' RESET='' G1='' G2='' G3='' G4='' G5='' G6='' G7=''
 fi
 
-# Cleanup on exit (restore cursor, reset colors, remove temp files)
+# Cleanup on exit (restore cursor, reset colors, remove temp files).
+# Only remove paths we actually created — never an inherited/unset value.
 cleanup() {
   printf '\033[?25h'  # show cursor
   printf "${RESET}"
-  rm -f "$TMPFILE" 2>/dev/null
-  rm -rf "$TMPDIR" 2>/dev/null
+  [ -n "$TMPFILE" ] && rm -f "$TMPFILE" 2>/dev/null
+  [ -n "$WORK_DIR" ] && rm -rf "$WORK_DIR" 2>/dev/null
+  return 0
 }
 trap cleanup EXIT INT TERM
 
+# ─── Download + integrity helpers ───────────────────────────────────────────
+
+# download_file <url> <dest> — curl/wget with HTTPS floor, timeout, and retry.
+download_file() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL --proto '=https' --tlsv1.2 --connect-timeout 20 --retry 3 --retry-delay 2 -o "$2" "$1"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -q --https-only --tries=3 --timeout=20 -O "$2" "$1"
+  else
+    printf "  ${RED}✗${RESET}  curl or wget is required to install Bloby\n"
+    exit 1
+  fi
+}
+
+# verify_sha256 <file> <expected-hex> — 0 match, 1 mismatch, 2 no tool available.
+verify_sha256() {
+  _actual=""
+  if command -v sha256sum >/dev/null 2>&1; then
+    _actual=$(sha256sum "$1" 2>/dev/null | awk '{print $1}')
+  elif command -v shasum >/dev/null 2>&1; then
+    _actual=$(shasum -a 256 "$1" 2>/dev/null | awk '{print $1}')
+  else
+    return 2
+  fi
+  # No hash computed (tool failed / file vanished) → "skip" (2), not "mismatch" (1),
+  # so we warn rather than aborting with a misleading "tampered download".
+  [ -n "$_actual" ] || return 2
+  [ "$_actual" = "$2" ]
+}
+
 printf "\n"
 printf "${G1}${BOLD}                                █▄         ${RESET}\n"
 printf "${G2}${BOLD}      ▄              ▄          ██         ${RESET}\n"
@@ -83,6 +137,14 @@ detect_platform() {
       ;;
   esac
 
+  # Detect musl (Alpine): nodejs.org ships glibc builds only, so a bundled Node
+  # would segfault at runtime. Flag it now and require a system Node instead.
+  if [ "$PLATFORM" = "linux" ]; then
+    if [ -f /etc/alpine-release ] || (ldd --version 2>&1 | grep -qi musl); then
+      LIBC="musl"
+    fi
+  fi
+
   printf "  ${DIM}Platform: ${PLATFORM}/${NODEARCH}${RESET}\n"
 }
 
@@ -115,35 +177,68 @@ install_node() {
     fi
   fi
 
-  printf "  ${BLUE}↓${RESET}  Downloading Node.js v${NODE_VERSION}...\n"
+  # nodejs.org ships glibc-linked builds; on musl they segfault at runtime.
+  if [ "$LIBC" = "musl" ]; then
+    printf "  ${RED}✗${RESET}  Alpine/musl detected — Bloby's bundled Node.js requires glibc.\n"
+    printf "  ${DIM}Install Node.js >= ${MIN_NODE_MAJOR} (e.g. ${BOLD}apk add nodejs npm${RESET}${DIM}) and re-run this installer.${RESET}\n"
+    exit 1
+  fi
 
-  NODE_URL="https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-${PLATFORM}-${NODEARCH}.tar.xz"
-  TMPFILE=$(mktemp /tmp/node-XXXXXX.tar.xz)
+  printf "  ${BLUE}↓${RESET}  Downloading Node.js v${NODE_VERSION}...\n"
 
-  # Download
-  if command -v curl >/dev/null 2>&1; then
-    curl -fsSL -o "$TMPFILE" "$NODE_URL"
-  elif command -v wget >/dev/null 2>&1; then
-    wget -qO "$TMPFILE" "$NODE_URL"
+  NODE_FILE="node-v${NODE_VERSION}-${PLATFORM}-${NODEARCH}.tar.xz"
+  NODE_URL="https://nodejs.org/dist/v${NODE_VERSION}/${NODE_FILE}"
+  # Trailing X's, NO suffix: BSD mktemp (macOS) only substitutes trailing X's,
+  # so a ".tar.xz" suffix would create a literal, predictable, non-unique file.
+  TMPFILE=$(mktemp "${TMPDIR:-/tmp}/bloby-node-XXXXXX")
+  download_file "$NODE_URL" "$TMPFILE"
+
+  # Integrity: verify against nodejs.org SHASUMS256.txt before extracting. A
+  # mismatch is fatal; an unreachable sums file or missing hash tool degrades to
+  # a warning so installs still proceed (the download itself is TLS-protected).
+  printf "  ${DIM}Verifying download...${RESET}\n"
+  EXPECTED_SHA=""
+  SUMS=$(curl -fsSL --proto '=https' --tlsv1.2 --connect-timeout 20 "https://nodejs.org/dist/v${NODE_VERSION}/SHASUMS256.txt" 2>/dev/null \
+    || wget -q --https-only --timeout=20 -O- "https://nodejs.org/dist/v${NODE_VERSION}/SHASUMS256.txt" 2>/dev/null \
+    || echo "")
+  if [ -n "$SUMS" ]; then
+    EXPECTED_SHA=$(printf '%s\n' "$SUMS" | awk -v f="$NODE_FILE" '$2==f {print $1; exit}')
+  fi
+  if [ -n "$EXPECTED_SHA" ]; then
+    vrc=0
+    verify_sha256 "$TMPFILE" "$EXPECTED_SHA" || vrc=$?
+    if [ "$vrc" = "0" ]; then
+      printf "  ${BLUE}✔${RESET}  Checksum verified\n"
+    elif [ "$vrc" = "2" ]; then
+      printf "  ${YELLOW}!${RESET}  Could not compute checksum — skipping verification\n"
+    else
+      printf "  ${RED}✗${RESET}  Node.js checksum mismatch — aborting (corrupt or tampered download)\n"
+      exit 1
+    fi
   else
-    printf "  ${RED}✗${RESET}  curl or wget required\n"
-    exit 1
+    printf "  ${YELLOW}!${RESET}  Could not fetch checksums — skipping verification\n"
   fi
 
-  # Extract
+  # Extract into a staging dir, verify it runs, then atomically swap in. An
+  # interrupt mid-extract no longer wipes the existing (working) node.
   mkdir -p "$TOOLS_DIR"
-  rm -rf "$NODE_DIR"
-  mkdir -p "$NODE_DIR"
-
-  tar xf "$TMPFILE" -C "$NODE_DIR" --strip-components=1
-  rm -f "$TMPFILE"
-
-  # Verify
-  if [ ! -x "$NODE_DIR/bin/node" ]; then
-    printf "  ${RED}✗${RESET}  Node.js download failed\n"
+  NODE_NEW="$NODE_DIR.new"
+  rm -rf "$NODE_NEW"
+  mkdir -p "$NODE_NEW"
+  tar xf "$TMPFILE" -C "$NODE_NEW" --strip-components=1
+  rm -f "$TMPFILE"; TMPFILE=""
+
+  if ! "$NODE_NEW/bin/node" -v >/dev/null 2>&1; then
+    printf "  ${RED}✗${RESET}  Node.js download failed (extracted binary does not run)\n"
+    rm -rf "$NODE_NEW"
     exit 1
   fi
 
+  rm -rf "$NODE_DIR.old"
+  [ -e "$NODE_DIR" ] && mv "$NODE_DIR" "$NODE_DIR.old"
+  mv "$NODE_NEW" "$NODE_DIR"
+  rm -rf "$NODE_DIR.old"
+
   printf "  ${BLUE}✔${RESET}  Node.js v${NODE_VERSION} installed\n"
 }
 
@@ -174,19 +269,15 @@ install_bloby() {
     exit 1
   fi
 
-  # Download and extract tarball
-  TMPDIR=$(mktemp -d)
-  if command -v curl >/dev/null 2>&1; then
-    curl -fsSL -o "$TMPDIR/bloby.tgz" "$TARBALL_URL"
-  elif command -v wget >/dev/null 2>&1; then
-    wget -qO "$TMPDIR/bloby.tgz" "$TARBALL_URL"
-  fi
+  # Download and extract tarball (download_file guards on missing curl/wget)
+  WORK_DIR=$(mktemp -d)
+  download_file "$TARBALL_URL" "$WORK_DIR/bloby.tgz"
 
-  tar xzf "$TMPDIR/bloby.tgz" -C "$TMPDIR"
-  EXTRACTED="$TMPDIR/package"
+  tar xzf "$WORK_DIR/bloby.tgz" -C "$WORK_DIR"
+  EXTRACTED="$WORK_DIR/package"
 
   if [ ! -d "$EXTRACTED" ]; then
-    rm -rf "$TMPDIR"
+    rm -rf "$WORK_DIR"; WORK_DIR=""
     printf "  ${RED}✗${RESET}  Installation failed\n"
     exit 1
   fi
@@ -219,7 +310,7 @@ install_bloby() {
     fi
   fi
 
-  rm -rf "$TMPDIR"
+  rm -rf "$WORK_DIR"; WORK_DIR=""
 
   # Install dependencies inside ~/.bloby/
   # claude-agent-sdk 0.3.x moved @anthropic-ai/sdk + @modelcontextprotocol/sdk to
@@ -245,6 +336,15 @@ install_bloby() {
     WS_INSTALL_LOG=$(mktemp)
     if ! (cd "$BLOBY_HOME/workspace" && "$NPM" install --omit=dev > "$WS_INSTALL_LOG" 2>&1); then
       printf "  ${RED}✗${RESET}  Workspace dependency install failed:\n"
+      # Native modules (better-sqlite3 etc.) need a compiler toolchain — detect
+      # the common "missing build tools" failure and point at the exact fix.
+      if grep -qiE 'make: .*command not found|gyp ERR! find Python|no developer tools|xcode-select|command not found: make|g\+\+: not found' "$WS_INSTALL_LOG"; then
+        if [ "$PLATFORM" = "darwin" ]; then
+          printf "  ${YELLOW}!${RESET}  Native build tools missing. Run ${BOLD}xcode-select --install${RESET} then re-run this installer.\n"
+        else
+          printf "  ${YELLOW}!${RESET}  Native build tools missing. On Debian/Ubuntu: ${BOLD}sudo apt-get install -y build-essential python3${RESET}, then re-run.\n"
+        fi
+      fi
       cat "$WS_INSTALL_LOG"
       rm -f "$WS_INSTALL_LOG"
       exit 1
@@ -348,19 +448,34 @@ install_bloby
 create_wrapper
 setup_path
 
+# Smoke-test: the wrapper + node + cli must actually run, not just exist on disk.
+if ! "$BIN_DIR/bloby" --version >/dev/null 2>&1; then
+  printf "\n  ${RED}✗${RESET}  Bloby installed but failed to run (\`bloby --version\`).\n"
+  printf "  ${DIM}Open a NEW terminal and run ${BOLD}bloby --version${RESET}${DIM}; if it still fails, re-run this installer.${RESET}\n\n"
+  exit 1
+fi
+
 printf "\n"
-printf "  ${PINK}${BOLD}✔  Bloby is ready!${RESET}\n"
+printf "  ${PINK}${BOLD}✔  Bloby is installed!${RESET}\n"
 printf "\n"
-printf "  ${DIM}─────────────────────────────${RESET}\n"
-printf "  ${BOLD}Get started:${RESET}\n"
+printf "  ${BLUE}${BOLD}╭───────────────────────────────────────────────────────╮${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}${BOLD}   NEXT STEP  -  type this, then press Enter:${RESET}          ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}${BLUE}${BOLD}       >  bloby init${RESET}                                   ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}${DIM}   ─────────────────────────────────────────────────${RESET}   ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}${YELLOW}${BOLD}   Not working?  (\"command not found\")${RESET}                 ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}   Just open a NEW terminal window and run${RESET}             ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}   bloby init  again.${RESET}                                  ${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}│${RESET}                                                       ${RESET}${BLUE}${BOLD}│${RESET}\n"
+printf "  ${BLUE}${BOLD}╰───────────────────────────────────────────────────────╯${RESET}\n"
 printf "\n"
-printf "    ${BLUE}bloby init${RESET}      Set up your bot\n"
+printf "  ${DIM}Other commands:${RESET}\n"
 printf "    ${BLUE}bloby start${RESET}     Start your bot\n"
 printf "    ${BLUE}bloby status${RESET}    Check if it's running\n"
 printf "    ${BLUE}bloby help${RESET}      All commands\n"
 printf "\n"
-printf "  ${PINK}>${RESET} Run ${BLUE}bloby init${RESET} to begin.\n"
-printf "  ${DIM}(Open a new terminal if 'bloby' isn't found yet)${RESET}\n"
-printf "\n"
 printf "  ${DIM}https://bloby.bot${RESET}\n"
 printf "\n"

package/shared/config.ts

@@ -97,7 +97,20 @@ const MODEL_MIGRATIONS: Record<string, string> = {
 
 export function loadConfig(): BotConfig {
   if (!fs.existsSync(paths.config)) throw new Error('No config. Run `bloby init`.');
-  const config = JSON.parse(fs.readFileSync(paths.config, 'utf-8'));
+  let config: BotConfig;
+  try {
+    config = JSON.parse(fs.readFileSync(paths.config, 'utf-8'));
+  } catch {
+    // Torn/truncated write — recover from the .bak mirror rather than crashing
+    // the supervisor (or, worse, letting the CLI regenerate a fresh wallet).
+    const bak = `${paths.config}.bak`;
+    if (fs.existsSync(bak)) {
+      config = JSON.parse(fs.readFileSync(bak, 'utf-8'));
+      try { saveConfig(config); } catch {}
+    } else {
+      throw new Error('config.json is corrupt and no backup (.bak) was found.');
+    }
+  }
   let dirty = false;
 
   // Backward compat: migrate old { enabled: boolean } → { mode }
@@ -119,5 +132,27 @@ export function loadConfig(): BotConfig {
 
 export function saveConfig(config: BotConfig): void {
   fs.mkdirSync(DATA_DIR, { recursive: true });
-  fs.writeFileSync(paths.config, JSON.stringify(config, null, 2));
+  // Atomic write: temp file + rename, then mirror to .bak. config.json holds the
+  // funded wallet and is written by BOTH this supervisor and the CLI, so a plain
+  // writeFileSync can be observed half-written (the Jun-9 0-byte-creds class of
+  // bug, here applied to the one file that must never be lost).
+  const json = JSON.stringify(config, null, 2);
+  const tmp = `${paths.config}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, json);
+    try {
+      fs.renameSync(tmp, paths.config);
+    } catch (err) {
+      // Windows: rename over a file another process holds open can EPERM/EEXIST.
+      const code = (err as NodeJS.ErrnoException)?.code;
+      if (process.platform === 'win32' && (code === 'EPERM' || code === 'EEXIST')) {
+        fs.copyFileSync(tmp, paths.config);
+        fs.unlinkSync(tmp);
+      } else throw err;
+    }
+    try { fs.copyFileSync(paths.config, `${paths.config}.bak`); } catch {}
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch {}
+    throw err;
+  }
 }

package/shared/relay.ts

@@ -122,7 +122,9 @@ export function startHeartbeat(token: string, tunnelUrl?: string): void {
   };
 
   beat(); // immediate first beat
-  heartbeatTimer = setInterval(beat, 30_000); // every 30s
+  // Every 120s. The relay's HEARTBEAT_TIMEOUT_MS must stay well above this (currently
+  // 360s = 3 missed beats of grace) so a single dropped beat never flaps a healthy bot.
+  heartbeatTimer = setInterval(beat, 120_000);
 }
 
 export function stopHeartbeat(): void {

package/supervisor/channels/manager.ts

@@ -29,7 +29,7 @@ import { AlexaChannel } from './alexa.js';
 import { TelegramChannel, type TelegramInbound } from './telegram.js';
 import type { ChannelConfig, ChannelProvider, ChannelStatus, ChannelType, InboundMessage, InboundMessageAttachment, RoutingTarget, SenderRole } from './types.js';
 import type { AgentAttachment } from '../bloby-agent.js';
-import { saveAttachment, type SavedFile } from '../file-saver.js';
+import { saveAttachment, MAX_ATTACHMENTS_PER_MESSAGE, MAX_TOTAL_ATTACHMENT_BYTES, type SavedFile } from '../file-saver.js';
 import type { WAMessageKey } from '@whiskeysockets/baileys';
 
 const MAX_CONCURRENT_AGENTS = 5;
@@ -37,16 +37,34 @@ const MAX_BUFFER_MESSAGES = 30;
 const DEBOUNCE_MS = 4000; // 4s — wait for the user to finish typing
 
 /** Persist channel-inbound attachments to disk so harnesses that consume file
- *  paths (Codex's `localImage`) can see them. Failures are logged and the
- *  attachment is dropped — text-only delivery is still useful. */
-function saveInboundAttachments(attachments?: AgentAttachment[]): SavedFile[] {
-  if (!attachments?.length) return [];
+ *  paths (Codex's `localImage`) can see them. Per-file failures are logged and that
+ *  attachment is dropped — one oversize/corrupt file can't abort the whole message,
+ *  and text-only delivery still goes through. Bounded by MAX_ATTACHMENTS_PER_MESSAGE
+ *  (count) and MAX_TOTAL_ATTACHMENT_BYTES (decoded bytes) so a single message can't
+ *  flood the disk; saveAttachment itself caps each file's size. */
+function saveInboundAttachments(attachments?: AgentAttachment[]): { saved: SavedFile[]; accepted: AgentAttachment[] } {
+  if (!attachments?.length) return { saved: [], accepted: [] };
+  const capped = attachments.slice(0, MAX_ATTACHMENTS_PER_MESSAGE);
+  if (attachments.length > capped.length) {
+    log.warn(`[channels] Dropping ${attachments.length - capped.length} inbound attachment(s) over the per-message cap (${MAX_ATTACHMENTS_PER_MESSAGE})`);
+  }
   const saved: SavedFile[] = [];
-  for (const att of attachments) {
-    try { saved.push(saveAttachment(att)); }
+  // The raw attachments that actually saved within budget — handed to the harness so the
+  // model inlines exactly what got persisted + shown in chat (no over-cap divergence).
+  const accepted: AgentAttachment[] = [];
+  let totalBytes = 0;
+  for (const att of capped) {
+    // Estimate decoded size from the base64 length (×3/4) before writing so a burst of
+    // mid-size files can't blow the per-message byte budget in aggregate.
+    totalBytes += Math.floor((att.data?.length || 0) * 0.75);
+    if (totalBytes > MAX_TOTAL_ATTACHMENT_BYTES) {
+      log.warn('[channels] Per-message attachment byte budget exceeded — dropping remaining inbound attachments');
+      break;
+    }
+    try { saved.push(saveAttachment(att)); accepted.push(att); }
     catch (err: any) { log.warn(`[channels] Failed to save inbound attachment: ${err.message}`); }
   }
-  return saved;
+  return { saved, accepted };
 }
 
 interface ChannelManagerOpts {
@@ -68,6 +86,17 @@ interface BufferedMessage {
   content: string;
 }
 
+/** Cap a rolling per-customer history buffer AND keep the window starting on a
+ *  user message. A blind length-splice can leave the window assistant-first,
+ *  which the Anthropic Messages API rejects outright once the pi harness sends
+ *  the buffer as structured chat history — every reply in that thread then
+ *  silently fails (audit C-7). Trimming at the source fixes it for every
+ *  provider flavor at once. */
+function trimCustomerBuffer(buf: BufferedMessage[]): void {
+  if (buf.length > MAX_BUFFER_MESSAGES) buf.splice(0, buf.length - MAX_BUFFER_MESSAGES);
+  while (buf.length > 0 && buf[0].role !== 'user') buf.shift();
+}
+
 interface DebounceEntry {
   messages: string[];
   attachments: InboundMessageAttachment[];
@@ -133,8 +162,8 @@ export class ChannelManager {
     if (channelConfigs?.whatsapp?.enabled && !this.providers.has('whatsapp')) {
       log.info('[channels] Initializing WhatsApp channel...');
       const whatsapp = new WhatsAppChannel(
-        (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, images, inboundKey) => {
-          const attachments = images?.map((img) => ({ type: 'image' as const, mediaType: img.mediaType, data: img.data }));
+        (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, media, inboundKey) => {
+          const attachments = media?.map((att) => ({ type: att.type, mediaType: att.mediaType, data: att.data, name: att.name }));
           this.handleInboundMessage('whatsapp', sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, attachments, inboundKey);
         },
         (status) => this.handleStatusChange(status),
@@ -200,7 +229,7 @@ export class ChannelManager {
       }
     }
     const isOwner = !!ownerUserId && msg.fromUserId === String(ownerUserId);
-    const attachments = msg.images?.map((img) => ({ type: 'image' as const, mediaType: img.mediaType, data: img.data }));
+    const attachments = msg.attachments?.map((att) => ({ type: att.type, mediaType: att.mediaType, data: att.data, name: att.name }));
     // Sanitize the attacker-controlled display name so it can't fake a `[Telegram | … | admin]`
     // context tag or inject newlines into the agent's context.
     const safeName = msg.senderName ? msg.senderName.replace(/[\[\]|\r\n]/g, ' ').slice(0, 64).trim() || undefined : undefined;
@@ -225,8 +254,8 @@ export class ChannelManager {
     if (provider?.getStatus().connected) return;
     if (!provider) {
       const whatsapp = new WhatsAppChannel(
-        (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, images, inboundKey) => {
-          const attachments = images?.map((img) => ({ type: 'image' as const, mediaType: img.mediaType, data: img.data }));
+        (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, media, inboundKey) => {
+          const attachments = media?.map((att) => ({ type: att.type, mediaType: att.mediaType, data: att.data, name: att.name }));
           this.handleInboundMessage('whatsapp', sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, attachments, inboundKey);
         },
         (status) => this.handleStatusChange(status),
@@ -600,7 +629,7 @@ export class ChannelManager {
         const buf = this.customerBuffers.get(target.assistantBufferKey);
         if (buf) {
           buf.push({ role: 'assistant', content: eventData.content });
-          if (buf.length > MAX_BUFFER_MESSAGES) buf.splice(0, buf.length - MAX_BUFFER_MESSAGES);
+          trimCustomerBuffer(buf);
         }
       }
       return;
@@ -981,12 +1010,34 @@ export class ChannelManager {
     const channelTag = `[${this.channelLabel(msg.channel)} | ${msg.sender} | ${earlyRoleTag}]\n`;
     const displayContent = channelTag + rawDisplay;
 
+    // Convert inbound attachments to agent format and persist them to disk BEFORE the
+    // user-message persist/broadcast — so the StoredAttachment array (filePath-based, served
+    // at /api/files/<relPath>) can ride along in meta.attachments + chat:sync. Without this
+    // the agent sees the media but the chat shows nothing (live or after refresh). An image
+    // keeps an auto-generated name; a file uses the channel-provided filename. (Mirrors the
+    // PWA path in supervisor/index.ts.)
+    const agentAttachments: AgentAttachment[] | undefined = msg.attachments?.map((att) => ({
+      type: att.type,
+      name: att.type === 'image'
+        ? `${msg.channel}_image.${att.mediaType.split('/')[1] || 'jpg'}`
+        : (att.name || `${msg.channel}_file`),
+      mediaType: att.mediaType,
+      data: att.data,
+    }));
+    // Save to disk so providers that consume file paths (Codex → localImage) can see the
+    // attachment. Claude consumes raw base64 from `agentAttachments` directly, but the
+    // on-disk copy is what the chat UI renders (filePath → /api/files/<relPath>).
+    const { saved: savedFiles, accepted: acceptedAttachments } = saveInboundAttachments(agentAttachments);
+    const storedAtts = savedFiles.map((f) => ({ type: f.type, name: f.name, mediaType: f.mediaType, filePath: f.relPath }));
+
     // Save user message to DB
     try {
+      const userMeta: any = { model, channel: msg.channel };
+      if (storedAtts.length) userMeta.attachments = JSON.stringify(storedAtts);
       await workerApi(`/api/conversations/${convId}/messages`, 'POST', {
         role: 'user',
         content: displayContent,
-        meta: { model, channel: msg.channel },
+        meta: userMeta,
       });
     } catch (err: any) {
       log.warn(`[channels] DB persist error: ${err.message}`);
@@ -995,7 +1046,12 @@ export class ChannelManager {
     // Broadcast to chat clients (mirroring)
     broadcastBloby('chat:sync', {
       conversationId: convId,
-      message: { role: 'user', content: displayContent, timestamp: new Date().toISOString() },
+      message: {
+        role: 'user',
+        content: displayContent,
+        timestamp: new Date().toISOString(),
+        attachments: storedAtts.length ? storedAtts : undefined,
+      },
     });
 
     // Fetch names and recent messages
@@ -1022,18 +1078,6 @@ export class ChannelManager {
     // Channel context — same tag we already prepended to the stored display content
     const channelContext = channelTag;
 
-    // Convert inbound attachments to agent format
-    const agentAttachments: AgentAttachment[] | undefined = msg.attachments?.map((att) => ({
-      type: 'image' as const,
-      name: `whatsapp_image.${att.mediaType.split('/')[1] || 'jpg'}`,
-      mediaType: att.mediaType,
-      data: att.data,
-    }));
-    // Save to disk so providers that consume file paths (Codex → localImage)
-    // can see the attachment. Claude consumes raw base64 from `agentAttachments`
-    // directly, but the on-disk copy is still useful for the path mention.
-    const savedFiles = saveInboundAttachments(agentAttachments);
-
     // Show "typing..." in the correct chat
     this.startTyping(msg.channel, msg.rawSender);
 
@@ -1116,7 +1160,7 @@ export class ChannelManager {
       assistantBufferKey: msg.role === 'assistant' ? `${msg.channel}:${msg.sender}` : undefined,
       inboundKey: msg.inboundKey,
     };
-    this.pushWithRouting(convId, target, channelContent, agentAttachments, savedFiles);
+    this.pushWithRouting(convId, target, channelContent, acceptedAttachments, savedFiles);
   }
 
   /** Synchronously handle an Alexa utterance: push into the shared conversation,
@@ -1305,10 +1349,8 @@ export class ChannelManager {
     // Add the new user message to the buffer
     buffer.push({ role: 'user', content: msg.text });
 
-    // Trim buffer to max size
-    if (buffer.length > MAX_BUFFER_MESSAGES) {
-      buffer.splice(0, buffer.length - MAX_BUFFER_MESSAGES);
-    }
+    // Trim buffer to max size (user-first — see trimCustomerBuffer)
+    trimCustomerBuffer(buffer);
 
     // Build recent messages for context (everything except the last one, which is the current message)
     const recentMessages: RecentMessage[] = buffer.length > 1
@@ -1329,14 +1371,16 @@ export class ChannelManager {
 
     const channelContext = `[${this.channelLabel(msg.channel)} | ${msg.sender} | customer${msg.senderName ? ` | ${msg.senderName}` : ''}]\n`;
 
-    // Convert inbound attachments to agent format
+    // Convert inbound attachments to agent format (image → auto-name; file → channel filename)
     const agentAttachments: AgentAttachment[] | undefined = msg.attachments?.map((att) => ({
-      type: 'image' as const,
-      name: `whatsapp_image.${att.mediaType.split('/')[1] || 'jpg'}`,
+      type: att.type,
+      name: att.type === 'image'
+        ? `${msg.channel}_image.${att.mediaType.split('/')[1] || 'jpg'}`
+        : (att.name || `${msg.channel}_file`),
       mediaType: att.mediaType,
       data: att.data,
     }));
-    const savedFiles = saveInboundAttachments(agentAttachments);
+    const { saved: savedFiles, accepted: acceptedAttachments } = saveInboundAttachments(agentAttachments);
 
     // Stable convId per customer (not per message)
     const convId = `channel-${agentKey}`;
@@ -1376,9 +1420,7 @@ export class ChannelManager {
         if (type === 'bot:response' && eventData.content) {
           // Add full response to the conversation buffer
           buffer!.push({ role: 'assistant', content: eventData.content });
-          if (buffer!.length > MAX_BUFFER_MESSAGES) {
-            buffer!.splice(0, buffer!.length - MAX_BUFFER_MESSAGES);
-          }
+          trimCustomerBuffer(buffer!);
 
           // Send remaining text after the last tool use (or full response if no tools were used)
           const remaining = waChunkBuf.trim();
@@ -1397,7 +1439,7 @@ export class ChannelManager {
           this.processQueue();
         }
       },
-      agentAttachments,
+      acceptedAttachments,
       savedFiles,
       { botName, humanName },
       recentMessages,
@@ -1424,9 +1466,7 @@ export class ChannelManager {
     }
     const label = fromMe ? 'me' : (senderName || chatId);
     buffer.push({ role: 'user', content: `[${label}]: ${text}` });
-    if (buffer.length > MAX_BUFFER_MESSAGES) {
-      buffer.splice(0, buffer.length - MAX_BUFFER_MESSAGES);
-    }
+    trimCustomerBuffer(buffer);
     log.info(`[channels] Assistant context stored: ${bufferKey} | ${buffer.length} msgs | [${label}]: "${text.slice(0, 60)}"`);
   }