Add /reset command to force-kill stalled agents from Telegram

Type /reset in any registered chat to kill a stuck agent process.
Next message spawns a fresh one. No SSH needed.

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

Author: ziggy

README.md

@@ -136,6 +136,18 @@ systemctl --user start ghostclaw
 systemctl --user restart ghostclaw
 ```
 
+## Telegram commands
+
+These work in any registered Telegram chat:
+
+| Command | What it does |
+|---------|-------------|
+| `/reset` | Force-kills a stalled agent. Next message starts fresh. |
+| `/ping` | Check if the bot is online. |
+| `/chatid` | Show the chat's registration ID. |
+
+`/reset` is the one you'll use most — if the bot seems stuck or unresponsive, type `/reset` and send another message.
+
 ## Updating
 
 ```

groups/global/CLAUDE.md

@@ -29,6 +29,10 @@ 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.
 
+### If you're stalled
+
+If the user types `/reset` in Telegram, your process gets force-killed and a fresh agent spawns on the next message. This is normal — don't try to prevent it.
+
 ### Internal thoughts
 
 If part of your output is internal reasoning rather than something for the user, wrap it in `<internal>` tags:

src/channels/telegram.ts

@@ -1,4 +1,6 @@
 import { Bot, InputFile } from 'grammy';
+import path from 'path';
+import fs from 'fs';
 
 import { ASSISTANT_NAME, TRIGGER_PATTERN } from '../config.js';
 import { logger } from '../logger.js';
@@ -16,6 +18,7 @@ export interface TelegramChannelOpts {
   onMessage: OnInboundMessage;
   onChatMetadata: OnChatMetadata;
   registeredGroups: () => Record<string, RegisteredGroup>;
+  onReset?: (chatJid: string) => boolean;
 }
 
 export class TelegramChannel implements Channel {
@@ -53,6 +56,22 @@ export class TelegramChannel implements Channel {
       ctx.reply(`${ASSISTANT_NAME} is online.`);
     });
 
+    // Command to force-kill a stalled agent and start fresh
+    this.bot.command('reset', (ctx) => {
+      const chatJid = `tg:${ctx.chat.id}`;
+      const group = this.opts.registeredGroups()[chatJid];
+      if (!group) {
+        ctx.reply('Not a registered chat.');
+        return;
+      }
+      const killed = this.opts.onReset?.(chatJid) ?? false;
+      if (killed) {
+        ctx.reply('Reset. Agent killed — send me something to start fresh.');
+      } else {
+        ctx.reply('Nothing running. Send me something to start.');
+      }
+    });
+
     this.bot.on('message:text', async (ctx) => {
       // Skip commands
       if (ctx.message.text.startsWith('/')) return;
@@ -168,7 +187,47 @@ export class TelegramChannel implements Channel {
       signalNewMessage();
     };
 
-    this.bot.on('message:photo', (ctx) => storeNonText(ctx, '[Photo]'));
+    this.bot.on('message:photo', async (ctx) => {
+      const chatJid = `tg:${ctx.chat.id}`;
+      const group = this.opts.registeredGroups()[chatJid];
+
+      // Download and save photo
+      let placeholder = '[Photo]';
+      try {
+        const photos = ctx.message.photo;
+        const largestPhoto = photos[photos.length - 1]; // Get highest resolution
+        const file = await ctx.api.getFile(largestPhoto.file_id);
+        const url = `https://api.telegram.org/file/bot${this.botToken}/${file.file_path}`;
+
+        // Create media directory if needed
+        const mediaDir = path.join(process.cwd(), 'data', 'telegram-media');
+        await fs.promises.mkdir(mediaDir, { recursive: true });
+
+        // Download photo
+        const resp = await fetch(url);
+        if (resp.ok) {
+          const buffer = Buffer.from(await resp.arrayBuffer());
+          const timestamp = Date.now();
+          const filename = `photo_${chatJid.replace(':', '_')}_${timestamp}.jpg`;
+          const filepath = path.join(mediaDir, filename);
+          await fs.promises.writeFile(filepath, buffer);
+
+          placeholder = `[Photo: ${filepath}]`;
+          logger.info({ chatJid, filepath, bytes: buffer.length }, 'Downloaded Telegram photo');
+
+          // Also save to Desktop for easy access
+          if (chatJid === 'tg:414798121') { // Main chat
+            const desktopPath = path.join(process.env.HOME || '', 'Desktop', 'latest-telegram-photo.jpg');
+            await fs.promises.writeFile(desktopPath, buffer);
+            logger.info({ desktopPath }, 'Saved photo to Desktop');
+          }
+        }
+      } catch (err) {
+        logger.error({ err }, 'Telegram photo download error');
+      }
+
+      storeNonText(ctx, placeholder);
+    });
     this.bot.on('message:video', (ctx) => storeNonText(ctx, '[Video]'));
     this.bot.on('message:voice', async (ctx) => {
       const chatJid = `tg:${ctx.chat.id}`;

src/group-queue.ts

@@ -207,6 +207,19 @@ export class GroupQueue {
     }
   }
 
+  /**
+   * Force-kill the active agent process for a group.
+   * Returns true if a process was killed, false if nothing was running.
+   */
+  killAgent(groupJid: string): boolean {
+    const state = this.getGroup(groupJid);
+    if (!state.process || state.process.killed) return false;
+
+    logger.info({ groupJid }, 'Force-killing agent process (/reset)');
+    state.process.kill('SIGKILL');
+    return true;
+  }
+
   private async runForGroup(
     groupJid: string,
     reason: 'messages' | 'drain',

src/index.ts

@@ -575,6 +575,7 @@ async function main(): Promise<void> {
       isGroup?: boolean,
     ) => storeChatMetadata(chatJid, timestamp, name, channel, isGroup),
     registeredGroups: () => registeredGroups,
+    onReset: (chatJid: string) => queue.killAgent(chatJid),
   };
 
   // Create and connect channels