@link-assistant/hive-mind 1.46.6 → 1.46.8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 1.46.8
+
+### Patch Changes
+
+- bcf2b9b: Retry on network issues and minimize terminal/log output differences (#1536): add ghRetry/ghCmdRetry utilities with exponential backoff for transient network errors (TCP reset, TLS timeout, connection refused, unexpected EOF). Apply retry to critical gh CLI calls: accept-invite, repository setup, auto-fork permission check, visibility detection, write permission check. Log stderr to log file on command failure for terminal/log parity. Add 'unexpected eof' to transient error detection patterns.
+
+## 1.46.7
+
+### Patch Changes
+
+- 249cf93: Fix --isolation option not working in /solve and /hive Telegram commands (#1534): extract --isolation from user args before validation, so it's used for execution isolation (via $ CLI from start-command) instead of being forwarded to solve/hive as an unknown argument. Per-command --isolation takes precedence over bot-level ISOLATION_BACKEND setting.
+
 ## 1.46.6
 
 ### Patch Changes

package/package.json

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

package/src/github.lib.mjs

@@ -2,7 +2,7 @@
 // GitHub-related utility functions. Check if use is already defined (when imported from solve.mjs), if not, fetch it (when running standalone)
 if (typeof globalThis.use === 'undefined') globalThis.use = (await eval(await (await fetch('https://unpkg.com/use-m/use.js')).text())).use;
 const { $ } = await use('command-stream'); // Use command-stream for consistent $ behavior
-import { log, maskToken, cleanErrorMessage, isENOSPC } from './lib.mjs';
+import { log, maskToken, cleanErrorMessage, isENOSPC, ghCmdRetry } from './lib.mjs';
 import { reportError } from './sentry.lib.mjs';
 import { githubLimits, timeouts } from './config.lib.mjs';
 import { batchCheckPullRequestsForIssues as batchCheckPRs, batchCheckArchivedRepositories as batchCheckArchived } from './github.batch.lib.mjs';
@@ -172,8 +172,8 @@ export const checkRepositoryWritePermission = async (owner, repo, options = {})
   }
   try {
     await log('🔍 Checking repository write permissions...');
-    // Use GitHub API to check repository permissions
-    const permResult = await $`gh api repos/${owner}/${repo} --jq .permissions`;
+    // Use GitHub API to check repository permissions (issue #1536: retry on network errors)
+    const permResult = await ghCmdRetry(() => $`gh api repos/${owner}/${repo} --jq .permissions`, { label: `write perms ${owner}/${repo}` });
     if (permResult.code !== 0) {
       // API call failed - might be a private repo or network issue
       const errorOutput = (permResult.stderr ? permResult.stderr.toString() : '') + (permResult.stdout ? permResult.stdout.toString() : '');
@@ -1437,7 +1437,8 @@ export async function handlePRNotFoundError({ prNumber, owner, repo, argv, shoul
  */
 export async function detectRepositoryVisibility(owner, repo) {
   try {
-    const visibilityResult = await $`gh api repos/${owner}/${repo} --jq .visibility`;
+    // Issue #1536: retry on transient network errors
+    const visibilityResult = await ghCmdRetry(() => $`gh api repos/${owner}/${repo} --jq .visibility`, { label: `visibility ${owner}/${repo}` });
     if (visibilityResult.code === 0) {
       const visibility = visibilityResult.stdout.toString().trim();
       const isPublic = visibility === 'public';

package/src/lib.mjs

@@ -291,11 +291,92 @@ export const isTransientNetworkError = error => {
   const output = (error?.stderr?.toString() || error?.stdout?.toString() || '').toLowerCase();
   const combined = msg + ' ' + output;
 
-  const transientPatterns = ['i/o timeout', 'dial tcp', 'connection refused', 'connection reset', 'econnreset', 'etimedout', 'enotfound', 'ehostunreach', 'enetunreach', 'network is unreachable', 'temporary failure', 'http 502', 'http 503', 'http 504', 'bad gateway', 'service unavailable', 'gateway timeout', 'tls handshake timeout', 'ssl_error', 'socket hang up'];
+  // Issue #1536: added 'unexpected eof' — seen in gh CLI when connection drops mid-response
+  const transientPatterns = ['i/o timeout', 'dial tcp', 'connection refused', 'connection reset', 'econnreset', 'etimedout', 'enotfound', 'ehostunreach', 'enetunreach', 'network is unreachable', 'temporary failure', 'http 502', 'http 503', 'http 504', 'bad gateway', 'service unavailable', 'gateway timeout', 'tls handshake timeout', 'ssl_error', 'socket hang up', 'unexpected eof'];
 
   return transientPatterns.some(pattern => combined.includes(pattern));
 };
 
+/**
+ * Retry a GitHub CLI / API operation with exponential backoff on transient network errors.
+ * Unlike the generic `retry()`, this function:
+ * - Only retries on transient network errors (TCP reset, TLS timeout, etc.)
+ * - Immediately rethrows non-transient errors (404, 403, auth failures)
+ * - Logs stderr to the log file when a command fails (fixing terminal/log parity)
+ *
+ * Issue #1536: Most gh commands had no retry logic, causing solve to abort on
+ * intermittent network issues.
+ *
+ * @param {Function} fn - Async function to execute (should call gh CLI or GitHub API)
+ * @param {Object} [options] - Options
+ * @param {number} [options.maxAttempts=3] - Maximum number of attempts
+ * @param {number} [options.delay=1000] - Initial delay between retries in ms
+ * @param {number} [options.backoff=2] - Backoff multiplier
+ * @param {string} [options.label='gh command'] - Label for log messages
+ * @returns {Promise<*>} Result of successful function execution
+ * @throws {Error} Last error if all attempts fail or error is non-transient
+ */
+export const ghRetry = async (fn, options = {}) => {
+  const { maxAttempts = 3, delay = 1000, backoff = 2, label = 'gh command' } = options;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (isTransientNetworkError(error) && attempt < maxAttempts) {
+        const waitTime = delay * Math.pow(backoff, attempt - 1);
+        await log(`⚠️ ${label}: Network error (attempt ${attempt}/${maxAttempts}), retrying in ${waitTime / 1000}s...`, { level: 'warn' });
+        await sleep(waitTime);
+        continue;
+      }
+      throw error;
+    }
+  }
+};
+
+/**
+ * Execute a command-stream `$` call with retry on transient network errors.
+ * This wraps the pattern: call $`gh ...`, check exit code, handle errors.
+ * On failure, stderr is logged to the log file (fixing terminal/log parity from issue #1536).
+ *
+ * @param {Function} cmdFn - Function that returns a command-stream result (e.g., () => $`gh api ...`)
+ * @param {Object} [options] - Options
+ * @param {number} [options.maxAttempts=3] - Maximum number of attempts
+ * @param {number} [options.delay=1000] - Initial delay between retries in ms
+ * @param {number} [options.backoff=2] - Backoff multiplier
+ * @param {string} [options.label='gh command'] - Label for log messages
+ * @returns {Promise<{stdout: string, stderr: string, code: number}>} Command result
+ */
+export const ghCmdRetry = async (cmdFn, options = {}) => {
+  const { maxAttempts = 3, delay = 1000, backoff = 2, label = 'gh command' } = options;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const result = await cmdFn();
+
+    // Log stderr to log file for parity (issue #1536)
+    const stderr = result.stderr?.toString().trim();
+    if (stderr && result.code !== 0) {
+      await log(`   [stderr] ${stderr}`, { level: 'warn' });
+    }
+
+    if (result.code === 0) {
+      return result;
+    }
+
+    // Check if this is a transient network error worth retrying
+    const combinedOutput = (result.stdout?.toString() || '') + ' ' + (result.stderr?.toString() || '');
+    if (isTransientNetworkError({ message: combinedOutput }) && attempt < maxAttempts) {
+      const waitTime = delay * Math.pow(backoff, attempt - 1);
+      await log(`⚠️ ${label}: Network error (attempt ${attempt}/${maxAttempts}), retrying in ${waitTime / 1000}s...`, { level: 'warn' });
+      await sleep(waitTime);
+      continue;
+    }
+
+    // Non-transient error or last attempt — return the result as-is
+    return result;
+  }
+};
+
 /**
  * Format bytes to human readable string
  * @param {number} bytes - Number of bytes

package/src/solve.accept-invite.lib.mjs

@@ -5,9 +5,13 @@
  * this module only accepts the invitation for the specific repository or organization
  * that is being solved. This is safer and more targeted.
  *
+ * Issue #1536: Added retry with exponential backoff for transient network errors
+ * (TLS handshake timeout, unexpected EOF, connection reset, etc.)
+ *
  * @see https://docs.github.com/en/rest/collaborators/invitations
  * @see https://docs.github.com/en/rest/orgs/members
  * @see https://github.com/link-assistant/hive-mind/issues/1373
+ * @see https://github.com/link-assistant/hive-mind/issues/1536
  */
 
 import { promisify } from 'util';
@@ -15,6 +19,10 @@ import { exec as execCallback } from 'child_process';
 
 const exec = promisify(execCallback);
 
+// Import retry utility (issue #1536)
+const lib = await import('./lib.mjs');
+const { ghRetry } = lib;
+
 /**
  * Accepts pending GitHub repository or organization invitation for a specific target.
  *
@@ -35,7 +43,7 @@ export async function autoAcceptInviteForRepo(owner, repo, log, verbose) {
 
   // Check for pending repository invitation
   try {
-    const { stdout: repoInvJson } = await exec('gh api /user/repository_invitations 2>/dev/null || echo "[]"');
+    const { stdout: repoInvJson } = await ghRetry(() => exec('gh api /user/repository_invitations 2>/dev/null || echo "[]"'), { label: 'fetch repo invitations' });
     const repoInvitations = JSON.parse(repoInvJson.trim() || '[]');
     verbose && (await log(`   Found ${repoInvitations.length} total pending repo invitation(s)`, { verbose: true }));
 
@@ -43,7 +51,7 @@ export async function autoAcceptInviteForRepo(owner, repo, log, verbose) {
 
     if (matchingInv) {
       try {
-        await exec(`gh api -X PATCH /user/repository_invitations/${matchingInv.id}`);
+        await ghRetry(() => exec(`gh api -X PATCH /user/repository_invitations/${matchingInv.id}`), { label: `accept repo invitation for ${fullName}` });
         await log(`✅ --auto-accept-invite: Accepted repository invitation for ${fullName}`);
         result.acceptedRepo = true;
       } catch (e) {
@@ -58,7 +66,7 @@ export async function autoAcceptInviteForRepo(owner, repo, log, verbose) {
 
   // Check for pending organization membership
   try {
-    const { stdout: orgMemJson } = await exec('gh api /user/memberships/orgs 2>/dev/null || echo "[]"');
+    const { stdout: orgMemJson } = await ghRetry(() => exec('gh api /user/memberships/orgs 2>/dev/null || echo "[]"'), { label: 'fetch org memberships' });
     const orgMemberships = JSON.parse(orgMemJson.trim() || '[]');
     const pendingOrgs = orgMemberships.filter(m => m.state === 'pending');
     verbose && (await log(`   Found ${pendingOrgs.length} total pending org invitation(s)`, { verbose: true }));
@@ -68,7 +76,7 @@ export async function autoAcceptInviteForRepo(owner, repo, log, verbose) {
     if (matchingOrg) {
       const orgName = matchingOrg.organization.login;
       try {
-        await exec(`gh api -X PATCH /user/memberships/orgs/${orgName} -f state=active`);
+        await ghRetry(() => exec(`gh api -X PATCH /user/memberships/orgs/${orgName} -f state=active`), { label: `accept org invitation for ${orgName}` });
         await log(`✅ --auto-accept-invite: Accepted organization invitation for ${orgName}`);
         result.acceptedOrg = true;
       } catch (e) {

package/src/solve.mjs

@@ -239,9 +239,9 @@ const claudePath = argv.executeToolWithBun ? 'bunx claude' : process.env.CLAUDE_
 if (argv.autoFork && !argv.fork) {
   const { detectRepositoryVisibility } = githubLib;
 
-  // Check if we have write access first
+  // Check if we have write access first (issue #1536: retry on transient network errors)
   await log('🔍 Checking repository access for auto-fork...');
-  const permResult = await $`gh api repos/${owner}/${repo} --jq .permissions`;
+  const permResult = await lib.ghCmdRetry(() => $`gh api repos/${owner}/${repo} --jq .permissions`, { label: 'auto-fork perms' });
 
   if (permResult.code === 0) {
     const permissions = JSON.parse(permResult.stdout.toString().trim());

package/src/solve.repository.lib.mjs

@@ -36,7 +36,7 @@ const { checkRepositoryWritePermission } = githubLib;
 // Get root repository (fork source or self), or null if inaccessible
 export const getRootRepository = async (owner, repo) => {
   try {
-    const result = await $`gh api repos/${owner}/${repo} --jq '{fork: .fork, source: .source.full_name}' 2>&1`;
+    const result = await lib.ghCmdRetry(() => $`gh api repos/${owner}/${repo} --jq '{fork: .fork, source: .source.full_name}' 2>&1`, { label: `get root repo ${owner}/${repo}` });
     if (result.code !== 0) return null;
 
     const repoInfo = JSON.parse(result.stdout.toString().trim());
@@ -50,11 +50,10 @@ export const getRootRepository = async (owner, repo) => {
 // Check if current user has a fork of the given root repository
 export const checkExistingForkOfRoot = async rootRepo => {
   try {
-    const userResult = await $`gh api user --jq .login`;
+    const userResult = await lib.ghCmdRetry(() => $`gh api user --jq .login`, { label: 'get user (fork check)' });
     if (userResult.code !== 0) return null;
     const currentUser = userResult.stdout.toString().trim();
-
-    const forksResult = await $`gh api repos/${rootRepo}/forks --paginate --jq '.[] | select(.owner.login == "${currentUser}") | .full_name'`;
+    const forksResult = await lib.ghCmdRetry(() => $`gh api repos/${rootRepo}/forks --paginate --jq '.[] | select(.owner.login == "${currentUser}") | .full_name'`, { label: `check forks of ${rootRepo}` });
     if (forksResult.code !== 0) return null;
 
     const forks = forksResult.stdout
@@ -363,8 +362,8 @@ export const setupRepository = async (argv, owner, repo, forkOwner = null, issue
     await log(`\n${formatAligned('🍴', 'Fork mode:', 'ENABLED')}`);
     await log(`${formatAligned('', 'Checking fork status...', '')}\n`);
 
-    // Get current user
-    const userResult = await $`gh api user --jq .login`;
+    // Get current user (issue #1536: retry on transient network errors)
+    const userResult = await lib.ghCmdRetry(() => $`gh api user --jq .login`, { label: 'get current user' });
     if (userResult.code !== 0) {
       await log(`${formatAligned('❌', 'Error:', 'Failed to get current user')}`);
       await safeExit(1, 'Repository setup failed');

package/src/telegram-bot.mjs

@@ -40,6 +40,7 @@ const { createYargsConfig: createHiveYargsConfig } = await import('./hive.config
 const { parseGitHubUrl } = await import('./github.lib.mjs');
 const { validateModelName, buildModelOptionDescription } = await import('./models/index.mjs');
 const { validateBranchInArgs } = await import('./solve.branch.lib.mjs');
+const { extractIsolationFromArgs, isValidPerCommandIsolation, resolveIsolation, createIsolationAwareQueueCallback } = await import('./telegram-isolation.lib.mjs');
 const { formatUsageMessage, getAllCachedLimits } = await import('./limits.lib.mjs');
 const { getVersionInfo, formatVersionMessage } = await import('./version-info.lib.mjs');
 const { escapeMarkdown, escapeMarkdownV2, cleanNonPrintableChars, makeSpecialCharsVisible } = await import('./telegram-markdown.lib.mjs');
@@ -586,8 +587,7 @@ async function safeReply(ctx, text, options = {}) {
   }
 }
 
-// Execute a command via isolation mode ($ from start-command) or start-screen, then update message
-async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock) {
+async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock, perCommandIsolation = null) {
   const { chat, message_id: msgId } = startingMessage;
   const safeEdit = async text => {
     try {
@@ -596,16 +596,16 @@ async function executeAndUpdateMessage(ctx, startingMessage, commandName, args,
       console.error(`[telegram-bot] Failed to update message for ${commandName}: ${e.message}`);
     }
   };
+  const iso = await resolveIsolation(perCommandIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE);
   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);
+  if (iso) {
+    session = iso.runner.generateSessionId();
+    VERBOSE && console.log(`[VERBOSE] Using isolation (${iso.backend}), session: ${session}`);
+    result = await iso.runner.executeWithIsolation(commandName, args, { backend: iso.backend, sessionId: session, verbose: VERBOSE });
+    extraInfo = `\n🔒 Isolation: \`${iso.backend}\``;
+    if (result.success) trackSession(session, { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, isolationBackend: iso.backend, sessionId: session }, VERBOSE);
   } else {
     result = await executeStartScreen(commandName, args);
     const match = result.success && (result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -R\s+(\S+)/));
@@ -934,9 +934,12 @@ async function handleSolveCommand(ctx) {
     await safeReply(ctx, errorMsg, { reply_to_message_id: ctx.message.message_id });
     return;
   }
-
-  // Merge user args with overrides
-  const args = mergeArgsWithOverrides(userArgs, solveOverrides);
+  const { backend: solvePerCommandIsolation, filteredArgs: userArgsWithoutIsolation } = extractIsolationFromArgs(userArgs); // issue #1534
+  if (solvePerCommandIsolation && !isValidPerCommandIsolation(solvePerCommandIsolation)) {
+    await safeReply(ctx, `❌ Invalid --isolation value '${escapeMarkdown(solvePerCommandIsolation)}'. Must be: screen, tmux, or docker`, { reply_to_message_id: ctx.message.message_id });
+    return;
+  }
+  const args = mergeArgsWithOverrides(userArgsWithoutIsolation, solveOverrides);
 
   // Determine tool from args (default: claude)
   let solveTool = 'claude';
@@ -1024,23 +1027,16 @@ async function handleSolveCommand(ctx) {
 
   if (check.canStart && queueStats.queued === 0) {
     const startingMessage = await safeReply(ctx, `🚀 Starting solve command...\n\n${infoBlock}`, { reply_to_message_id: ctx.message.message_id });
-    await executeAndUpdateMessage(ctx, startingMessage, 'solve', args, infoBlock);
+    await executeAndUpdateMessage(ctx, startingMessage, 'solve', args, infoBlock, solvePerCommandIsolation);
   } else {
-    const queueItem = solveQueue.enqueue({ url: normalizedUrl, args, ctx, requester, infoBlock, tool: solveTool });
+    const queueItem = solveQueue.enqueue({ url: normalizedUrl, args, ctx, requester, infoBlock, tool: solveTool, perCommandIsolation: solvePerCommandIsolation });
     let queueMessage = `📋 Solve command queued (position #${queueStats.queued + 1})\n\n${infoBlock}`;
     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 =
-        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));
+      const _t = (s, i) => trackSession(s, i, VERBOSE);
+      solveQueue.executeCallback = createIsolationAwareQueueCallback(ISOLATION_BACKEND, isolationRunner, _t, createQueueExecuteCallback(executeStartScreen, _t), VERBOSE);
     }
   }
 }
@@ -1135,8 +1131,12 @@ async function handleHiveCommand(ctx) {
     if (VERBOSE) console.log(`[VERBOSE] /hive: Normalized ${p.type} URL to repo URL: ${normalizedArgs[0]}`);
   } else if (validation.normalizedUrl && validation.normalizedUrl !== userArgs[0]) normalizedArgs[0] = validation.normalizedUrl;
 
-  // Merge user args with overrides
-  const args = mergeArgsWithOverrides(normalizedArgs, hiveOverrides);
+  const { backend: hivePerCommandIsolation, filteredArgs: normalizedArgsWithoutIsolation } = extractIsolationFromArgs(normalizedArgs); // issue #1534
+  if (hivePerCommandIsolation && !isValidPerCommandIsolation(hivePerCommandIsolation)) {
+    await safeReply(ctx, `❌ Invalid --isolation value '${escapeMarkdown(hivePerCommandIsolation)}'. Must be: screen, tmux, or docker`, { reply_to_message_id: ctx.message.message_id });
+    return;
+  }
+  const args = mergeArgsWithOverrides(normalizedArgsWithoutIsolation, hiveOverrides);
 
   // Determine tool from args (default: claude)
   let hiveTool = 'claude';
@@ -1195,7 +1195,7 @@ async function handleHiveCommand(ctx) {
   }
 
   const startingMessage = await safeReply(ctx, `🚀 Starting hive command...\n\n${infoBlock}`, { reply_to_message_id: ctx.message.message_id });
-  await executeAndUpdateMessage(ctx, startingMessage, 'hive', args, infoBlock);
+  await executeAndUpdateMessage(ctx, startingMessage, 'hive', args, infoBlock, hivePerCommandIsolation);
 }
 
 bot.command(/^hive$/i, handleHiveCommand);

package/src/telegram-isolation.lib.mjs

@@ -0,0 +1,88 @@
+/**
+ * Per-command isolation support for Telegram bot commands.
+ *
+ * Extracts --isolation <backend> from user args in /solve and /hive commands,
+ * so it can be used for execution isolation (via $ CLI from start-command)
+ * instead of being forwarded to solve/hive as an unknown argument.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1534
+ * @see https://github.com/link-assistant/hive-mind/pull/390
+ */
+
+const VALID_ISOLATION_BACKENDS = ['screen', 'tmux', 'docker'];
+
+/**
+ * Extract --isolation <backend> from args array.
+ * Returns { backend: string|null, filteredArgs: string[] }.
+ * The --isolation flag is a per-command execution option (not a solve/hive option),
+ * so it must be stripped before passing args to solve/hive validation and execution.
+ */
+export function extractIsolationFromArgs(args) {
+  const filteredArgs = [];
+  let backend = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--isolation' && i + 1 < args.length) {
+      backend = args[i + 1].trim().toLowerCase();
+      i++; // Skip the value
+    } else if (args[i].startsWith('--isolation=')) {
+      backend = args[i].substring('--isolation='.length).trim().toLowerCase();
+    } else {
+      filteredArgs.push(args[i]);
+    }
+  }
+  return { backend, filteredArgs };
+}
+
+/**
+ * Validate an isolation backend value.
+ * @param {string} backend
+ * @returns {boolean}
+ */
+export function isValidPerCommandIsolation(backend) {
+  return VALID_ISOLATION_BACKENDS.includes(backend);
+}
+
+/**
+ * Get the effective isolation backend and runner for a command execution.
+ * Per-command isolation takes precedence over bot-level ISOLATION_BACKEND.
+ *
+ * @param {string|null} perCommandIsolation - Per-command --isolation value from user args
+ * @param {string} botIsolationBackend - Bot-level ISOLATION_BACKEND
+ * @param {object|null} botIsolationRunner - Bot-level isolation runner module
+ * @param {boolean} verbose - Enable verbose logging
+ * @returns {Promise<{backend: string, runner: object}|null>}
+ */
+export async function resolveIsolation(perCommandIsolation, botIsolationBackend, botIsolationRunner, verbose = false) {
+  const effectiveBackend = perCommandIsolation || botIsolationBackend;
+  if (!effectiveBackend) return null;
+
+  let runner = botIsolationRunner;
+  if (!runner) {
+    try {
+      runner = await import('./isolation-runner.lib.mjs');
+      if (verbose) console.log('[VERBOSE] Dynamically imported isolation-runner for per-command isolation');
+    } catch (e) {
+      console.error(`[telegram-bot] Failed to import isolation-runner: ${e.message}`);
+      return null;
+    }
+  }
+
+  return { backend: effectiveBackend, runner };
+}
+
+/**
+ * Create a queue execute callback that supports per-command isolation.
+ * Falls back to the provided fallback callback when no isolation is active.
+ */
+export function createIsolationAwareQueueCallback(botIsolationBackend, botIsolationRunner, trackSession, fallbackCallback, verbose) {
+  return async item => {
+    const iso = await resolveIsolation(item.perCommandIsolation, botIsolationBackend, botIsolationRunner, verbose);
+    if (iso) {
+      const sid = iso.runner.generateSessionId();
+      const r = await iso.runner.executeWithIsolation(item.command || 'solve', item.args, { backend: iso.backend, sessionId: sid, verbose });
+      if (r.success) trackSession(sid, { chatId: item.ctx?.chat?.id, messageId: item.messageInfo?.messageId, startTime: new Date(), url: item.url, command: item.command || 'solve', isolationBackend: iso.backend, sessionId: sid }, verbose);
+      return { ...r, output: r.output || `session: ${sid}` };
+    }
+    return fallbackCallback(item);
+  };
+}