claude-notification-plugin 1.1.105 → 1.1.108

package/.claude-plugin/plugin.json

@@ -1,20 +1,20 @@
-{
-  "name": "claude-notification-plugin",
-  "version": "1.1.105",
-  "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
-  "author": {
-    "name": "Viacheslav Makarov",
-    "email": "npmjs@bazilio.ru"
-  },
-  "homepage": "https://github.com/Bazilio-san/claude-notification-plugin#readme",
-  "repository": "https://github.com/Bazilio-san/claude-notification-plugin",
-  "license": "MIT",
-  "keywords": [
-    "notification",
-    "telegram",
-    "windows",
-    "sound",
-    "voice",
-    "hooks"
-  ]
-}
+{
+  "name": "claude-notification-plugin",
+  "version": "1.1.108",
+  "description": "Telegram listener daemon + Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
+  "author": {
+    "name": "Viacheslav Makarov",
+    "email": "npmjs@bazilio.ru"
+  },
+  "homepage": "https://github.com/Bazilio-san/claude-notification-plugin#readme",
+  "repository": "https://github.com/Bazilio-san/claude-notification-plugin",
+  "license": "MIT",
+  "keywords": [
+    "notification",
+    "telegram",
+    "windows",
+    "sound",
+    "voice",
+    "hooks"
+  ]
+}

package/README.md

@@ -2,11 +2,23 @@
 
 **Send a message in Telegram, and the task starts running on your PC.**
 
-Cross-platform notifications for Claude Code task completion.
-Sends alerts to Telegram and desktop (Windows, macOS, Linux) when Claude finishes working.
-
-
-## Features
+Cross-platform notifications for Claude Code task completion.
+Sends alerts to Telegram and desktop (Windows, macOS, Linux) when Claude finishes working.
+
+## Start Here (Listener)
+
+If you want Telegram-first remote control, start with the Listener daemon:
+
+```bash
+claude-notify listener setup
+claude-notify listener start
+claude-notify listener status
+```
+
+Deep internals and troubleshooting: [Detailed Guide](listener/LISTENER-DETAILED.md)
+
+
+## Features
 
 - **[Telegram Listener](#telegram-listener)** — your remote control for Claude (supports worktrees)
 - Telegram bot messages with auto-delete
@@ -118,7 +130,7 @@ ENV: `CLAUDE_NOTIFY_TELEGRAM_TOKEN`
 **telegram.chatId** — Chat ID to send messages to.
 ENV: `CLAUDE_NOTIFY_TELEGRAM_CHAT_ID`
 
-**telegram.deleteAfterHours** — Auto-delete old Telegram messages after N hours. `0` to disable. Default: **24**
+**telegram.deleteAfterHours** — Auto-delete old Telegram messages after N hours (applies to notifier and listener bot messages). `0` to disable. Default: **24**
 
 **telegram.includeLastCcMessageInTelegram** — Append Claude's last message to the notification (truncated to 3500 chars). Default: **true**
 ENV: `CLAUDE_NOTIFY_INCLUDE_LAST_CC_MESSAGE_IN_TELEGRAM`
@@ -219,14 +231,16 @@ fix the login bug                     → runs in "default" project
 &api/feature/auth implement OAuth2    → runs in a worktree (auto-created)
 ```
 
-The bot replies with status and results:
+The bot replies with status and results:
 
 ```
 ⏳ [&api] Running: add pagination to GET /users
 ...
-✅ [&api] Done: add pagination to GET /users
-<claude's output>
-```
+✅ [&api] Done: add pagination to GET /users
+<claude's output>
+```
+
+If Claude returns a temporary API failure (`StopFailure`, e.g. `529 overloaded`), the listener saves the reported session ID and the next task for the same target auto-resumes it.
 
 ### 4. Manage the daemon
 

package/bin/cli.js

@@ -32,10 +32,11 @@ switch (command) {
       console.log(`Usage: claude-notify <command> [options]
 
 Commands:
+  listener <action>    Manage the Telegram Listener daemon
+                       Actions: start, stop, status, logs, restart
   install              Setup plugin registration, Telegram config, hooks
   uninstall            Remove plugin, hooks, config, CLI wrappers
-  listener <action>    Manage the Telegram Listener daemon
-                       Actions: start, stop, status, logs, restart`);
+`);
       process.exit(command ? 1 : 0);
     }
 }

package/bin/install.js

@@ -737,11 +737,16 @@ Plugin hooks (via hooks/hooks.json):
 Config: ${CONFIG_PATH}
 ${telegramStatus}${platformTip}
 
-Log: ${INSTALL_LOG_PATH}
-
-To uninstall:  claude-notify uninstall
-
-To disable per project, add to .claude/settings.local.json: { "env": { "CLAUDE_NOTIFY_DISABLE": "1" } }`);
+Log: ${INSTALL_LOG_PATH}
+
+Listener quick start:
+  claude-notify listener setup
+  claude-notify listener start
+  claude-notify listener status
+
+To uninstall:  claude-notify uninstall
+
+To disable per project, add to .claude/settings.local.json: { "env": { "CLAUDE_NOTIFY_DISABLE": "1" } }`);
 
   closeLog();
 }

package/commit-sha

@@ -1 +1 @@
-172c80dbeb3e3f935e6e96b28d23b7ee40ba8858
+0daaa9a945591246c6de6c117d9cf9b4add7ab25

package/listener/LISTENER-DETAILED.md

@@ -3,7 +3,7 @@
 Telegram Listener is a background daemon that receives tasks from a Telegram chat
 and executes them on your machine via an interactive Claude Code PTY session. The result is sent back to Telegram.
 
-**[Quick Start here](../LISTENER.md)**
+**[Quick Start here](../README.md#telegram-listener)**
 
 # Detailed Guide
 

package/listener/listener.js

@@ -133,7 +133,9 @@ const resumeLastSessionEnabled = listenerConfig.resumeLastSession !== false; //
 const sessionsListLimit = listenerConfig.sessionsListLimit || 5;
 const sessionWorkingThresholdSec = listenerConfig.sessionWorkingThresholdSec || 2;
 
-const poller = new TelegramPoller(token, chatId, logger);
+const poller = new TelegramPoller(token, chatId, logger, {
+  deleteAfterHours: config.telegram?.deleteAfterHours,
+});
 const queue = new WorkQueue(
   logger,
   listenerConfig.maxQueuePerWorkDir || 10,
@@ -304,7 +306,14 @@ async function notifyTaskCompletion (workDir, task, kind, payload = {}) {
   let header;
   let queueResult;
   if (kind === 'error') {
-    header = `❌  <code>${label}</code>\nError`;
+    const resumeSid = payload.resumeSessionId || payload.sessionId || null;
+    if (resumeSid) {
+      setStoredSessionId(workDir, resumeSid);
+    }
+    const resumeHint = resumeSid
+      ? `\nSaved session: <code>${resumeSid}</code>\nNext task for this target will auto-resume it.`
+      : '';
+    header = `❌  <code>${label}</code>\nError${resumeHint}`;
     queueResult = `ERROR: ${payload.errorMsg}`;
   } else if (kind === 'timeout') {
     const reason = payload.reason || `no activity for ${payload.timeoutMin} min`;
@@ -413,7 +422,17 @@ async function notifyTaskCompletion (workDir, task, kind, payload = {}) {
 }
 
 runner.on('complete', (workDir, task, result) => notifyTaskCompletion(workDir, task, 'complete', result));
-runner.on('error', (workDir, task, errorMsg) => notifyTaskCompletion(workDir, task, 'error', { errorMsg }));
+runner.on('error', (workDir, task, errorData) => {
+  if (typeof errorData === 'string') {
+    notifyTaskCompletion(workDir, task, 'error', { errorMsg: errorData });
+    return;
+  }
+  notifyTaskCompletion(workDir, task, 'error', {
+    errorMsg: errorData?.message || 'Unknown error',
+    sessionId: errorData?.sessionId || null,
+    resumeSessionId: errorData?.resumeSessionId || null,
+  });
+});
 runner.on('timeout', (workDir, task) => notifyTaskCompletion(workDir, task, 'timeout', {
   timeoutMin: Math.round(taskTimeout / 60000),
 }));

package/listener/pty-runner.js

@@ -154,6 +154,8 @@ export class PtyRunner extends EventEmitter {
       } else if (type === 'error') {
         // StopFailure — emit error, abort task
         this._unlinkSafe(filePath);
+        const errorSignalSessionId = marker.sessionId
+          || (f.startsWith('err_') ? f.slice(4, -5) : null);
         for (const [workDir, session] of this.sessions) {
           if (session.state === 'busy' && this._normalizePath(session.workDir) === this._normalizePath(cwd)) {
             if (session._pendingId && this.pendingMarkers.has(session._pendingId)) {
@@ -164,11 +166,22 @@ export class PtyRunner extends EventEmitter {
             session.currentTask = null;
             this._destroyPty(workDir);
             const errorMsg = `API error: ${marker.error}${marker.errorDetails ? ' — ' + marker.errorDetails : ''}`;
+            const resumeMatch = (marker.errorDetails || marker.lastAssistantMessage || '')
+              .match(/(?:^|\s)--resume\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+            const resumeSessionId = resumeMatch?.[1] || null;
             this.logger.error(`Hook signal: ${errorMsg} in ${workDir}`);
             if (this.taskLogger) {
               this.taskLogger.logAnswer(task?.project || 'unknown', task?.branch || 'main', errorMsg, 1);
             }
-            this.emit('error', workDir, task, errorMsg);
+            this.emit('error', workDir, task, {
+              message: errorMsg,
+              sessionId: errorSignalSessionId && errorSignalSessionId !== 'unknown'
+                ? errorSignalSessionId
+                : null,
+              resumeSessionId,
+              errorType: marker.error || 'unknown',
+              errorDetails: marker.errorDetails || '',
+            });
             break;
           }
         }

package/listener/telegram-poller.js

@@ -7,17 +7,22 @@ const MAX_MESSAGE_LENGTH = 4096;
 // of looping silently.
 const MAX_CONSECUTIVE_409 = 8;
 
-export class TelegramPoller {
-  constructor (token, chatId, logger) {
-    this.token = token;
-    this.chatId = String(chatId);
-    this.logger = logger;
-    this.baseUrl = `https://api.telegram.org/bot${token}`;
-    this.offset = 0;
-    this._errorBackoff = 0; // current backoff in ms (0 = no backoff)
-    this._consecutiveErrors = 0;
-    this._consecutive409 = 0;
-  }
+export class TelegramPoller {
+  constructor (token, chatId, logger, options = {}) {
+    this.token = token;
+    this.chatId = String(chatId);
+    this.logger = logger;
+    this.baseUrl = `https://api.telegram.org/bot${token}`;
+    this.offset = 0;
+    this._errorBackoff = 0; // current backoff in ms (0 = no backoff)
+    this._consecutiveErrors = 0;
+    this._consecutive409 = 0;
+    const deleteAfterHours = Number(options.deleteAfterHours);
+    this._deleteAfterMs = Number.isFinite(deleteAfterHours) && deleteAfterHours > 0
+      ? deleteAfterHours * 3600_000
+      : 0;
+    this._sentMessages = [];
+  }
 
   async flush () {
     try {
@@ -153,9 +158,12 @@ export class TelegramPoller {
         body: JSON.stringify({ ...base, parse_mode: 'HTML' }),
       });
       let data = await res.json();
-      if (data.ok) {
-        return data.result.message_id;
-      }
+      if (data.ok) {
+        const messageId = data.result.message_id;
+        this._trackSentMessage(messageId);
+        await this._cleanupOldMessages();
+        return messageId;
+      }
       const htmlErr = data.description || `error_code ${data.error_code}`;
       // Retry without HTML parse mode (covers entity-parsing errors)
       res = await fetch(`${this.baseUrl}/sendMessage`, {
@@ -164,10 +172,13 @@ export class TelegramPoller {
         body: JSON.stringify(base),
       });
       data = await res.json();
-      if (data.ok) {
-        this.logger.warn(`sendMessage: HTML failed (${htmlErr}), plain succeeded`);
-        return data.result.message_id;
-      }
+      if (data.ok) {
+        this.logger.warn(`sendMessage: HTML failed (${htmlErr}), plain succeeded`);
+        const messageId = data.result.message_id;
+        this._trackSentMessage(messageId);
+        await this._cleanupOldMessages();
+        return messageId;
+      }
       this.logger.error(`sendMessage failed: HTML=${htmlErr}, plain=${data.description || data.error_code}`);
       return null;
     } catch (err) {
@@ -262,23 +273,57 @@ export class TelegramPoller {
     }
   }
 
-  async sendDocument (buffer, filename, caption) {
-    try {
-      const formData = new FormData();
-      formData.append('chat_id', this.chatId);
-      formData.append('document', new Blob([buffer]), filename);
-      if (caption) {
-        formData.append('caption', caption.slice(0, 1024));
-      }
-      await fetch(`${this.baseUrl}/sendDocument`, {
-        method: 'POST',
-        body: formData,
-      });
-    } catch (err) {
-      this.logger.error(`sendDocument error: ${err.message}`);
-    }
-  }
-}
+  async sendDocument (buffer, filename, caption) {
+    try {
+      const formData = new FormData();
+      formData.append('chat_id', this.chatId);
+      formData.append('document', new Blob([buffer]), filename);
+      if (caption) {
+        formData.append('caption', caption.slice(0, 1024));
+      }
+      const res = await fetch(`${this.baseUrl}/sendDocument`, {
+        method: 'POST',
+        body: formData,
+      });
+      const data = await res.json();
+      if (data.ok && data.result?.message_id) {
+        this._trackSentMessage(data.result.message_id);
+        await this._cleanupOldMessages();
+      }
+    } catch (err) {
+      this.logger.error(`sendDocument error: ${err.message}`);
+    }
+  }
+
+  _trackSentMessage (messageId) {
+    if (!messageId || this._deleteAfterMs <= 0) {
+      return;
+    }
+    this._sentMessages.push({
+      id: messageId,
+      ts: Date.now(),
+    });
+    if (this._sentMessages.length > 1000) {
+      this._sentMessages = this._sentMessages.slice(-500);
+    }
+  }
+
+  async _cleanupOldMessages () {
+    if (this._deleteAfterMs <= 0 || this._sentMessages.length === 0) {
+      return;
+    }
+    const now = Date.now();
+    const keep = [];
+    for (const msg of this._sentMessages) {
+      if (now - msg.ts > this._deleteAfterMs) {
+        await this.deleteMessage(msg.id);
+      } else {
+        keep.push(msg);
+      }
+    }
+    this._sentMessages = keep;
+  }
+}
 
 function escapeHtml (text) {
   return text

package/notifier/notifier.js

@@ -214,15 +214,16 @@ function writePtySignalFile (event) {
   });
 }
 
-function writeErrorSignalFile (event) {
-  const sessionId = event.session_id || 'unknown';
-  writeSignalFile(`err_${sessionId}.json`, {
-    type: 'error',
-    cwd: event.cwd || process.cwd(),
-    error: event.error || 'unknown',
-    errorDetails: event.error_details || '',
-    lastAssistantMessage: event.last_assistant_message || '',
-    timestamp: Date.now(),
+function writeErrorSignalFile (event) {
+  const sessionId = event.session_id || 'unknown';
+  writeSignalFile(`err_${sessionId}.json`, {
+    type: 'error',
+    sessionId,
+    cwd: event.cwd || process.cwd(),
+    error: event.error || 'unknown',
+    errorDetails: event.error_details || '',
+    lastAssistantMessage: event.last_assistant_message || '',
+    timestamp: Date.now(),
   });
 }
 
@@ -413,8 +414,11 @@ async function sendTelegram (config, state) {
   }
 
   // Delete old messages
-  const maxAge = (config.telegram.deleteAfterHours || 24) * 3600_000;
-  if (state.sentMessages?.length) {
+  const deleteAfter = Number(config.telegram.deleteAfterHours);
+  const maxAge = Number.isFinite(deleteAfter) && deleteAfter > 0
+    ? deleteAfter * 3600_000
+    : 0;
+  if (maxAge > 0 && state.sentMessages?.length) {
     const now = Date.now();
     const keep = [];
     for (const msg of state.sentMessages) {

package/package.json

@@ -1,66 +1,69 @@
-{
-  "name": "claude-notification-plugin",
-  "productName": "claude-notification-plugin",
-  "version": "1.1.105",
-  "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
-  "type": "module",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "files": [
-    ".claude-plugin/",
-    "bin/",
-    "claude_img/claude.png",
-    "hooks/",
-    "listener/",
-    "notifier/",
-    "commit-sha",
-    "README.md",
-    "LICENSE"
-  ],
-  "bin": {
-    "claude-notify": "bin/cli.js"
-  },
-  "scripts": {
-    "prepack": "git rev-parse HEAD > commit-sha",
-    "postinstall": "node bin/install.js",
-    "lint": "eslint .",
-    "lint:fix": "eslint --fix .",
-    "listener:restart": "claude-notify listener restart",
-    "listener:stop": "claude-notify listener stop",
-    "listener:start": "claude-notify listener start",
-    "listener:status": "claude-notify listener status"
-  },
-  "keywords": [
-    "claude",
-    "claude-code",
-    "notifications",
-    "telegram",
-    "hooks",
-    "macos",
-    "linux",
-    "cross-platform"
-  ],
-  "author": {
-    "name": "Viacheslav Makarov",
-    "email": "npmjs@bazilio.ru"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Bazilio-san/claude-notification-plugin.git"
-  },
-  "homepage": "https://github.com/Bazilio-san/claude-notification-plugin#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@xterm/headless": "^6.0.0",
-    "node-notifier": "^10.0.1",
-    "node-pty": "^1.1.0"
-  },
-  "devDependencies": {
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-unused-imports": "^4.4.1"
-  }
-}
+{
+  "name": "claude-notification-plugin",
+  "productName": "claude-notification-plugin",
+  "version": "1.1.108",
+  "description": "Telegram listener daemon + Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    ".claude-plugin/",
+    "bin/",
+    "claude_img/claude.png",
+    "hooks/",
+    "listener/",
+    "notifier/",
+    "commit-sha",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "claude-notify": "bin/cli.js"
+  },
+  "scripts": {
+    "prepack": "git rev-parse HEAD > commit-sha",
+    "postinstall": "node bin/install.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "listener:restart": "claude-notify listener restart",
+    "listener:stop": "claude-notify listener stop",
+    "listener:start": "claude-notify listener start",
+    "listener:status": "claude-notify listener status",
+    "agents:link": "node scripts/claude-2-agents-symlink.js setup",
+    "agents:link:status": "node scripts/claude-2-agents-symlink.js status",
+    "agents:link:remove": "node scripts/claude-2-agents-symlink.js remove"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "notifications",
+    "telegram",
+    "hooks",
+    "macos",
+    "linux",
+    "cross-platform"
+  ],
+  "author": {
+    "name": "Viacheslav Makarov",
+    "email": "npmjs@bazilio.ru"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bazilio-san/claude-notification-plugin.git"
+  },
+  "homepage": "https://github.com/Bazilio-san/claude-notification-plugin#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@xterm/headless": "^6.0.0",
+    "node-notifier": "^10.0.1",
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-unused-imports": "^4.4.1"
+  }
+}