v0.5.1: faster message handling + stall-aware typing

- Event-driven message wake: channels signal the loop immediately instead
  of waiting for the next poll tick (~2s → <5ms)
- Poll interval reduced to 500ms as fallback (was 2000ms)
- Typing indicator stops after 15s of no agent output (stall detection),
  resumes when output flows again
- Agents now acknowledge long tasks before starting ("On it — checking X")
- Heartbeat: suppress reasoning noise, only report actual problems

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ziggy

groups/global/CLAUDE.md

@@ -16,7 +16,18 @@ You are a personal AI assistant running on a dedicated machine. You help with ta
 
 Your output is sent to the user or group.
 
-You also have `mcp__ghostclaw__send_message` which sends a message immediately while you're still working. This is useful when you want to acknowledge a request before starting longer work.
+You also have `mcp__ghostclaw__send_message` which sends a message immediately while you're still working.
+
+### Acknowledge before long tasks
+
+If a request will take more than a few seconds (research, multi-step work, file operations, anything involving tools), immediately send a short ack via `send_message` before starting:
+- "On it — checking X"
+- "Looking into that"
+- "Running that now"
+
+Keep it to one short line. Don't ack simple questions you can answer directly.
+
+If the request is ambiguous or you need clarification, ask via `send_message` right away instead of guessing.
 
 ### Internal thoughts
 

groups/main/CLAUDE.md

@@ -32,7 +32,18 @@ No filler. No "Great question!" No "I'd be happy to help." No emoji unless asked
 
 Output is sent to the user via Telegram (main channel) or WhatsApp (group chats).
 
-`mcp__ghostclaw__send_message` sends a message immediately while you're still working. Useful to acknowledge a request before starting longer work.
+`mcp__ghostclaw__send_message` sends a message immediately while you're still working.
+
+### Acknowledge before long tasks
+
+If a request will take more than a few seconds (research, multi-step work, file operations, anything involving tools), immediately send a short ack via `send_message` before starting:
+- "On it — checking X"
+- "Looking into that"
+- "Running that now"
+
+Keep it to one short line. Don't ack simple questions you can answer directly.
+
+If the request is ambiguous or you need clarification, ask via `send_message` right away instead of guessing.
 
 ### Telegram Formatting
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghostclaw",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Personal AI assistant. Bare metal, Telegram-first, no containers.",
   "type": "module",
   "main": "dist/index.js",

src/channels/telegram.ts

@@ -2,6 +2,7 @@ import { Bot, InputFile } from 'grammy';
 
 import { ASSISTANT_NAME, TRIGGER_PATTERN } from '../config.js';
 import { logger } from '../logger.js';
+import { signalNewMessage } from '../message-signal.js';
 import { transcribeBuffer, textToSpeech } from '../transcription.js';
 import { markdownToTelegramHtml } from '../router.js';
 import {
@@ -124,6 +125,7 @@ export class TelegramChannel implements Channel {
         timestamp,
         is_from_me: false,
       });
+      signalNewMessage();
 
       logger.info(
         { chatJid, chatName, sender: senderName },
@@ -163,6 +165,7 @@ export class TelegramChannel implements Channel {
         timestamp,
         is_from_me: false,
       });
+      signalNewMessage();
     };
 
     this.bot.on('message:photo', (ctx) => storeNonText(ctx, '[Photo]'));

src/channels/whatsapp.ts

@@ -19,6 +19,7 @@ import {
 } from '../config.js';
 import { getLastGroupSync, setLastGroupSync, updateChatName } from '../db.js';
 import { logger } from '../logger.js';
+import { signalNewMessage } from '../message-signal.js';
 import {
   isVoiceMessage,
   transcribeAudioMessage,
@@ -259,6 +260,7 @@ export class WhatsAppChannel implements Channel {
             is_from_me: fromMe,
             is_bot_message: isBotMessage,
           });
+          signalNewMessage();
         }
       }
     });

src/config.ts

@@ -17,7 +17,7 @@ export const ASSISTANT_NAME =
 export const ASSISTANT_HAS_OWN_NUMBER =
   (process.env.ASSISTANT_HAS_OWN_NUMBER ||
     envConfig.ASSISTANT_HAS_OWN_NUMBER) === 'true';
-export const POLL_INTERVAL = 2000;
+export const POLL_INTERVAL = 500;
 export const SCHEDULER_POLL_INTERVAL = 60000;
 
 const PROJECT_ROOT = process.cwd();

src/index.ts

@@ -11,6 +11,7 @@ import {
   TELEGRAM_ONLY,
   TRIGGER_PATTERN,
 } from './config.js';
+import { waitForMessage } from './message-signal.js';
 import { TelegramChannel } from './channels/telegram.js';
 import { WhatsAppChannel } from './channels/whatsapp.js';
 import { initErrorAlerts, sendErrorAlert } from './error-alerts.js';
@@ -195,16 +196,36 @@ async function processGroupMessages(chatJid: string): Promise<boolean> {
     }, IDLE_TIMEOUT);
   };
 
-  // Keep typing indicator alive throughout processing (Telegram expires it after 5s)
+  // Stall-aware typing indicator:
+  // - Refreshes every 4s (Telegram expires typing after 5s)
+  // - Stops after 15s of no agent output (stall detection)
+  // - Resumes when output flows again
+  const TYPING_STALL_MS = 15_000;
+  let typingActive = true;
+  let lastOutputAt = Date.now();
+
   const typingInterval = setInterval(() => {
-    channel.setTyping?.(chatJid, true)?.catch(() => {});
+    if (typingActive && Date.now() - lastOutputAt < TYPING_STALL_MS) {
+      channel.setTyping?.(chatJid, true)?.catch(() => {});
+    } else if (typingActive) {
+      // Stalled — stop typing until output resumes
+      typingActive = false;
+      channel.setTyping?.(chatJid, false)?.catch(() => {});
+    }
   }, 4000);
   await channel.setTyping?.(chatJid, true);
 
   let hadError = false;
   let outputSentToUser = false;
 
   const output = await runAgent(group, prompt, chatJid, async (result) => {
+    // Any streaming output resets the stall timer and resumes typing
+    lastOutputAt = Date.now();
+    if (!typingActive) {
+      typingActive = true;
+      channel.setTyping?.(chatJid, true)?.catch(() => {});
+    }
+
     // Streaming output callback — called for each agent result
     if (result.result) {
       const raw =
@@ -435,7 +456,7 @@ async function startMessageLoop(): Promise<void> {
     } catch (err) {
       logger.error({ err }, 'Error in message loop');
     }
-    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+    await waitForMessage(POLL_INTERVAL);
   }
 }
 

src/message-signal.ts

@@ -0,0 +1,32 @@
+import { EventEmitter } from 'events';
+
+/**
+ * Lightweight signal to wake the message loop immediately when a
+ * channel receives a message, instead of waiting for the next poll tick.
+ */
+const emitter = new EventEmitter();
+emitter.setMaxListeners(0);
+
+/** Channels call this after storing a message. */
+export function signalNewMessage(): void {
+  emitter.emit('message');
+}
+
+/**
+ * Returns a promise that resolves when either:
+ * - a new message signal fires, or
+ * - the timeout expires (fallback poll interval)
+ */
+export function waitForMessage(timeoutMs: number): Promise<void> {
+  return new Promise((resolve) => {
+    const onMessage = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      emitter.removeListener('message', onMessage);
+      resolve();
+    }, timeoutMs);
+    emitter.once('message', onMessage);
+  });
+}