claude-notification-plugin 1.1.89 → 1.1.91

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-notification-plugin",
-  "version": "1.1.89",
+  "version": "1.1.91",
   "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
   "author": {
     "name": "Viacheslav Makarov",

package/README.md

@@ -90,6 +90,9 @@ Config file: `~/.claude/claude-notify.config.json`
       }
     },
     "continueSession": true,
+    "resumeLastSession": true,
+    "sessionsListLimit": 5,
+    "sessionWorkingThresholdSec": 2,
     "worktreeBaseDir": "abs-path-to-worktrees-root",
     "autoCreateWorktree": true,
     "taskTimeoutMinutes": 30,
@@ -259,6 +262,9 @@ Projects are referenced with the `&` prefix (e.g. `&api`, `&api/branch`).
 | `/worktree &project/branch`    | Create a worktree                    |
 | `/rmworktree &project/branch`  | Remove a worktree                    |
 | `/pty [&project[/branch]]`     | PTY session diagnostics (state, buffer, output) |
+| `/sessions [&project[/branch]]` | List recent CC sessions in the project's `~/.claude/projects/<dir>/`, with status (free / alive idle / working) and a Resume / Kill & Resume button per row |
+| `/resume &project[/branch] <sessionId>` | Mark the next task to resume `<sessionId>` (`claude --resume <id>`) |
+| `/kresume &project[/branch] <sessionId>` | Same, but kill the process holding the JSONL first |
 | `/history`                     | Recent task history                  |
 | `/stop`                        | Stop the listener                    |
 | `/start`                       | Show help with inline buttons        |
@@ -321,7 +327,10 @@ the same path cannot be registered twice under different aliases.
 |----------------------|-----------------------|----------------------------------------------------------------------------------------|
 | `projects`           | (required)            | Map of projects: `alias → { path }`                                                    |
 | `claudeArgs`         | `[]`                  | Extra CLI args for Claude (e.g. `["--permission-mode", "auto"]`)                       |
-| `continueSession`    | `true`                | Continue previous session context (`--continue` flag). Claude remembers previous tasks |
+| `continueSession`    | `true`                | Keep the PTY alive between Telegram tasks so subsequent tasks reuse the same live Claude session |
+| `resumeLastSession`  | `true`                | When spawning a fresh PTY, add `--continue` so Claude picks up the most recent JSONL in the workDir (bridges laptop CC session ↔ Telegram listener) |
+| `sessionsListLimit`  | `5`                   | How many most-recent sessions `/sessions` shows                                        |
+| `sessionWorkingThresholdSec` | `2`           | A locked JSONL with mtime ≤ this many seconds is considered actively writing (status `working`, resume disabled) |
 | `worktreeBaseDir`    | `~/.claude/worktrees` | Where auto-created worktrees are stored                                                |
 | `autoCreateWorktree` | `true`                | Auto-create worktrees for unknown branches                                             |
 | `taskTimeoutMinutes` | `30`                  | Max task execution time (force-stopped when exceeded)                                  |

package/commit-sha

@@ -1 +1 @@
-0bd678de06dbe99bc95ce19ee702c72549a29536
+01bee72db3baded113d020fadd1a94fb262fddc1

package/listener/file-locks.js

@@ -0,0 +1,222 @@
+import { spawn } from 'child_process';
+
+// PowerShell + Win32 Restart Manager API. Compiles a tiny C# helper on first
+// run (~1–2s cold start) and reuses it for the life of the process. Reads
+// file paths from stdin (one per line, UTF-8) — avoids argv escaping issues
+// for paths with spaces, quotes, or non-ASCII characters.
+const PS_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$OutputEncoding = [System.Text.Encoding]::UTF8
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+[Console]::InputEncoding  = [System.Text.Encoding]::UTF8
+$src = @'
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+namespace ResMgr {
+  public static class Locker {
+    [StructLayout(LayoutKind.Sequential)]
+    struct RM_UNIQUE_PROCESS { public int dwProcessId; public System.Runtime.InteropServices.ComTypes.FILETIME t; }
+    const int N_APP = 256; const int N_SVC = 64;
+    [StructLayout(LayoutKind.Sequential, CharSet=CharSet.Unicode)]
+    struct RM_PROCESS_INFO {
+      public RM_UNIQUE_PROCESS Process;
+      [MarshalAs(UnmanagedType.ByValTStr, SizeConst=N_APP)] public string strAppName;
+      [MarshalAs(UnmanagedType.ByValTStr, SizeConst=N_SVC)] public string strServiceShortName;
+      public uint ApplicationType; public uint AppStatus; public uint TSSessionId;
+      [MarshalAs(UnmanagedType.Bool)] public bool bRestartable;
+    }
+    [DllImport("rstrtmgr.dll", CharSet=CharSet.Unicode)]
+    static extern int RmStartSession(out uint h, int f, string k);
+    [DllImport("rstrtmgr.dll")] static extern int RmEndSession(uint h);
+    [DllImport("rstrtmgr.dll", CharSet=CharSet.Unicode)]
+    static extern int RmRegisterResources(uint h, uint nF, string[] f, uint nA, [In] RM_UNIQUE_PROCESS[] a, uint nS, string[] s);
+    [DllImport("rstrtmgr.dll")]
+    static extern int RmGetList(uint h, out uint need, ref uint cnt, [In, Out] RM_PROCESS_INFO[] info, ref uint reason);
+    public static List<int> WhoIsLocking(string path) {
+      var pids = new List<int>();
+      uint handle;
+      if (RmStartSession(out handle, 0, Guid.NewGuid().ToString()) != 0) return pids;
+      try {
+        if (RmRegisterResources(handle, 1, new []{path}, 0, null, 0, null) != 0) return pids;
+        uint need = 0, cnt = 0, reason = 0;
+        int res = RmGetList(handle, out need, ref cnt, null, ref reason);
+        if (res == 234 && need > 0) {
+          var info = new RM_PROCESS_INFO[need]; cnt = need;
+          if (RmGetList(handle, out need, ref cnt, info, ref reason) == 0) {
+            for (int i = 0; i < cnt; i++) pids.Add(info[i].Process.dwProcessId);
+          }
+        }
+      } finally { RmEndSession(handle); }
+      return pids;
+    }
+  }
+}
+'@
+Add-Type -TypeDefinition $src -Language CSharp -ErrorAction Stop | Out-Null
+$line = $null
+while (($line = [Console]::In.ReadLine()) -ne $null) {
+  if ($line -eq '') { continue }
+  try {
+    $pids = [ResMgr.Locker]::WhoIsLocking($line)
+    Write-Output ("OK\`t" + $line + "\`t" + ($pids -join ','))
+  } catch {
+    Write-Output ("ERR\`t" + $line + "\`t" + $_.Exception.Message)
+  }
+}
+`;
+
+/**
+ * Find PIDs of processes that have an open handle to each given file path.
+ * Returns a Map<filePath, number[]>. Paths absent from the map mean "no
+ * detection (tool unavailable or error)" — callers should treat as unknown,
+ * not as "free".
+ *
+ * On Windows, spawns a single PowerShell with the Restart Manager API and
+ * feeds all paths via stdin to amortize PowerShell's ~1–2s cold start.
+ * On Linux/macOS, uses `lsof -F p` for the same.
+ */
+export async function findLocking (filePaths, logger) {
+  if (!filePaths || filePaths.length === 0) {
+    return new Map();
+  }
+  if (process.platform === 'win32') {
+    return findLockingWindows(filePaths, logger);
+  }
+  return findLockingUnix(filePaths, logger);
+}
+
+function findLockingWindows (filePaths, logger) {
+  return new Promise((resolve) => {
+    const result = new Map();
+    let proc;
+    try {
+      proc = spawn('powershell.exe', [
+        '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+        '-Command', PS_SCRIPT,
+      ], { windowsHide: true });
+    } catch (err) {
+      logger?.warn(`file-locks: spawn powershell failed: ${err.message}`);
+      resolve(result);
+      return;
+    }
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      for (const line of stdout.split(/\r?\n/)) {
+        if (!line.startsWith('OK\t')) {
+          continue;
+        }
+        const parts = line.split('\t');
+        const filePath = parts[1];
+        const pids = (parts[2] || '').split(',').map(Number).filter(n => Number.isInteger(n) && n > 0);
+        result.set(filePath, pids);
+      }
+      if (stderr.trim() && logger) {
+        logger.warn(`file-locks: powershell stderr: ${stderr.trim().slice(0, 200)}`);
+      }
+      resolve(result);
+    };
+
+    proc.stdout.on('data', (d) => {
+      stdout += d.toString('utf-8'); 
+    });
+    proc.stderr.on('data', (d) => {
+      stderr += d.toString('utf-8'); 
+    });
+    proc.on('close', finish);
+    proc.on('error', (err) => {
+      logger?.warn(`file-locks: powershell error: ${err.message}`);
+      finish();
+    });
+
+    const timer = setTimeout(() => {
+      try {
+        proc.kill(); 
+      } catch { /* ignore */ }
+      logger?.warn('file-locks: powershell timed out (15s)');
+      finish();
+    }, 15_000);
+    proc.on('close', () => clearTimeout(timer));
+
+    try {
+      proc.stdin.write(filePaths.join('\n') + '\n', 'utf-8');
+      proc.stdin.end();
+    } catch (err) {
+      logger?.warn(`file-locks: stdin write failed: ${err.message}`);
+      finish();
+    }
+  });
+}
+
+function findLockingUnix (filePaths, logger) {
+  return new Promise((resolve) => {
+    const result = new Map();
+    let proc;
+    try {
+      proc = spawn('lsof', ['-F', 'pn', '--', ...filePaths]);
+    } catch (err) {
+      logger?.warn(`file-locks: spawn lsof failed: ${err.message}`);
+      resolve(result);
+      return;
+    }
+    let stdout = '';
+    proc.stdout.on('data', (d) => {
+      stdout += d.toString('utf-8'); 
+    });
+    proc.on('error', () => resolve(result));
+    proc.on('close', () => {
+      // lsof -F pn: lines starting with `p` are PIDs, `n` are file names.
+      // Parse pairs: each `n<path>` belongs to the most recent `p<pid>`.
+      let currentPid = 0;
+      const pathSet = new Set(filePaths);
+      for (const line of stdout.split('\n')) {
+        if (line.startsWith('p')) {
+          currentPid = parseInt(line.slice(1), 10) || 0;
+        } else if (line.startsWith('n') && currentPid > 0) {
+          const p = line.slice(1);
+          if (pathSet.has(p)) {
+            const arr = result.get(p) || [];
+            if (!arr.includes(currentPid)) {
+              arr.push(currentPid);
+            }
+            result.set(p, arr);
+          }
+        }
+      }
+      resolve(result);
+    });
+  });
+}
+
+/**
+ * Forcefully kill a process by PID. Returns true on success.
+ */
+export async function killPid (pid, logger) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  if (process.platform === 'win32') {
+    return new Promise((resolve) => {
+      const proc = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true });
+      proc.on('close', (code) => resolve(code === 0));
+      proc.on('error', (err) => {
+        logger?.warn(`file-locks: taskkill error: ${err.message}`);
+        resolve(false);
+      });
+    });
+  }
+  try {
+    process.kill(pid, 'SIGKILL');
+    return true;
+  } catch (err) {
+    logger?.warn(`file-locks: kill ${pid} failed: ${err.message}`);
+    return false;
+  }
+}

package/listener/listener.js

@@ -22,7 +22,9 @@ import {
   normalizeForCompare,
   loadSeenProjects,
 } from '../bin/constants.js';
-import { JsonlReader, resolveJsonlPath, resolveJsonlByMtime } from './jsonl-reader.js';
+import { JsonlReader, resolveJsonlPath, resolveJsonlByMtime, cwdToProjectDir } from './jsonl-reader.js';
+import { listSessions } from './session-list.js';
+import { findLocking, killPid } from './file-locks.js';
 
 // ----------------------
 // CRASH PROTECTION
@@ -122,6 +124,9 @@ const globalClaudeArgs = listenerConfig.claudeArgs || [];
 const continueSessionEnabled = listenerConfig.continueSession !== false; // default: true
 const taskTimeoutMinutes = listenerConfig.taskTimeoutMinutes || 30;
 const taskTimeout = taskTimeoutMinutes * 60_000;
+const resumeLastSessionEnabled = listenerConfig.resumeLastSession !== false; // default: true
+const sessionsListLimit = listenerConfig.sessionsListLimit || 5;
+const sessionWorkingThresholdSec = listenerConfig.sessionWorkingThresholdSec || 2;
 
 const poller = new TelegramPoller(token, chatId, logger);
 const queue = new WorkQueue(
@@ -147,6 +152,9 @@ const startTime = Date.now();
 const sessions = new Map();
 // WorkDirs that should start a fresh session on next task
 const freshSessionDirs = new Set();
+// WorkDirs with a pending resume request: workDir -> sessionId. Consumed by
+// applyResumeArgs() on the next task, then cleared.
+const pendingResumeBySid = new Map();
 // Live console intervals per workDir
 const liveConsoleTimers = new Map();
 // JSONL readers per workDir (for live console from structured session data)
@@ -218,8 +226,10 @@ async function runWatchdog () {
   }
 }
 
-// 1. Initial watchdog sweep on startup
-runWatchdog();
+// 1. Initial watchdog sweep on startup. Must finish before orphan recovery,
+// otherwise orphan recovery sees the stale active (still set) and re-spawns
+// the killed task while watchdog is still awaiting its Telegram notify.
+await runWatchdog();
 
 // 2. Re-start orphaned active tasks (PTY sessions lost on restart)
 for (const [workDir, entry] of Object.entries(queue.queues)) {
@@ -393,6 +403,52 @@ function getClaudeArgs (projectAlias) {
   return projectArgs.length > 0 ? projectArgs : globalClaudeArgs;
 }
 
+function hasAnyJsonl (workDir) {
+  const dirName = cwdToProjectDir(workDir);
+  const dirPath = path.join(CLAUDE_DIR, 'projects', dirName);
+  try {
+    return fs.readdirSync(dirPath).some(f => f.endsWith('.jsonl'));
+  } catch {
+    return false;
+  }
+}
+
+// Decide whether to add --continue or --resume <id> to claudeArgs for a fresh PTY.
+// A pending /resume <sid> wins over the global resumeLastSession default.
+// If args already contain a resume flag, leave them alone. If reusing an idle
+// PTY, claudeArgs are ignored anyway.
+function applyResumeArgs (claudeArgs, workDir) {
+  if (claudeArgs.includes('--continue') || claudeArgs.includes('--resume')) {
+    return claudeArgs;
+  }
+  if (pendingResumeBySid.has(workDir)) {
+    const sid = pendingResumeBySid.get(workDir);
+    pendingResumeBySid.delete(workDir);
+    return [...claudeArgs, '--resume', sid];
+  }
+  if (resumeLastSessionEnabled && hasAnyJsonl(workDir)) {
+    return [...claudeArgs, '--continue'];
+  }
+  return claudeArgs;
+}
+
+function formatTimeAgo (ms) {
+  const sec = Math.max(0, Math.floor(ms / 1000));
+  if (sec < 60) {
+    return `${sec}s ago`;
+  }
+  const min = Math.floor(sec / 60);
+  if (min < 60) {
+    return `${min}m ago`;
+  }
+  const h = Math.floor(min / 60);
+  if (h < 24) {
+    return `${h}h ago`;
+  }
+  const d = Math.floor(h / 24);
+  return `${d}d ago`;
+}
+
 function shouldContinueSession (workDir) {
   if (!continueSessionEnabled) {
     return false;
@@ -506,7 +562,7 @@ async function startTask (workDir, task) {
       runningMsgId = await poller.sendMessage(runningRaw);
     }
     task.runningMessageId = runningMsgId;
-    const claudeArgs = getClaudeArgs(entry?.project);
+    const claudeArgs = applyResumeArgs(getClaudeArgs(entry?.project), workDir);
     try {
       runner.run(workDir, task, claudeArgs, continueSession);
       queue.markStarted(workDir, task.pid || 0);
@@ -543,7 +599,7 @@ async function startTask (workDir, task) {
 
   task.runningMessageId = runningMsgId;
   startLiveConsole(workDir, runningMsgId, runningFull);
-  const claudeArgs = getClaudeArgs(entry?.project);
+  const claudeArgs = applyResumeArgs(getClaudeArgs(entry?.project), workDir);
   try {
     runner.run(workDir, task, claudeArgs, continueSession);
     queue.markStarted(workDir, task.pid || 0);
@@ -631,6 +687,12 @@ async function handleCommand (cmd, args) {
       return handleHistory();
     case '/pty':
       return handlePty(args);
+    case '/sessions':
+      return handleSessions(args);
+    case '/resume':
+      return handleResumeSession(args, false);
+    case '/kresume':
+      return handleResumeSession(args, true);
     case '/stop':
       return handleStop();
     case '/help':
@@ -1256,6 +1318,144 @@ PTY log: <code>${info.hasLogStream ? 'writing' : 'off'}</code>
 <pre>${escapeHtml(lastLines)}</pre>`;
 }
 
+async function handleSessions (args) {
+  let target = parseTarget(args);
+  if (!target) {
+    const def = getDefaultProject(config);
+    if (!def) {
+      return 'Usage: /sessions &project[/branch]';
+    }
+    target = { project: def, branch: null };
+  }
+  let workDir;
+  try {
+    workDir = worktreeManager.resolveWorkDir(target.project, target.branch);
+  } catch (err) {
+    return `❌ ${escapeHtml(err.message)}`;
+  }
+  const labelTarget = target.branch && target.branch !== 'main' && target.branch !== 'master'
+    ? `&${target.project}/${target.branch}`
+    : `&${target.project}`;
+
+  const items = await listSessions(workDir, {
+    limit: sessionsListLimit,
+    workingThresholdSec: sessionWorkingThresholdSec,
+    logger,
+  });
+  if (items.length === 0) {
+    return `📋 No sessions found for ${escapeHtml(labelTarget)}`;
+  }
+
+  let text = `📋 <b>Sessions for ${escapeHtml(labelTarget)}</b> (${items.length} most recent)`;
+  const buttons = [];
+  let idx = 0;
+  for (const s of items) {
+    idx++;
+    const ago = formatTimeAgo(Date.now() - s.mtime);
+    const sizeKb = s.size / 1024;
+    const sizeStr = sizeKb >= 1024 ? `${(sizeKb / 1024).toFixed(1)} MB` : `${Math.round(sizeKb)} KB`;
+    let icon;
+    let statusLabel;
+    if (s.status === 'working') {
+      icon = '🔴';
+      statusLabel = 'working';
+    } else if (s.status === 'idle') {
+      icon = '🟡';
+      statusLabel = 'alive idle';
+    } else {
+      icon = '🟢';
+      statusLabel = 'free';
+    }
+    const lockInfo = s.lockedBy.length > 0 ? ` · pid ${s.lockedBy.join(',')}` : '';
+    const preview = s.preview ? escapeHtml(s.preview) : '<i>(no user message yet)</i>';
+    text += `\n\n<b>${idx}.</b> ${icon} ${statusLabel} · ${ago} · ${sizeStr}${lockInfo}\n<code>${s.sessionId}</code>\n${preview}`;
+
+    if (s.status === 'working') {
+      // Skip — resuming a file being actively written would corrupt JSONL.
+    } else if (s.status === 'idle') {
+      buttons.push([
+        { text: `${idx}. ⚠️ Kill & Resume`, callback_data: `/kresume ${labelTarget} ${s.sessionId}` },
+      ]);
+    } else {
+      buttons.push([
+        { text: `${idx}. ▶ Resume`, callback_data: `/resume ${labelTarget} ${s.sessionId}` },
+      ]);
+    }
+  }
+
+  if (buttons.length === 0) {
+    return text + '\n\n<i>All sessions are actively in use — cannot resume safely.</i>';
+  }
+  return { text, replyMarkup: { inline_keyboard: buttons } };
+}
+
+async function handleResumeSession (args, kill) {
+  const tokens = (args || '').trim().split(/\s+/).filter(Boolean);
+  const cmdName = kill ? '/kresume' : '/resume';
+  if (tokens.length < 2) {
+    return `Usage: ${cmdName} &project[/branch] &lt;sessionId&gt;`;
+  }
+  const target = parseTarget(tokens[0]);
+  if (!target) {
+    return `Invalid project alias: ${escapeHtml(tokens[0])}`;
+  }
+  const sessionId = tokens[1];
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sessionId)) {
+    return `Invalid session ID: <code>${escapeHtml(sessionId)}</code>`;
+  }
+
+  let workDir;
+  try {
+    workDir = worktreeManager.resolveWorkDir(target.project, target.branch);
+  } catch (err) {
+    return `❌ ${escapeHtml(err.message)}`;
+  }
+  const labelTarget = target.branch && target.branch !== 'main' && target.branch !== 'master'
+    ? `&${target.project}/${target.branch}`
+    : `&${target.project}`;
+
+  const dirName = cwdToProjectDir(workDir);
+  const filePath = path.join(CLAUDE_DIR, 'projects', dirName, `${sessionId}.jsonl`);
+  if (!fs.existsSync(filePath)) {
+    return `Session not found: <code>${escapeHtml(sessionId)}</code>`;
+  }
+
+  let killReport = '';
+  if (kill) {
+    const lockMap = await findLocking([filePath], logger);
+    const pids = lockMap.get(filePath) || [];
+    if (pids.length === 0) {
+      killReport = '\n<i>No active locker found — proceeding with resume.</i>';
+    } else {
+      let killed = 0;
+      for (const pid of pids) {
+        if (await killPid(pid, logger)) {
+          killed++;
+        }
+      }
+      logger.info(`/kresume: killed ${killed}/${pids.length} processes locking ${sessionId}: ${pids.join(',')}`);
+      // Brief settle delay so the OS releases the file handle.
+      await new Promise((r) => setTimeout(r, 500));
+      killReport = `\n<i>Killed ${killed}/${pids.length} process(es): ${pids.join(', ')}</i>`;
+    }
+  }
+
+  // Drop any live PTY in this workDir so the next task spawns a fresh one with --resume.
+  if (runner.isPtyAlive(workDir)) {
+    try {
+      runner.cancel(workDir);
+    } catch (err) {
+      logger.warn(`/resume: cancel PTY failed: ${err.message}`);
+    }
+    stopLiveConsole(workDir);
+    runner.cleanActivitySignal(workDir);
+  }
+  freshSessionDirs.add(workDir);
+  pendingResumeBySid.set(workDir, sessionId);
+
+  return `🔄 ${escapeHtml(labelTarget)}: next task will resume <code>${sessionId.slice(0, 8)}…</code>${killReport}\n\nSend the task as usual:\n<code>${escapeHtml(labelTarget)} your task here</code>`;
+}
+
 function handleHistory () {
   const history = queue.getHistory(10);
   if (history.length === 0) {
@@ -1290,6 +1490,9 @@ const MENU_KEYBOARD = {
     [
       { text: '📜 History', callback_data: '/history' },
       { text: '🖥 PTY', callback_data: '/pty' },
+      { text: '📋 Sessions', callback_data: '/sessions' },
+    ],
+    [
       { text: '🏠 Default', callback_data: '/setdefault' },
     ],
     [
@@ -1318,6 +1521,9 @@ function handleHelp () {
 /worktree &project/branch — create worktree
 /rmworktree &project/branch — remove worktree
 /pty [&project[/branch]] — PTY session diagnostics
+/sessions [&project[/branch]] — list 5 most recent CC sessions with resume buttons
+/resume &project[/branch] &lt;sessionId&gt; — next task resumes the given session
+/kresume &project[/branch] &lt;sessionId&gt; — kill the holder, then resume
 /history — task history
 /stop — stop listener
 /menu — command buttons
@@ -1476,6 +1682,7 @@ async function mainLoop () {
     { command: 'setdefault', description: 'Change default project' },
     { command: 'history', description: 'Recent task history' },
     { command: 'pty', description: 'PTY session diagnostics' },
+    { command: 'sessions', description: 'List recent CC sessions' },
     { command: 'help', description: 'Show all commands' },
     { command: 'stop', description: 'Stop listener' },
   ]);

package/listener/pty-runner.js

@@ -632,6 +632,14 @@ export class PtyRunner extends EventEmitter {
     return session?.state === 'busy';
   }
 
+  /**
+   * Check if a PTY session exists for a workDir (busy or idle).
+   * Used to decide whether to kill before spawning a fresh session for --resume.
+   */
+  isPtyAlive (workDir) {
+    return this.sessions.has(workDir);
+  }
+
   /**
    * Get active task info for a workDir.
    */

package/listener/session-list.js

@@ -0,0 +1,142 @@
+import fs from 'fs';
+import path from 'path';
+import { CLAUDE_DIR } from '../bin/constants.js';
+import { cwdToProjectDir } from './jsonl-reader.js';
+import { findLocking } from './file-locks.js';
+
+const PROJECTS_DIR = path.join(CLAUDE_DIR, 'projects');
+
+const PREVIEW_MAX_LINES = 200;
+const PREVIEW_MAX_CHARS = 120;
+
+/**
+ * List the most recent Claude Code sessions (JSONL files) for a workDir,
+ * with status and a short preview of the first user message.
+ *
+ * Status semantics:
+ *   - working:  file is locked AND mtime within workingThresholdSec
+ *   - idle:     file is locked AND older than workingThresholdSec
+ *   - free:     file is not locked
+ *
+ * @param {string}   workDir              cwd whose project dir to scan
+ * @param {object}   opts
+ * @param {number}   opts.limit                  max sessions to return
+ * @param {number}   opts.workingThresholdSec    mtime ≤ this AND locked → working
+ * @param {object}   opts.logger
+ * @returns {Promise<Array<{sessionId, filePath, mtime, size, status, lockedBy, preview}>>}
+ */
+export async function listSessions (workDir, { limit = 5, workingThresholdSec = 2, logger } = {}) {
+  const dirName = cwdToProjectDir(workDir);
+  const dirPath = path.join(PROJECTS_DIR, dirName);
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dirPath);
+  } catch {
+    return [];
+  }
+
+  const candidates = [];
+  for (const name of entries) {
+    if (!name.endsWith('.jsonl')) {
+      continue;
+    }
+    const filePath = path.join(dirPath, name);
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile() || stat.size === 0) {
+      continue;
+    }
+    candidates.push({
+      sessionId: name.slice(0, -'.jsonl'.length),
+      filePath,
+      mtime: stat.mtimeMs,
+      size: stat.size,
+    });
+  }
+
+  candidates.sort((a, b) => b.mtime - a.mtime);
+  const top = candidates.slice(0, limit);
+
+  if (top.length === 0) {
+    return [];
+  }
+
+  const lockMap = await findLocking(top.map(s => s.filePath), logger);
+  const now = Date.now();
+  const workingMs = workingThresholdSec * 1000;
+
+  for (const s of top) {
+    const pids = lockMap.get(s.filePath) || [];
+    s.lockedBy = pids;
+    if (pids.length > 0) {
+      s.status = (now - s.mtime) <= workingMs ? 'working' : 'idle';
+    } else {
+      s.status = 'free';
+    }
+    s.preview = readFirstUserMessage(s.filePath);
+  }
+
+  return top;
+}
+
+/**
+ * Read the first user-typed message text from a JSONL session file.
+ * Returns a short single-line preview, or an empty string if not found.
+ */
+function readFirstUserMessage (filePath) {
+  let buf;
+  try {
+    // Read up to 256 KB — first user message is almost always very early.
+    const fd = fs.openSync(filePath, 'r');
+    const chunk = Buffer.alloc(256 * 1024);
+    const n = fs.readSync(fd, chunk, 0, chunk.length, 0);
+    fs.closeSync(fd);
+    buf = chunk.slice(0, n).toString('utf-8');
+  } catch {
+    return '';
+  }
+
+  const lines = buf.split('\n');
+  const max = Math.min(lines.length, PREVIEW_MAX_LINES);
+  for (let i = 0; i < max; i++) {
+    const line = lines[i];
+    if (!line || line[0] !== '{') {
+      continue;
+    }
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (rec.type !== 'user' || !rec.message) {
+      continue;
+    }
+    const content = rec.message.content;
+    let text = '';
+    if (typeof content === 'string') {
+      text = content;
+    } else if (Array.isArray(content)) {
+      for (const part of content) {
+        if (part && typeof part === 'object' && part.type === 'text' && typeof part.text === 'string') {
+          text = part.text;
+          break;
+        }
+      }
+    }
+    if (!text) {
+      continue;
+    }
+    text = text.replace(/\s+/g, ' ').trim();
+    if (text.length > PREVIEW_MAX_CHARS) {
+      text = text.slice(0, PREVIEW_MAX_CHARS - 1) + '…';
+    }
+    return text;
+  }
+  return '';
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-notification-plugin",
   "productName": "claude-notification-plugin",
-  "version": "1.1.89",
+  "version": "1.1.91",
   "description": "Claude Code task-completion notifications: Telegram, desktop notifications (Windows/macOS/Linux), sound, and voice",
   "type": "module",
   "engines": {