@link-assistant/hive-mind 1.45.1 → 1.46.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @link-assistant/hive-mind
 
+## 1.46.0
+
+### Minor Changes
+
+- d9721c0: Add work session completion notifications and isolation mode to Telegram bot
+
+  Session notifications:
+  - Tracks sessions started by `/solve` and `/hive` commands
+  - Monitors sessions every 30 seconds and sends completion notifications
+  - Sends notification with session name, duration, URL, and exit status
+  - Persistent session tracking via ExecutionStore from start-command
+
+  Isolation mode (`--isolation` option, experimental):
+  - New `--isolation` flag for Telegram bot: `screen`, `tmux`, or `docker`
+  - Uses `$` CLI from link-foundation/start with GUID-based session tracking
+  - Tracks session completion via `$ --status <uuid>` for reliable detection
+  - Solve queue supports isolation-aware execution and process counting
+  - Each isolated session gets a unique UUID for unambiguous tracking
+  - Without `--isolation`, uses existing `start-screen` command (unchanged)
+
 ## 1.45.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.45.1",
+  "version": "1.46.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/isolation-runner.lib.mjs

@@ -0,0 +1,204 @@
+/**
+ * Isolation Runner for Telegram bot
+ *
+ * Executes commands using the `$` CLI from start-command with isolation backends
+ * (screen, tmux, docker). Uses GUIDs for unique session tracking and
+ * `$ --status <uuid>` for reliable completion detection.
+ *
+ * Uses command-stream library to invoke the globally-installed `$` CLI,
+ * following the same pattern as claude.lib.mjs, agent.lib.mjs, etc.
+ *
+ * @see https://github.com/link-foundation/start
+ * @see https://github.com/link-assistant/hive-mind/issues/380
+ */
+
+import crypto from 'crypto';
+
+if (typeof use === 'undefined') {
+  globalThis.use = (await eval(await (await fetch('https://unpkg.com/use-m/use.js')).text())).use;
+}
+
+const { $ } = await use('command-stream');
+
+// Valid isolation backends
+const VALID_ISOLATION_BACKENDS = ['screen', 'tmux', 'docker'];
+
+/**
+ * Generate a UUID v4 for unique session identification
+ * @returns {string} UUID v4 string
+ */
+export function generateSessionId() {
+  return crypto.randomUUID();
+}
+
+/**
+ * Find the `$` CLI binary path
+ * @returns {Promise<string|null>} Path to `$` binary or null
+ */
+async function findStartCommandBinary() {
+  try {
+    const result = await $`which $`;
+    const path = result.stdout?.toString().trim() || '';
+    return path || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Execute a command with isolation via `$` from start-command
+ *
+ * @param {string} command - The command to run (e.g., 'solve')
+ * @param {string[]} args - Arguments for the command
+ * @param {Object} options - Isolation options
+ * @param {string} options.backend - Isolation backend: 'screen', 'tmux', or 'docker'
+ * @param {string} [options.sessionId] - UUID for session tracking (auto-generated if not provided)
+ * @param {boolean} [options.verbose] - Enable verbose logging
+ * @returns {Promise<{success: boolean, sessionId: string, output: string, error?: string, warning?: string}>}
+ */
+export async function executeWithIsolation(command, args, options = {}) {
+  const { backend, verbose = false } = options;
+  const sessionId = options.sessionId || generateSessionId();
+
+  if (!VALID_ISOLATION_BACKENDS.includes(backend)) {
+    return {
+      success: false,
+      sessionId,
+      output: '',
+      error: `Invalid isolation backend: '${backend}'. Must be one of: ${VALID_ISOLATION_BACKENDS.join(', ')}`,
+    };
+  }
+
+  const binPath = await findStartCommandBinary();
+  if (!binPath) {
+    return {
+      success: false,
+      sessionId,
+      output: '',
+      warning: '⚠️ WARNING: start-command ($) not found in PATH\nPlease install: npm install -g start-command',
+      error: 'start-command ($) not found',
+    };
+  }
+
+  if (verbose) {
+    console.log(`[VERBOSE] isolation-runner: Using $ binary at: ${binPath}`);
+    console.log(`[VERBOSE] isolation-runner: Backend: ${backend}, Session ID: ${sessionId}`);
+  }
+
+  // Build arguments as array for the $ CLI:
+  // $ --isolated <backend> --detached --session <sessionId> -- <command> <args...>
+  const argsStr = args.join(' ');
+
+  if (verbose) {
+    console.log(`[VERBOSE] isolation-runner: $ --isolated ${backend} --detached --session ${sessionId} -- ${command} ${argsStr}`);
+  }
+
+  try {
+    const result = await $({ mirror: false })`${binPath} --isolated ${backend} --detached --session ${sessionId} -- ${command} ${argsStr}`;
+
+    const stdout = result.stdout?.toString() || '';
+    const stderr = result.stderr?.toString() || '';
+    const output = stdout + (stderr ? '\n' + stderr : '');
+
+    if (verbose) {
+      console.log(`[VERBOSE] isolation-runner: Output: ${output.substring(0, 500)}`);
+    }
+
+    return {
+      success: true,
+      sessionId,
+      output: output.trim(),
+    };
+  } catch (error) {
+    const stdout = error.stdout?.toString() || '';
+    const stderr = error.stderr?.toString() || '';
+    const output = stdout + stderr;
+
+    if (verbose) {
+      console.error(`[VERBOSE] isolation-runner: Error: ${error.message}`);
+      console.error(`[VERBOSE] isolation-runner: Output: ${output.substring(0, 500)}`);
+    }
+
+    return {
+      success: false,
+      sessionId,
+      output: output.trim(),
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Query the status of an isolated session via `$ --status <uuid>`
+ *
+ * @param {string} sessionId - UUID of the session to check
+ * @param {boolean} [verbose] - Enable verbose logging
+ * @returns {Promise<{exists: boolean, status: string|null, exitCode: number|null, raw: string}>}
+ */
+export async function querySessionStatus(sessionId, verbose = false) {
+  const binPath = await findStartCommandBinary();
+  if (!binPath) {
+    if (verbose) {
+      console.log('[VERBOSE] isolation-runner: Cannot query status - $ binary not found');
+    }
+    return { exists: false, status: null, exitCode: null, raw: '' };
+  }
+
+  try {
+    const result = await $({ mirror: false })`${binPath} --status ${sessionId} --output-format json`;
+
+    const stdout = result.stdout?.toString().trim() || '';
+
+    if (verbose) {
+      console.log(`[VERBOSE] isolation-runner: Status query result: ${stdout.substring(0, 300)}`);
+    }
+
+    try {
+      const data = JSON.parse(stdout);
+      return {
+        exists: true,
+        status: data.status || null,
+        exitCode: data.exitCode !== undefined ? data.exitCode : null,
+        raw: stdout,
+      };
+    } catch {
+      // If JSON parsing fails, try text-based detection
+      const isExecuting = stdout.includes('executing');
+      const isExecuted = stdout.includes('executed');
+      return {
+        exists: isExecuting || isExecuted,
+        status: isExecuting ? 'executing' : isExecuted ? 'executed' : null,
+        exitCode: null,
+        raw: stdout,
+      };
+    }
+  } catch (error) {
+    if (verbose) {
+      console.log(`[VERBOSE] isolation-runner: Status query error: ${error.message}`);
+    }
+    return { exists: false, status: null, exitCode: null, raw: '' };
+  }
+}
+
+/**
+ * Check if an isolated session is still running
+ *
+ * @param {string} sessionId - UUID of the session
+ * @param {boolean} [verbose] - Enable verbose logging
+ * @returns {Promise<boolean>} True if session is still executing
+ */
+export async function isSessionRunning(sessionId, verbose = false) {
+  const result = await querySessionStatus(sessionId, verbose);
+  return result.exists && result.status === 'executing';
+}
+
+/**
+ * Validate that an isolation backend value is valid
+ * @param {string} backend - Backend value to validate
+ * @returns {boolean}
+ */
+export function isValidIsolationBackend(backend) {
+  return VALID_ISOLATION_BACKENDS.includes(backend);
+}
+
+export { VALID_ISOLATION_BACKENDS };

package/src/session-monitor.lib.mjs

@@ -0,0 +1,253 @@
+/**
+ * Session monitoring for Telegram bot
+ *
+ * Tracks active sessions (screen-based or isolation-based) and sends
+ * notifications when they complete.
+ *
+ * Two tracking modes:
+ * 1. Screen mode (default): Uses `screen -ls` to detect session completion
+ * 2. Isolation mode: Uses `$ --status <uuid>` from start-command CLI for reliable tracking
+ *
+ * Session state is stored in-memory. The `$` CLI (start-command) is accessed
+ * purely via its CLI interface, not as a library dependency.
+ *
+ * @see https://github.com/link-foundation/start
+ * @see https://github.com/link-assistant/hive-mind/issues/380
+ */
+
+import { promisify } from 'util';
+import { exec as execCallback } from 'child_process';
+
+const exec = promisify(execCallback);
+
+// Lazy import for isolation runner (only when needed)
+let _querySessionStatus = null;
+async function getQuerySessionStatus() {
+  if (!_querySessionStatus) {
+    const mod = await import('./isolation-runner.lib.mjs');
+    _querySessionStatus = mod.querySessionStatus;
+  }
+  return _querySessionStatus;
+}
+
+// In-memory session store
+const activeSessions = new Map();
+
+/**
+ * Check if a screen session exists
+ * @param {string} sessionName - Name of the screen session to check
+ * @returns {Promise<boolean>} True if session exists, false otherwise
+ */
+export async function checkScreenSessionExists(sessionName) {
+  try {
+    const { stdout } = await exec('screen -ls');
+    return stdout.includes(sessionName);
+  } catch {
+    // screen -ls returns exit code 1 when no sessions exist
+    return false;
+  }
+}
+
+/**
+ * Check if an isolated session is still running using $ --status
+ * @param {string} sessionId - UUID of the isolated session
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Promise<boolean>} True if session is still running
+ */
+async function checkIsolatedSessionRunning(sessionId, verbose = false) {
+  try {
+    const queryStatus = await getQuerySessionStatus();
+    const result = await queryStatus(sessionId, verbose);
+    return result.exists && result.status === 'executing';
+  } catch (error) {
+    if (verbose) {
+      console.error(`[VERBOSE] Error checking isolated session ${sessionId}: ${error.message}`);
+    }
+    return false;
+  }
+}
+
+/**
+ * Get the exit code of a completed isolated session
+ * @param {string} sessionId - UUID of the isolated session
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Promise<number|null>} Exit code or null if unknown
+ */
+async function getIsolatedSessionExitCode(sessionId, verbose = false) {
+  try {
+    const queryStatus = await getQuerySessionStatus();
+    const result = await queryStatus(sessionId, verbose);
+    if (result.exists && result.status === 'executed') {
+      return result.exitCode;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Track a new session for completion monitoring
+ *
+ * @param {string} sessionName - Name of the screen session or isolation session UUID
+ * @param {Object} sessionInfo - Session metadata
+ * @param {number} sessionInfo.chatId - Telegram chat ID to notify
+ * @param {number} [sessionInfo.messageId] - Telegram message ID to update on completion
+ * @param {Date} sessionInfo.startTime - When the session started
+ * @param {string} sessionInfo.url - GitHub URL being processed
+ * @param {string} sessionInfo.command - Command type (solve/hive)
+ * @param {string} [sessionInfo.isolationBackend] - Isolation backend if using isolation mode
+ * @param {string} [sessionInfo.sessionId] - UUID for isolation-based sessions
+ * @param {boolean} verbose - Whether to log verbose output
+ */
+export function trackSession(sessionName, sessionInfo, verbose = false) {
+  activeSessions.set(sessionName, sessionInfo);
+  if (verbose) {
+    const mode = sessionInfo.isolationBackend ? `isolation:${sessionInfo.isolationBackend}` : 'screen';
+    console.log(`[VERBOSE] Session ${sessionName} tracked in memory (mode: ${mode})`);
+  }
+}
+
+/**
+ * Get the number of active sessions being tracked
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {number} Number of active sessions
+ */
+export function getActiveSessionCount(verbose = false) {
+  if (verbose) {
+    console.log(`[VERBOSE] Active sessions: ${activeSessions.size}`);
+  }
+  return activeSessions.size;
+}
+
+/**
+ * Get all active sessions
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Array<{sessionName: string, sessionInfo: Object}>} Array of active sessions
+ */
+function getActiveSessions(verbose = false) {
+  const sessions = [];
+  for (const [sessionName, sessionInfo] of activeSessions.entries()) {
+    sessions.push({ sessionName, sessionInfo });
+  }
+  if (verbose) {
+    console.log(`[VERBOSE] Retrieved ${sessions.length} active session(s)`);
+  }
+  return sessions;
+}
+
+/**
+ * Remove a session from tracking
+ * @param {string} sessionName - Name of the session to remove
+ * @param {boolean} verbose - Whether to log verbose output
+ */
+function completeSession(sessionName, exitCode = 0, verbose = false) {
+  activeSessions.delete(sessionName);
+  if (verbose) {
+    console.log(`[VERBOSE] Session ${sessionName} removed from tracking (exit: ${exitCode})`);
+  }
+}
+
+/**
+ * Monitor active sessions and send notifications when they complete
+ * @param {Object} bot - Telegraf bot instance for sending messages
+ * @param {boolean} verbose - Whether to log verbose output
+ */
+export async function monitorSessions(bot, verbose = false) {
+  const sessions = getActiveSessions(verbose);
+
+  if (sessions.length === 0) {
+    return;
+  }
+
+  if (verbose) {
+    console.log(`[VERBOSE] Checking ${sessions.length} active session(s)...`);
+  }
+
+  for (const { sessionName, sessionInfo } of sessions) {
+    let stillRunning;
+    let exitCode = null;
+
+    if (sessionInfo.isolationBackend && sessionInfo.sessionId) {
+      // Isolation mode: use $ --status for reliable tracking
+      stillRunning = await checkIsolatedSessionRunning(sessionInfo.sessionId, verbose);
+      if (!stillRunning) {
+        exitCode = await getIsolatedSessionExitCode(sessionInfo.sessionId, verbose);
+      }
+    } else {
+      // Screen mode: use screen -ls for detection
+      stillRunning = await checkScreenSessionExists(sessionName);
+    }
+
+    if (!stillRunning) {
+      console.log(`Session ${sessionName} has finished. Sending notification to chat ${sessionInfo.chatId}`);
+
+      try {
+        const endTime = new Date();
+        const startTime = sessionInfo.startTime instanceof Date ? sessionInfo.startTime : new Date(sessionInfo.startTime);
+        const duration = Math.round((endTime - startTime) / 1000);
+        const minutes = Math.floor(duration / 60);
+        const seconds = duration % 60;
+
+        const statusEmoji = exitCode === null || exitCode === 0 ? '✅' : '❌';
+        const statusText = exitCode === null || exitCode === 0 ? 'Completed' : `Failed (exit code: ${exitCode})`;
+        const isolationInfo = sessionInfo.isolationBackend ? `\n🔒 Isolation: ${sessionInfo.isolationBackend}` : '';
+
+        let message = `${statusEmoji} *Work Session ${statusText}*\n\n`;
+        message += `📊 Session: \`${sessionName}\`\n`;
+        message += `⏱️ Duration: ${minutes}m ${seconds}s\n`;
+        message += `🔗 URL: ${sessionInfo.url}${isolationInfo}\n\n`;
+        message += `The work session has finished. You can now review the results.`;
+
+        // Update the original reply message if messageId is available, otherwise send new message
+        if (sessionInfo.messageId) {
+          await bot.telegram.editMessageText(sessionInfo.chatId, sessionInfo.messageId, undefined, message, { parse_mode: 'Markdown' });
+        } else {
+          await bot.telegram.sendMessage(sessionInfo.chatId, message, { parse_mode: 'Markdown' });
+        }
+
+        completeSession(sessionName, exitCode || 0, verbose);
+      } catch (error) {
+        console.error(`Failed to send completion notification for ${sessionName}:`, error);
+        completeSession(sessionName, 1, verbose);
+      }
+    }
+  }
+}
+
+/**
+ * Start the session monitoring interval
+ * @param {Object} bot - Telegraf bot instance for sending messages
+ * @param {boolean} verbose - Whether to log verbose output
+ * @param {number} intervalMs - Monitoring interval in milliseconds (default: 30000)
+ * @returns {NodeJS.Timer} The interval timer (can be cleared with clearInterval)
+ */
+export function startSessionMonitoring(bot, verbose = false, intervalMs = 30000) {
+  const timer = setInterval(() => monitorSessions(bot, verbose), intervalMs);
+  console.log(`📊 Session monitoring started (checking every ${intervalMs / 1000} seconds, storage: in-memory)`);
+  return timer;
+}
+
+/**
+ * Get statistics about session tracking
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Object} Statistics object
+ */
+export function getSessionStats(verbose = false) {
+  const sessions = Array.from(activeSessions.values());
+  const isolated = sessions.filter(s => s.isolationBackend);
+
+  if (verbose) {
+    console.log(`[VERBOSE] Session stats: ${sessions.length} total, ${isolated.length} isolated`);
+  }
+
+  return {
+    total: activeSessions.size,
+    executing: activeSessions.size,
+    executed: 0,
+    successful: 0,
+    failed: 0,
+    isolated: isolated.length,
+    storageType: 'in-memory',
+  };
+}

package/src/telegram-bot.mjs

@@ -23,27 +23,18 @@ const { loadLenvConfig } = await import('./lenv-reader.lib.mjs');
 
 const dotenvxModule = await use('@dotenvx/dotenvx');
 const dotenvx = dotenvxModule.default || dotenvxModule;
-
 const getenvModule = await use('getenv');
-// Node 24 CJS/ESM interop may return the whole module object instead of the function directly
 const getenv = typeof getenvModule === 'function' ? getenvModule : getenvModule.default || getenvModule;
 
-// Load .env configuration as base
-// quiet: true suppresses info messages, ignore: ['MISSING_ENV_FILE'] suppresses error when .env doesn't exist
-// This makes .env file optional (issue #1318)
+// Load .env/.lenv configuration (issue #1318)
 dotenvx.config({ quiet: true, ignore: ['MISSING_ENV_FILE'] });
-
-// Load .lenv configuration (if exists)
-// .lenv overrides .env
 loadLenvConfig({ override: true, quiet: true });
 
 const yargsModule = await use('yargs@17.7.2');
 const yargs = yargsModule.default || yargsModule;
 const helpersModuleBot = await use('yargs@17.7.2/helpers');
-// Node 24 CJS/ESM interop may return the whole module object instead of named exports directly
 const _helpersBot = helpersModuleBot.default || helpersModuleBot;
 const hideBin = _helpersBot.hideBin || (argv => argv.slice(2));
-// Import yargs configurations, GitHub utilities, and telegram helpers
 const { createYargsConfig: createSolveYargsConfig, detectMalformedFlags } = await import('./solve.config.lib.mjs');
 const { createYargsConfig: createHiveYargsConfig } = await import('./hive.config.lib.mjs');
 const { parseGitHubUrl } = await import('./github.lib.mjs');
@@ -55,8 +46,8 @@ const { escapeMarkdown, escapeMarkdownV2, cleanNonPrintableChars, makeSpecialCha
 const { getSolveQueue, createQueueExecuteCallback } = await import('./telegram-solve-queue.lib.mjs');
 const { isChatStopped, getChatStopInfo, getStoppedChatRejectMessage, DEFAULT_STOP_REASON } = await import('./telegram-start-stop-command.lib.mjs');
 const { isOldMessage: _isOldMessage, isGroupChat: _isGroupChat, isChatAuthorized: _isChatAuthorized, isForwardedOrReply: _isForwardedOrReply, extractCommandFromText, extractGitHubUrl: _extractGitHubUrl } = await import('./telegram-message-filters.lib.mjs');
-// Import bot launcher with exponential backoff retry (issue #1240)
 const { launchBotWithRetry } = await import('./telegram-bot-launcher.lib.mjs');
+const { trackSession, startSessionMonitoring } = await import('./session-monitor.lib.mjs');
 
 const config = yargs(hideBin(process.argv))
   .usage('Usage: hive-telegram-bot [options]')
@@ -118,6 +109,7 @@ const config = yargs(hideBin(process.argv))
     alias: 'v',
     default: getenv('TELEGRAM_BOT_VERBOSE', 'false') === 'true',
   })
+  .option('isolation', { type: 'string', description: 'Experimental: isolation backend (screen/tmux/docker)', default: getenv('TELEGRAM_ISOLATION', '') })
   .help('h')
   .alias('h', 'help')
   .parserConfiguration({
@@ -127,65 +119,52 @@ const config = yargs(hideBin(process.argv))
   .strict() // Enable strict mode to reject unknown options (consistent with solve.mjs and hive.mjs)
   .parse();
 
-// Load configuration from --configuration option if provided
-// This allows users to pass environment variables via command line
-//
-// Complete configuration priority order (highest priority last):
-// 1. .env (base configuration, loaded first - already loaded above at line 24)
-// 2. .lenv (overrides .env - already loaded above at line 28)
-// 3. yargs CLI options parsed above (lines 41-102) use getenv() for defaults,
-//    which reads from process.env populated by .env and .lenv
-// 4. --configuration option (overrides process.env, affecting getenv() calls below)
-// 5. Final resolution (lines 116+): CLI option values > environment variables
-//    Pattern: config.X || getenv('VAR') means CLI options have highest priority
+// Configuration priority: CLI option > --configuration LINO > .lenv > .env
 if (config.configuration) {
   loadLenvConfig({ configuration: config.configuration, override: true, quiet: true });
 }
 
-// After loading configuration, resolve final values
-// Priority: CLI option > environment variable
 const BOT_TOKEN = config.token || getenv('TELEGRAM_BOT_TOKEN', '');
 const VERBOSE = config.verbose || getenv('TELEGRAM_BOT_VERBOSE', 'false') === 'true';
-
 if (!BOT_TOKEN) {
-  console.error('Error: TELEGRAM_BOT_TOKEN environment variable or --token option is not set');
-  console.error('Please set it with: export TELEGRAM_BOT_TOKEN=your_bot_token');
-  console.error('Or use: hive-telegram-bot --token your_bot_token');
+  console.error('Error: TELEGRAM_BOT_TOKEN not set. Use --token or TELEGRAM_BOT_TOKEN env var.');
   process.exit(1);
 }
 
-// After loading configuration, resolve final values from environment or config
-// Priority: CLI option > environment variable (from .lenv or .env)
-// NOTE: This section moved BEFORE loading telegraf for faster dry-run mode (issue #801)
+// Resolve final config values (CLI option > environment variable)
 const resolvedAllowedChats = config.allowedChats || getenv('TELEGRAM_ALLOWED_CHATS', '');
 const allowedChats = resolvedAllowedChats ? lino.parseNumericIds(resolvedAllowedChats) : null;
 
 // Parse allowed topics (chatId:topicId pairs in Links Notation)
 const resolvedAllowedTopics = config.allowedTopics || getenv('TELEGRAM_ALLOWED_TOPICS', '');
 const allowedTopics = resolvedAllowedTopics ? lino.parseLinks(resolvedAllowedTopics) : null;
-
-// Parse override options
 const resolvedSolveOverrides = config.solveOverrides || getenv('TELEGRAM_SOLVE_OVERRIDES', '');
 const solveOverrides = resolvedSolveOverrides
   ? lino
       .parseStringValues(resolvedSolveOverrides)
-      .map(line => line.trim())
-      .filter(line => line)
+      .map(l => l.trim())
+      .filter(l => l)
   : [];
-
 const resolvedHiveOverrides = config.hiveOverrides || getenv('TELEGRAM_HIVE_OVERRIDES', '');
 const hiveOverrides = resolvedHiveOverrides
   ? lino
       .parseStringValues(resolvedHiveOverrides)
-      .map(line => line.trim())
-      .filter(line => line)
+      .map(l => l.trim())
+      .filter(l => l)
   : [];
-
-// Command enable/disable flags
-// Note: yargs automatically supports --no-solve and --no-hive for negation
-// Priority: CLI option > environment variable
 const solveEnabled = config.solve;
 const hiveEnabled = config.hive;
+// Isolation mode (experimental): uses `$` from start-command with specified backend
+const ISOLATION_BACKEND = (config.isolation || getenv('TELEGRAM_ISOLATION', '')).trim().toLowerCase();
+let isolationRunner = null;
+if (ISOLATION_BACKEND) {
+  if (!['screen', 'tmux', 'docker'].includes(ISOLATION_BACKEND)) {
+    console.error(`Error: Invalid --isolation value '${ISOLATION_BACKEND}'. Must be: screen, tmux, or docker`);
+    process.exit(1);
+  }
+  console.log(`🔒 Isolation mode enabled: ${ISOLATION_BACKEND} (experimental)`);
+  isolationRunner = await import('./isolation-runner.lib.mjs');
+}
 
 // Validate solve overrides early using solve's yargs config
 // Only validate if solve command is enabled
@@ -607,29 +586,35 @@ async function safeReply(ctx, text, options = {}) {
   }
 }
 
-// Execute a start-screen command and update the initial message with the result
+// Execute a command via isolation mode ($ from start-command) or start-screen, then update message
 async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock) {
-  const result = await executeStartScreen(commandName, args);
-  const { chat, message_id } = startingMessage;
-
-  // Safely edit message - catch errors to prevent stuck "Starting..." messages (issue #1062)
+  const { chat, message_id: msgId } = startingMessage;
   const safeEdit = async text => {
     try {
-      await ctx.telegram.editMessageText(chat.id, message_id, undefined, text, { parse_mode: 'Markdown' });
+      await ctx.telegram.editMessageText(chat.id, msgId, undefined, text, { parse_mode: 'Markdown' });
     } catch (e) {
       console.error(`[telegram-bot] Failed to update message for ${commandName}: ${e.message}`);
     }
   };
-
-  if (result.warning) return safeEdit(`⚠️  ${result.warning}`);
-
-  if (result.success) {
-    const match = result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -R\s+(\S+)/);
-    const session = match ? match[1] : 'unknown';
-    await safeEdit(`✅ ${commandName.charAt(0).toUpperCase() + commandName.slice(1)} command started successfully!\n\n📊 Session: \`${session}\`\n\n${infoBlock}`);
+  let result,
+    session,
+    extraInfo = '';
+  if (ISOLATION_BACKEND && isolationRunner) {
+    const sid = isolationRunner.generateSessionId();
+    VERBOSE && console.log(`[VERBOSE] Using isolation (${ISOLATION_BACKEND}), session: ${sid}`);
+    result = await isolationRunner.executeWithIsolation(commandName, args, { backend: ISOLATION_BACKEND, sessionId: sid, verbose: VERBOSE });
+    session = sid;
+    extraInfo = `\n🔒 Isolation: \`${ISOLATION_BACKEND}\``;
+    if (result.success) trackSession(sid, { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, isolationBackend: ISOLATION_BACKEND, sessionId: sid }, VERBOSE);
   } else {
-    await safeEdit(`❌ Error executing ${commandName} command:\n\n\`\`\`\n${result.error || result.output}\n\`\`\``);
+    result = await executeStartScreen(commandName, args);
+    const match = result.success && (result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -R\s+(\S+)/));
+    session = match ? match[1] : 'unknown';
+    if (result.success && session !== 'unknown') trackSession(session, { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName }, VERBOSE);
   }
+  if (result.warning) return safeEdit(`⚠️  ${result.warning}`);
+  if (result.success) await safeEdit(`✅ ${commandName.charAt(0).toUpperCase() + commandName.slice(1)} command started successfully!\n\n📊 Session: \`${session}\`${extraInfo}\n\n${infoBlock}\n\n🔔 You will receive a notification when the session finishes.`);
+  else await safeEdit(`❌ Error executing ${commandName} command:\n\n\`\`\`\n${result.error || result.output}\n\`\`\``);
 }
 
 bot.command('help', async ctx => {
@@ -707,6 +692,9 @@ bot.command('help', async ctx => {
   message += '*/help* - Show this help message\n';
   message += '*/stop* - Stop accepting new tasks (owner only)\n';
   message += '*/start* - Resume accepting tasks (owner only)\n\n';
+  message += '🔔 *Session Notifications:* The bot monitors sessions and notifies when they complete.\n';
+  if (ISOLATION_BACKEND) message += `🔒 *Isolation Mode:* \`${ISOLATION_BACKEND}\` (experimental)\n`;
+  message += '\n';
   message += '⚠️ *Note:* /solve, /hive, /solve\\_queue, /limits, /version, /accept\\_invites, /merge, /stop and /start commands only work in group chats.\n\n';
   message += '🔧 *Common Options:*\n';
   message += `• \`--model <model>\` or \`-m\` - ${buildModelOptionDescription()}\n`;
@@ -1043,7 +1031,17 @@ async function handleSolveCommand(ctx) {
     if (check.reason) queueMessage += `\n\n⏳ Waiting: ${escapeMarkdown(check.reason)}`;
     const queuedMessage = await safeReply(ctx, queueMessage, { reply_to_message_id: ctx.message.message_id });
     queueItem.messageInfo = { chatId: queuedMessage.chat.id, messageId: queuedMessage.message_id };
-    if (!solveQueue.executeCallback) solveQueue.executeCallback = createQueueExecuteCallback(executeStartScreen);
+    if (!solveQueue.executeCallback) {
+      solveQueue.executeCallback =
+        ISOLATION_BACKEND && isolationRunner
+          ? async item => {
+              const sid = isolationRunner.generateSessionId();
+              const r = await isolationRunner.executeWithIsolation('solve', item.args, { backend: ISOLATION_BACKEND, sessionId: sid, verbose: VERBOSE });
+              if (r.success) trackSession(sid, { chatId: item.ctx?.chat?.id, messageId: item.messageInfo?.messageId, startTime: new Date(), url: item.url, command: 'solve', isolationBackend: ISOLATION_BACKEND, sessionId: sid }, VERBOSE);
+              return { ...r, output: r.output || `session: ${sid}` };
+            }
+          : createQueueExecuteCallback(executeStartScreen, (session, info) => trackSession(session, info, VERBOSE));
+    }
   }
 }
 
@@ -1457,6 +1455,9 @@ launchBotWithRetry(
 
       console.log('[VERBOSE] Send a message to the bot to test message reception');
     }
+
+    // Start session monitoring - check for completed sessions every 30 seconds
+    startSessionMonitoring(bot, VERBOSE);
   })
   .catch(error => {
     console.error('❌ Failed to start bot:', error);

package/src/telegram-solve-queue.lib.mjs

@@ -1351,14 +1351,44 @@ export function resetSolveQueue() {
 /**
  * Create an execute callback for the queue
  * @param {Function} executeStartScreen - Function to execute start-screen command
+ * @param {Function} [trackSessionFn] - Optional function to track session for completion notifications
  * @returns {Function} Execute callback for queue items
  */
-export function createQueueExecuteCallback(executeStartScreen) {
+export function createQueueExecuteCallback(executeStartScreen, trackSessionFn) {
   return async item => {
-    return await executeStartScreen('solve', item.args);
+    const result = await executeStartScreen('solve', item.args);
+    if (trackSessionFn && result.success) {
+      const match = result.output && (result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -R\s+(\S+)/));
+      const session = match ? match[1] : null;
+      if (session) {
+        trackSessionFn(session, { chatId: item.ctx?.chat?.id, messageId: item.messageInfo?.messageId, startTime: new Date(), url: item.url, command: 'solve' });
+      }
+    }
+    return result;
   };
 }
 
+/**
+ * Get count of running isolated sessions tracked via ExecutionStore
+ * When isolation mode is enabled, this replaces pgrep-based process detection
+ * for more reliable task counting.
+ *
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Promise<{count: number, sessions: string[]}>}
+ */
+export async function getRunningIsolatedSessions(verbose = false) {
+  try {
+    const { getActiveSessionCount } = await import('./session-monitor.lib.mjs');
+    const count = getActiveSessionCount(verbose);
+    return { count, sessions: [] };
+  } catch (error) {
+    if (verbose) {
+      console.error(`[VERBOSE] /solve_queue error getting isolated sessions:`, error.message);
+    }
+    return { count: 0, sessions: [] };
+  }
+}
+
 export default {
   SolveQueue,
   SolveQueueItem,
@@ -1367,6 +1397,7 @@ export default {
   getRunningProcesses,
   getRunningClaudeProcesses,
   getRunningAgentProcesses,
+  getRunningIsolatedSessions,
   createQueueExecuteCallback,
   formatDuration,
   QUEUE_CONFIG,