@link-assistant/hive-mind 2.9.2 → 2.10.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 2.10.1
+
+### Patch Changes
+
+- a9b0967: Fix killed Telegram task resume instructions by recovering the last tool session from the complete task log, rejecting unrelated shared-directory session logs, and preserving the original slash-command alias through queued and restarted sessions.
+
+## 2.10.0
+
+### Minor Changes
+
+- a1a1f63: Allow `--model formal-ai` with every supported agentic CLI, route execution through `formal-ai with`, and provide a persistent Formal AI Docker service.
+
 ## 2.9.2
 
 ### Patch Changes

package/README.hi.md

@@ -502,6 +502,11 @@ Free Models via Kilo Gateway (with --tool agent):
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-5-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-4.5-air-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/deepseek-r1-free
+
+# किसी भी समर्थित agentic CLI को Formal AI के माध्यम से route करें
+/solve https://github.com/owner/repo/issues/123 --tool agent --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool codex --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool claude --model formal-ai
 ```
 
 > **📖 मुफ्त मॉडल गाइड**: OpenCode Zen और Kilo Gateway प्रदाताओं सहित सभी मुफ्त मॉडलों के बारे में व्यापक जानकारी के लिए [docs/FREE_MODELS.hi.md](./docs/FREE_MODELS.hi.md) देखें।

package/README.md

@@ -506,6 +506,11 @@ Free Models via Kilo Gateway (with --tool agent):
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-5-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-4.5-air-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/deepseek-r1-free
+
+# Route any supported agentic CLI through Formal AI
+/solve https://github.com/owner/repo/issues/123 --tool agent --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool codex --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool claude --model formal-ai
 ```
 
 Current tool defaults in Hive Mind:

package/README.ru.md

@@ -503,6 +503,11 @@ Free Models via Kilo Gateway (with --tool agent):
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-5-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-4.5-air-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/deepseek-r1-free
+
+# Маршрутизация любого поддерживаемого агентного CLI через Formal AI
+/solve https://github.com/owner/repo/issues/123 --tool agent --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool codex --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool claude --model formal-ai
 ```
 
 > **📖 Руководство по бесплатным моделям**: см. [docs/FREE_MODELS.ru.md](./docs/FREE_MODELS.ru.md) для получения полной информации обо всех бесплатных моделях, включая провайдеры OpenCode Zen и Kilo Gateway.

package/README.zh.md

@@ -499,6 +499,11 @@ Free Models via Kilo Gateway (with --tool agent):
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-5-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/glm-4.5-air-free
 /solve https://github.com/owner/repo/issues/123 --tool agent --model kilo/deepseek-r1-free
+
+# 通过 Formal AI 路由任意受支持的 Agent CLI
+/solve https://github.com/owner/repo/issues/123 --tool agent --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool codex --model formal-ai
+/solve https://github.com/owner/repo/issues/123 --tool claude --model formal-ai
 ```
 
 > **📖 免费模型指南**：有关所有免费模型（包括 OpenCode Zen 和 Kilo Gateway 提供商）的全面信息，请参见 [docs/FREE_MODELS.zh.md](./docs/FREE_MODELS.zh.md)。

package/package.json

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

package/src/agent.lib.mjs

@@ -22,6 +22,7 @@ import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import Decimal from 'decimal.js-light';
 import semver from 'semver';
 import { agentModels, defaultModels, freeToBaseModelMap } from './models/index.mjs';
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { checkPlaywrightMcpPackageAvailability, getAgentPlaywrightMcpDisableEnv } from './playwright-mcp.lib.mjs';
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage } from './agent-token-usage.lib.mjs';
 import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
@@ -502,6 +503,11 @@ export const executeAgentCommand = async params => {
 
     // Map model alias to full ID
     const mappedModel = mapModelToId(argv.model);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'agent',
+      model: argv.model,
+      toolPath: agentPath,
+    });
 
     // Build agent command arguments
     let agentArgs = `--model ${mappedModel}`;
@@ -546,30 +552,31 @@ export const executeAgentCommand = async params => {
         await fs.writeFile(promptFile, combinedPrompt);
       }
 
-      const fullCommand = streamingInput ? `(cd "${tempDir}" && ${agentPath} ${agentArgs})` : `(cd "${tempDir}" && cat "${promptFile}" | ${agentPath} ${agentArgs})`;
+      const fullCommand = streamingInput ? `(cd "${tempDir}" && ${toolInvocation.displayCommand} ${agentArgs})` : `(cd "${tempDir}" && cat "${promptFile}" | ${toolInvocation.displayCommand} ${agentArgs})`;
 
-      await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-      await log(`${fullCommand}`);
-      await log('');
+      const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+      if (preparedResult) return preparedResult;
 
       if (streamingInput) {
-        execCommand = $({
+        const commandRunner = $({
           cwd: tempDir,
           stdin: 'pipe',
           mirror: false,
           env: agentEnv,
-        })`${agentPath} ${agentArgs}`;
+        });
+        execCommand = toolInvocation.formalAi ? commandRunner`${toolInvocation.command} ${toolInvocation.args} ${agentArgs}` : commandRunner`${toolInvocation.command} ${agentArgs}`;
         const attached = await attachStreamingInput(bidirectionalHandler, execCommand, combinedPrompt, log, !!argv.verbose, { toolLabel: 'Agent' });
         if (!attached) {
           throw new Error('Agent live stream-json input requested, but stdin attachment failed');
         }
       } else {
         // Pipe the prompt file to agent via stdin for the legacy one-shot path.
-        execCommand = $({
+        const commandRunner = $({
           cwd: tempDir,
           mirror: false,
           env: agentEnv,
-        })`cat ${promptFile} | ${agentPath} ${agentArgs}`;
+        });
+        execCommand = toolInvocation.formalAi ? commandRunner`cat ${promptFile} | ${toolInvocation.command} ${toolInvocation.args} ${agentArgs}` : commandRunner`cat ${promptFile} | ${toolInvocation.command} ${agentArgs}`;
       }
 
       await log(`${formatAligned('📋', 'Command details:', '')}`);

package/src/claude.lib.mjs

@@ -22,6 +22,7 @@ import { buildSolveResumeCommand } from './solve.resume-command.lib.mjs'; // Iss
 import { SESSION_FORCE_KILLED_MARKER, postTrackedComment } from './tool-comments.lib.mjs'; // Issue #1625
 import { handleClaudeRuntimeSwitch } from './claude.runtime-switch.lib.mjs'; // see issue #1141
 import { CLAUDE_MODELS as availableModels, mapClaudeSubAgentModelToEnvValue } from './models/index.mjs'; // Issue #1221, #1978
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { buildMcpConfigWithoutPlaywright, ensureClaudePlaywrightMcpServer } from './playwright-mcp.lib.mjs';
 import { resolveClaudeSessionToolFlags } from './useless-tools.lib.mjs';
 import { ensureClaudeQuietConfig } from './claude-quiet-config.lib.mjs';
@@ -614,13 +615,13 @@ export const executeClaudeCommand = async params => {
     const progressMonitor = await initProgressMonitoring(argv, { owner, repo, prNumber, $, log }); // works with or without --interactive-mode
     let execCommand;
     const mappedModel = mapModelToId(argv.model);
+    const toolInvocation = resolveFormalAiToolInvocation({ tool: 'claude', model: argv.model, toolPath: claudePath });
     const resolvedPlanModel = argv.planModel ? mapModelToId(argv.planModel) : undefined; // Issue #1223
     const resolvedSubAgentModel = argv.subAgentModel ? mapClaudeSubAgentModelToEnvValue(argv.subAgentModel) : undefined; // Issue #1978
     const effectiveModel = resolvedPlanModel ? 'opusplan' : mappedModel;
     const resolvedExecutionModel = resolvedPlanModel ? mappedModel : undefined;
-    // Issue #1949: Let Claude Code handle transient overload (529) fallback via its own
-    // `--fallback-model` flag (it re-tries the primary each turn) instead of us swapping
-    // `--model`. Only for plain `--model` runs (not opusplan) with a distinct fallback.
+    // Issue #1949: Let Claude Code's `--fallback-model` handle transient overloads and retry
+    // the primary each turn. Only for plain `--model` runs with a distinct fallback.
     const mappedFallbackModel = argv.fallbackModel ? mapModelToId(argv.fallbackModel) : undefined;
     const useClaudeFallbackModel = !resolvedPlanModel && mappedFallbackModel && mappedFallbackModel !== effectiveModel;
     let claudeArgs = `--output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel}`;
@@ -650,10 +651,9 @@ export const executeClaudeCommand = async params => {
     } else {
       claudeArgs += ` -p "${escapedPromptForAttempt}" --append-system-prompt "${escapedSystemPrompt}"`;
     }
-    const fullCommand = `(cd "${tempDir}" && ${claudePath} ${claudeArgs} | jq -c .)`;
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(`${fullCommand}`);
-    await log('');
+    const fullCommand = `(cd "${tempDir}" && ${toolInvocation.displayCommand} ${claudeArgs} | jq -c .)`;
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
     if (argv.verbose) {
       await log(`📋 User prompt:\n---BEGIN USER PROMPT---\n${promptForAttempt}\n---END USER PROMPT---`, { verbose: true });
       await log(`📋 System prompt:\n---BEGIN SYSTEM PROMPT---\n${systemPrompt}\n---END SYSTEM PROMPT---`, { verbose: true });
@@ -684,15 +684,15 @@ export const executeClaudeCommand = async params => {
       if (useClaudeFallbackModel && argv.verbose) await log(`📊 Claude --fallback-model: ${mappedFallbackModel} (Issue #1949 — primary --model ${effectiveModel} stays stable across overload retries)`, { verbose: true });
       if (argv.resume) {
         const simpleEscapedPrompt = promptForAttempt.replace(/"/g, '\\"');
-        execCommand = $({ cwd: tempDir, mirror: false, env: claudeEnv })`${claudePath} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = toolInvocation.formalAi ? $({ cwd: tempDir, mirror: false, env: claudeEnv })`${toolInvocation.command} ${toolInvocation.args} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"` : $({ cwd: tempDir, mirror: false, env: claudeEnv })`${toolInvocation.command} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"`;
       } else if (streamingInput) {
         // Issue #817: Drive Claude via --input-format stream-json on a pipe
         // stdin. Initial prompt + later PR comments are written as NDJSON
         // frames by attachStreamingInput (see bidirectional-interactive.lib.mjs).
         const streamingInputArgs = ['-p', '--input-format', 'stream-json'];
-        execCommand = $({ cwd: tempDir, stdin: 'pipe', mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} ${streamingInputArgs} --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = toolInvocation.formalAi ? $({ cwd: tempDir, stdin: 'pipe', mirror: false, env: claudeEnv })`${toolInvocation.command} ${toolInvocation.args} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} ${streamingInputArgs} --append-system-prompt "${simpleEscapedSystem}"` : $({ cwd: tempDir, stdin: 'pipe', mirror: false, env: claudeEnv })`${toolInvocation.command} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} ${streamingInputArgs} --append-system-prompt "${simpleEscapedSystem}"`;
       } else {
-        execCommand = $({ cwd: tempDir, stdin: promptForAttempt, mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = toolInvocation.formalAi ? $({ cwd: tempDir, stdin: promptForAttempt, mirror: false, env: claudeEnv })`${toolInvocation.command} ${toolInvocation.args} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"` : $({ cwd: tempDir, stdin: promptForAttempt, mirror: false, env: claudeEnv })`${toolInvocation.command} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"`;
       }
       if (streamingInput) {
         await attachStreamingInput(bidirectionalHandler, execCommand, promptForAttempt, log, !!argv.verbose);

package/src/codex.lib.mjs

@@ -31,6 +31,7 @@ import { initProgressMonitoring } from './solve.progress-monitoring.lib.mjs';
 import { ensureCodexPlaywrightMcpServer, getCodexPlaywrightMcpDisableConfigArgs } from './playwright-mcp.lib.mjs';
 import { fetchModelInfo } from './model-info.lib.mjs';
 import { defaultModels } from './models/index.mjs';
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { parseSubSessionSize, buildCodexSubSessionSizeConfigArgs, buildCodexDisable1mContextConfigArgs } from './sub-session-size.lib.mjs'; // Issue #1706
 import { getCumulativeContextInputTokens } from './context-fill.lib.mjs';
@@ -816,6 +817,11 @@ export const executeCodexCommand = async params => {
 
     let execCommand;
     const mappedModel = mapModelToId(argv.model);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'codex',
+      model: argv.model,
+      toolPath: codexPath,
+    });
     const { reasoningEffort, source: reasoningEffortSource, rolloutTokenBudget } = resolveCodexReasoningEffort(argv);
     const isResumeMode = !!argv.resume;
     const codexEnv = applyCodexCapabilityEnv(capabilityPreflight?.codexBaseEnv || getCodexExecEnv(argv.verbose), {
@@ -889,11 +895,10 @@ export const executeCodexCommand = async params => {
       if (subSessionSizeArgs.length) await log(`📊 Codex --sub-session-size: ${subSessionSizeArgs.join(' ')}`, { verbose: true });
     }
 
-    const fullCommand = `(cd ${shellQuote(tempDir)} && cat ${shellQuote(promptFile)} | ${codexPath} ${codexArgs})`;
+    const fullCommand = `(cd ${shellQuote(tempDir)} && cat ${shellQuote(promptFile)} | ${toolInvocation.displayCommand} ${codexArgs})`;
 
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(`${fullCommand}`);
-    await log('');
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
 
     try {
       let interactiveHandler = null;

package/src/formal-ai.lib.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { FORMAL_AI_MODEL_ALIAS, isFormalAiModel } from './models/index.mjs';
+
+const execFileAsync = promisify(execFile);
+
+export const FORMAL_AI_SUPPORTED_TOOLS = Object.freeze(['claude', 'agent', 'opencode', 'codex', 'qwen', 'gemini']);
+export const DEFAULT_FORMAL_AI_PATH = 'formal-ai';
+
+const SAFE_SHELL_WORD = /^[a-zA-Z0-9_\-./=,+@:]+$/;
+
+const shellQuote = value => {
+  const stringValue = String(value);
+  if (SAFE_SHELL_WORD.test(stringValue)) return stringValue;
+  return `'${stringValue.replaceAll("'", "'\\''")}'`;
+};
+
+const normalizeExternalBaseUrl = value => {
+  if (!value) return null;
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`HIVE_MIND_FORMAL_AI_BASE_URL must be a valid HTTP(S) URL, received "${value}"`);
+  }
+
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.pathname !== '/' || parsed.search || parsed.hash) {
+    throw new Error('HIVE_MIND_FORMAL_AI_BASE_URL must be an HTTP(S) origin without credentials, a path, a query, or a fragment');
+  }
+
+  return parsed.origin;
+};
+
+/**
+ * Resolve the executable and leading arguments for one Hive tool invocation.
+ * Formal AI owns the temporary client configuration and forwards all remaining
+ * arguments to the selected agentic CLI unchanged.
+ */
+export const resolveFormalAiToolInvocation = ({ tool, model, toolPath, env = process.env }) => {
+  if (!isFormalAiModel(model)) {
+    return {
+      command: toolPath,
+      args: [],
+      displayCommand: shellQuote(toolPath),
+      formalAi: false,
+      baseUrl: null,
+    };
+  }
+
+  if (!FORMAL_AI_SUPPORTED_TOOLS.includes(tool)) {
+    throw new Error(`Formal AI dispatch does not support Hive tool "${tool}"`);
+  }
+
+  const command = env.HIVE_MIND_FORMAL_AI_PATH?.trim() || DEFAULT_FORMAL_AI_PATH;
+  const baseUrl = normalizeExternalBaseUrl(env.HIVE_MIND_FORMAL_AI_BASE_URL);
+  const args = ['with'];
+
+  if (baseUrl) {
+    args.push('--no-start-server', '--base-url', baseUrl);
+  }
+  args.push(tool);
+
+  return {
+    command,
+    args,
+    displayCommand: [command, ...args].map(shellQuote).join(' '),
+    formalAi: true,
+    baseUrl,
+  };
+};
+
+/**
+ * Check both the wrapper and the selected native CLI without starting a model
+ * server or spending a model request.
+ */
+export const validateFormalAiToolConnection = async (tool, { env = process.env, run = execFileAsync, timeoutMs = 30_000 } = {}) => {
+  const invocation = resolveFormalAiToolInvocation({
+    tool,
+    model: FORMAL_AI_MODEL_ALIAS,
+    toolPath: tool,
+    env,
+  });
+  const args = ['with', '--no-start-server', tool, '--version'];
+
+  try {
+    const result = await run(invocation.command, args, {
+      encoding: 'utf8',
+      env: { ...process.env, ...env },
+      timeout: timeoutMs,
+    });
+    return {
+      valid: true,
+      command: invocation.command,
+      args,
+      version: result?.stdout?.trim() || null,
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      command: invocation.command,
+      args,
+      error: error?.stderr?.trim() || error?.message || String(error),
+      code: error?.code,
+    };
+  }
+};
+
+export const isPrepareOnly = argv => !!(argv?.dryRun || argv?.onlyPrepareCommand);
+
+export const createPreparedToolResult = preparedCommand => ({
+  success: true,
+  preparedOnly: true,
+  preparedCommand,
+  sessionId: null,
+  limitReached: false,
+  errorDuringExecution: false,
+});
+
+export const logPreparedToolCommand = async ({ argv, fullCommand, log, formatAligned }) => {
+  await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
+  await log(fullCommand);
+  await log('');
+
+  if (!isPrepareOnly(argv)) return null;
+
+  await log('🧪 Command prepared; AI execution skipped.');
+  return createPreparedToolResult(fullCommand);
+};

package/src/gemini.lib.mjs

@@ -18,6 +18,7 @@ import { buildSolveResumeCommand } from './solve.resume-command.lib.mjs'; // Iss
 const __geminiBuildSolveResumeCmd = (argv, sessionId, tempDir) => (sessionId && argv?.url ? buildSolveResumeCommand({ issueUrl: argv.url, sessionId, tool: 'gemini', model: argv.model, fallbackModel: argv.fallbackModel, tempDir }) : null);
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { defaultModels, geminiModels } from './models/index.mjs';
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { checkPlaywrightMcpPackageAvailability } from './playwright-mcp.lib.mjs';
 import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { getCumulativeContextInputTokens, toTokenCount } from './context-fill.lib.mjs';
@@ -423,6 +424,11 @@ export const executeGeminiCommand = async params => {
     await log(`   Load: ${resourcesBefore.load}`, { verbose: true });
 
     const mappedModel = mapModelToId(argv.model || defaultModels.gemini);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'gemini',
+      model: argv.model || defaultModels.gemini,
+      toolPath: geminiPath,
+    });
     const combinedPrompt = systemPrompt ? `${systemPrompt}\n\n${prompt}` : prompt;
 
     if (argv.resume) {
@@ -432,11 +438,11 @@ export const executeGeminiCommand = async params => {
     // Issue #1809: build args via shared helper so verbose/sandbox/include-dirs
     // toggles stay consistent between the logged command and the real invocation.
     const geminiArgList = buildGeminiArgs(argv, mappedModel, { tempDir, workspaceTmpDir });
-    const fullCommand = `(cd ${shellQuote(tempDir)} && ${geminiPath} ${geminiArgList.map(shellQuote).join(' ')} <<< <prompt>)`;
+    const fullGeminiArgList = [...toolInvocation.args, ...geminiArgList];
+    const fullCommand = `(cd ${shellQuote(tempDir)} && ${toolInvocation.displayCommand} ${geminiArgList.map(shellQuote).join(' ')} <<< <prompt>)`;
 
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(fullCommand);
-    await log('');
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
 
     let geminiJsonState = {};
     let allOutput = '';
@@ -455,7 +461,7 @@ export const executeGeminiCommand = async params => {
         cwd: tempDir,
         stdin: combinedPrompt,
         mirror: false,
-      })`${geminiPath} ${geminiArgList}`;
+      })`${toolInvocation.command} ${fullGeminiArgList}`;
 
       await log(`${formatAligned('📋', 'Command details:', '')}`);
       await log(formatAligned('📂', 'Working directory:', tempDir, 2));

package/src/isolation-runner.lib.mjs

@@ -15,6 +15,7 @@ import { ensureUseM } from './use-m-bootstrap.lib.mjs';
 
 import crypto from 'crypto';
 import { spawn } from 'node:child_process';
+import { lookup as lookupHost } from 'node:dns/promises';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -53,6 +54,7 @@ const HIVE_MIND_IMAGE_REPO = 'konard/hive-mind';
 const HIVE_MIND_DIND_IMAGE_REPO = 'konard/hive-mind-dind';
 const DEFAULT_HIVE_MIND_IMAGE_TAG = 'latest';
 const DOCKER_CONTAINER_HOME = '/home/box';
+const FORMAL_AI_COMPOSE_HOSTNAME = 'link-assistant-formal-ai';
 // Default path where the host Docker socket is bind-mounted inside a DinD
 // container so box's host-image passthrough can copy host images into the
 // nested daemon. Matches box's own DIND_HOST_DOCKER_SOCK default. The deploy
@@ -227,6 +229,44 @@ function resolveImageVariant(image, env = process.env) {
   return image.includes('hive-mind-dind') ? 'dind' : env.HIVE_MIND_IMAGE_VARIANT || 'regular';
 }
 
+/**
+ * Resolve an outer Compose HTTP service before handing its origin to a nested
+ * Docker daemon. The nested daemon has its own DNS namespace, but it can route
+ * to the outer service's address through the parent container.
+ *
+ * HTTPS names are deliberately preserved for certificate verification.
+ */
+export async function resolveFormalAiIsolationEnv(env = process.env, { lookup = lookupHost } = {}) {
+  const baseUrl = env.HIVE_MIND_FORMAL_AI_BASE_URL;
+  if (!baseUrl) return env;
+
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    return env;
+  }
+
+  if (parsed.protocol !== 'http:' || parsed.hostname !== FORMAL_AI_COMPOSE_HOSTNAME) {
+    return env;
+  }
+
+  try {
+    const addresses = await lookup(parsed.hostname, { all: true, verbatim: true });
+    const selected = addresses.find(candidate => candidate.family === 4) || addresses[0];
+    if (!selected?.address) return env;
+
+    const host = selected.family === 6 ? `[${selected.address}]` : selected.address;
+    return {
+      ...env,
+      HIVE_MIND_FORMAL_AI_BASE_URL: `${parsed.protocol}//${host}${parsed.port ? `:${parsed.port}` : ''}`,
+    };
+  } catch {
+    // Keep the hostname for deployments whose nested DNS can resolve it.
+    return env;
+  }
+}
+
 /**
  * Build the `$` (start-command) arguments that launch a Docker-isolated task
  * using start-command's NATIVE Docker backend (`$ --isolated docker`).
@@ -264,6 +304,13 @@ export function buildDockerIsolationStartArgs(command, args = [], options = {})
   // working directory comes from the image's WORKDIR.
   startArgs.push('-e', `HOME=${DOCKER_CONTAINER_HOME}`, '-e', `HIVE_MIND_PARENT_SESSION_ID=${sessionId || ''}`, '-e', `HIVE_MIND_IMAGE_VARIANT=${resolveImageVariant(image, env)}`);
 
+  // A persistent Formal AI server normally runs beside the Telegram/root
+  // container. Docker-isolated `/solve` jobs must receive the same endpoint;
+  // otherwise the wrapper starts a per-job server and loses shared memory.
+  if (env.HIVE_MIND_FORMAL_AI_BASE_URL) {
+    startArgs.push('-e', `HIVE_MIND_FORMAL_AI_BASE_URL=${env.HIVE_MIND_FORMAL_AI_BASE_URL}`);
+  }
+
   for (const mount of getDockerIsolationAuthMounts({ tool, env, homeDir, existsSync })) {
     startArgs.push('--volume', `${mount.source}:${mount.target}`);
   }
@@ -620,14 +667,21 @@ export async function executeWithIsolation(command, args, options = {}) {
     console.log(`[VERBOSE] isolation-runner: Backend: ${backend}, Session ID: ${sessionId}`);
   }
 
-  const startCommandArgs = buildStartCommandArgs(command, args, { ...options, sessionId });
+  const effectiveOptions =
+    backend === 'docker'
+      ? {
+          ...options,
+          env: await resolveFormalAiIsolationEnv(options.env || process.env),
+        }
+      : options;
+  const startCommandArgs = buildStartCommandArgs(command, args, { ...effectiveOptions, sessionId });
 
   if (verbose) {
     console.log(`[VERBOSE] isolation-runner: ${[binPath, ...startCommandArgs].map(shellQuote).join(' ')}`);
     if (backend === 'docker') {
-      const env = options.env || process.env;
+      const env = effectiveOptions.env || process.env;
       const image = getDockerIsolationImage({ env });
-      const mounts = getDockerIsolationAuthMounts({ tool: options.tool, env, homeDir: options.homeDir || os.homedir(), existsSync: options.existsSync || fs.existsSync });
+      const mounts = getDockerIsolationAuthMounts({ tool: effectiveOptions.tool, env, homeDir: effectiveOptions.homeDir || os.homedir(), existsSync: effectiveOptions.existsSync || fs.existsSync });
       console.log('[VERBOSE] isolation-runner: Docker isolation backend: native ($ --isolated docker)');
       console.log(`[VERBOSE] isolation-runner: Docker isolation image: ${image}`);
       console.log(`[VERBOSE] isolation-runner: Docker isolation privileged: ${shouldRunPrivilegedDockerIsolation(image, env)}`);

package/src/models/index.mjs

@@ -28,10 +28,26 @@ const execFileAsync = promisify(execFile);
 
 // ─── MODEL DATA ──────────────────────────────────────────────────────────────
 
+export const FORMAL_AI_MODEL_ALIAS = 'formal-ai';
+export const FORMAL_AI_PROVIDER_MODEL_ID = 'formalai/formal-ai';
+
+const formalAiNativeModelAliases = {
+  [FORMAL_AI_MODEL_ALIAS]: FORMAL_AI_MODEL_ALIAS,
+  [FORMAL_AI_PROVIDER_MODEL_ID]: FORMAL_AI_MODEL_ALIAS,
+};
+
+const formalAiProviderModelAliases = {
+  [FORMAL_AI_MODEL_ALIAS]: FORMAL_AI_PROVIDER_MODEL_ID,
+  [FORMAL_AI_PROVIDER_MODEL_ID]: FORMAL_AI_PROVIDER_MODEL_ID,
+};
+
+export const isFormalAiModel = model => model === FORMAL_AI_MODEL_ALIAS || model === FORMAL_AI_PROVIDER_MODEL_ID;
+
 // Claude models (Anthropic API)
 // Updated for Opus 4.5/4.6/4.7/4.8/5, Sonnet 4.6/5, and Fable 5 / Mythos 5 support
 // (Issue #1221, Issue #1238, Issue #1329, Issue #1433, Issue #1620, Issue #1832, Issue #1875, Issue #2003, Issue #2096)
 export const claudeModels = {
+  ...formalAiNativeModelAliases,
   sonnet: 'claude-sonnet-5', // Sonnet 5 (Issue #2003)
   opus: 'claude-opus-5', // Opus 5 (default, Issue #2096)
   haiku: 'claude-haiku-4-5-20251001', // Haiku 4.5
@@ -72,6 +88,7 @@ export const claudeModels = {
 // Issue #1543: Added qwen3.6-plus-free (former default) and nemotron-3-super-free per agent PR #234
 // Issue #1563: qwen3.6-plus-free free promotion ended (April 2026), nemotron-3-super-free is now default per agent PR #243
 export const agentModels = {
+  ...formalAiProviderModelAliases,
   // OpenCode Zen free models (current)
   grok: 'opencode/grok-code',
   'grok-code': 'opencode/grok-code',
@@ -111,6 +128,7 @@ export const agentModels = {
 
 // OpenCode models (OpenCode API)
 export const opencodeModels = {
+  ...formalAiProviderModelAliases,
   gpt4: 'openai/gpt-4',
   gpt4o: 'openai/gpt-4o',
   claude: 'anthropic/claude-3-5-sonnet',
@@ -124,6 +142,7 @@ export const opencodeModels = {
 
 // Codex models (OpenAI API)
 export const codexModels = {
+  ...formalAiNativeModelAliases,
   gpt5: 'gpt-5',
   'gpt-5': 'gpt-5',
   'gpt-5.5': 'gpt-5.5',
@@ -196,6 +215,7 @@ export const CODEX_MODEL_VARIANTS = getCodexModelVariants();
 
 // Qwen Code models
 export const qwenModels = {
+  ...formalAiNativeModelAliases,
   qwen: 'qwen3-coder-plus',
   'qwen-coder': 'qwen3-coder-plus',
   qwen3: 'qwen3-coder-plus',
@@ -210,6 +230,7 @@ export const qwenModels = {
 // Keep aliases aligned with the Gemini CLI model aliases documented in
 // docs/cli/cli-reference.md: auto, pro, flash, and flash-lite.
 export const geminiModels = {
+  ...formalAiNativeModelAliases,
   auto: 'auto',
   gemini: 'gemini-2.5-flash',
   flash: 'gemini-2.5-flash',
@@ -492,6 +513,10 @@ export const mapModelForTool = (tool, model) => {
  * @returns {boolean} True if the model is compatible with the tool
  */
 export const isModelCompatibleWithTool = (tool, model) => {
+  if (isFormalAiModel(model)) {
+    return ['claude', 'agent', 'opencode', 'codex', 'qwen', 'gemini'].includes(tool);
+  }
+
   const mappedModel = mapModelForTool(tool, model);
 
   switch (tool) {
@@ -539,12 +564,12 @@ export const getValidModelsForTool = tool => {
 // Primary (non-alias, non-deprecated) short names shown in CLI help descriptions
 // These are the recommended model names users should see in --model help text
 export const primaryModelNames = {
-  claude: ['opus', 'sonnet', 'haiku', 'opusplan', 'fable'],
-  opencode: ['grok', 'gpt4o'],
-  codex: ['gpt-5.6-sol', 'gpt-5.5', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.4', 'gpt-5.4-mini', 'gpt-5.3-codex-spark'],
-  agent: ['nemotron-3-super-free', 'minimax-m2.5-free', 'big-pickle', 'gpt-5-nano', 'glm-5-free', 'deepseek-r1-free'],
-  qwen: ['qwen3-coder-plus', 'qwen3-coder', 'qwen3-coder-flash'],
-  gemini: ['flash', 'pro', 'flash-lite', 'auto'],
+  claude: ['opus', 'sonnet', 'haiku', 'opusplan', 'fable', FORMAL_AI_MODEL_ALIAS],
+  opencode: ['grok', 'gpt4o', FORMAL_AI_MODEL_ALIAS],
+  codex: ['gpt-5.6-sol', 'gpt-5.5', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.4', 'gpt-5.4-mini', 'gpt-5.3-codex-spark', FORMAL_AI_MODEL_ALIAS],
+  agent: ['nemotron-3-super-free', 'minimax-m2.5-free', 'big-pickle', 'gpt-5-nano', 'glm-5-free', 'deepseek-r1-free', FORMAL_AI_MODEL_ALIAS],
+  qwen: ['qwen3-coder-plus', 'qwen3-coder', 'qwen3-coder-flash', FORMAL_AI_MODEL_ALIAS],
+  gemini: ['flash', 'pro', 'flash-lite', 'auto', FORMAL_AI_MODEL_ALIAS],
 };
 
 /**

package/src/opencode.lib.mjs

@@ -20,6 +20,7 @@ import { timeouts, retryLimits } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { opencodeModels, defaultModels } from './models/index.mjs';
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { checkPlaywrightMcpPackageAvailability, getOpenCodePlaywrightMcpDisableEnv } from './playwright-mcp.lib.mjs';
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage as parseOpenCodeTokenUsage } from './agent-token-usage.lib.mjs';
 import { calculateAgentPricing } from './agent.lib.mjs';
@@ -212,34 +213,6 @@ export const executeOpenCodeCommand = async params => {
       }
     }
 
-    // Create OpenCode configuration file with unrestricted permissions
-    // This allows OpenCode to access files outside the working directory without prompting
-    // Fixes issue #755: "Permission required to run: Access file outside working directory"
-    // Reference: https://opencode.ai/docs/config - see permissions documentation
-    const opencodeConfigPath = path.join(tempDir, 'opencode.json');
-    const opencodeConfig = {
-      $schema: 'https://opencode.ai/config.json',
-      permission: {
-        // All tool permissions set to 'allow' for unrestricted autonomous execution
-        // See: https://github.com/sst/opencode - permission options: "allow", "ask", "deny"
-        edit: 'allow', // File modification operations
-        bash: 'allow', // Command execution
-        webfetch: 'allow', // Web page retrieval
-        skill: 'allow', // Custom skills execution
-        doom_loop: 'allow', // Allow repeated identical tool calls (default: ask)
-        external_directory: 'allow', // File operations outside working directory (default: ask)
-      },
-    };
-    try {
-      await fs.writeFile(opencodeConfigPath, JSON.stringify(opencodeConfig, null, 2));
-      if (argv.verbose) {
-        await log(`   Created OpenCode config: ${opencodeConfigPath}`, { verbose: true });
-        await log('   Permissions set: edit=allow, bash=allow, webfetch=allow, skill=allow, doom_loop=allow, external_directory=allow', { verbose: true });
-      }
-    } catch (configError) {
-      await log(`⚠️  Warning: Could not create OpenCode config file: ${configError.message}`, { level: 'warning' });
-    }
-
     // Take resource snapshot before execution
     const resourcesBefore = await getResourceSnapshot();
     await log('📈 System resources before execution:', { verbose: true });
@@ -259,6 +232,11 @@ export const executeOpenCodeCommand = async params => {
 
     // Map model alias to full ID
     const mappedModel = mapModelToId(argv.model);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'opencode',
+      model: argv.model,
+      toolPath: opencodePath,
+    });
     const streamingTokenUsage = createAgentTokenUsage();
 
     // Build opencode command arguments
@@ -280,11 +258,38 @@ export const executeOpenCodeCommand = async params => {
     await fs.writeFile(promptFile, combinedPrompt);
 
     // Build the full command - pipe the prompt file to opencode
-    const fullCommand = `(cd "${tempDir}" && cat "${promptFile}" | ${opencodePath} ${opencodeArgs})`;
+    const fullCommand = `(cd "${tempDir}" && cat "${promptFile}" | ${toolInvocation.displayCommand} ${opencodeArgs})`;
 
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(`${fullCommand}`);
-    await log('');
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
+
+    // Create OpenCode configuration file with unrestricted permissions
+    // This allows OpenCode to access files outside the working directory without prompting
+    // Fixes issue #755: "Permission required to run: Access file outside working directory"
+    // Reference: https://opencode.ai/docs/config - see permissions documentation
+    const opencodeConfigPath = path.join(tempDir, 'opencode.json');
+    const opencodeConfig = {
+      $schema: 'https://opencode.ai/config.json',
+      permission: {
+        // All tool permissions set to 'allow' for unrestricted autonomous execution
+        // See: https://github.com/sst/opencode - permission options: "allow", "ask", "deny"
+        edit: 'allow', // File modification operations
+        bash: 'allow', // Command execution
+        webfetch: 'allow', // Web page retrieval
+        skill: 'allow', // Custom skills execution
+        doom_loop: 'allow', // Allow repeated identical tool calls (default: ask)
+        external_directory: 'allow', // File operations outside working directory (default: ask)
+      },
+    };
+    try {
+      await fs.writeFile(opencodeConfigPath, JSON.stringify(opencodeConfig, null, 2));
+      if (argv.verbose) {
+        await log(`   Created OpenCode config: ${opencodeConfigPath}`, { verbose: true });
+        await log('   Permissions set: edit=allow, bash=allow, webfetch=allow, skill=allow, doom_loop=allow, external_directory=allow', { verbose: true });
+      }
+    } catch (configError) {
+      await log(`⚠️  Warning: Could not create OpenCode config file: ${configError.message}`, { level: 'warning' });
+    }
 
     const buildPricingInfo = async () => {
       const tokenUsage = streamingTokenUsage;
@@ -298,17 +303,19 @@ export const executeOpenCodeCommand = async params => {
     try {
       // Pipe the prompt file to opencode via stdin
       if (argv.resume) {
-        execCommand = $({
+        const commandRunner = $({
           cwd: tempDir,
           mirror: false,
           env: opencodeEnv,
-        })`cat ${promptFile} | ${opencodePath} run --format json --session ${argv.resume} --model ${mappedModel}`;
+        });
+        execCommand = toolInvocation.formalAi ? commandRunner`cat ${promptFile} | ${toolInvocation.command} ${toolInvocation.args} run --format json --session ${argv.resume} --model ${mappedModel}` : commandRunner`cat ${promptFile} | ${toolInvocation.command} run --format json --session ${argv.resume} --model ${mappedModel}`;
       } else {
-        execCommand = $({
+        const commandRunner = $({
           cwd: tempDir,
           mirror: false,
           env: opencodeEnv,
-        })`cat ${promptFile} | ${opencodePath} run --format json --model ${mappedModel}`;
+        });
+        execCommand = toolInvocation.formalAi ? commandRunner`cat ${promptFile} | ${toolInvocation.command} ${toolInvocation.args} run --format json --model ${mappedModel}` : commandRunner`cat ${promptFile} | ${toolInvocation.command} run --format json --model ${mappedModel}`;
       }
 
       await log(`${formatAligned('📋', 'Command details:', '')}`);

package/src/qwen.lib.mjs

@@ -19,6 +19,7 @@ import { timeouts, retryLimits } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { qwenModels, defaultModels } from './models/index.mjs';
+import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
 import { checkPlaywrightMcpPackageAvailability } from './playwright-mcp.lib.mjs';
 import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { getCumulativeContextInputTokens, getRestoredContextInputTokens, toTokenCount } from './context-fill.lib.mjs';
@@ -504,15 +505,19 @@ export const executeQwenCommand = async params => {
     await log(`   Load: ${resourcesBefore.load}`, { verbose: true });
 
     const mappedModel = mapModelToId(argv.model || defaultModels.qwen);
+    const toolInvocation = resolveFormalAiToolInvocation({
+      tool: 'qwen',
+      model: argv.model || defaultModels.qwen,
+      toolPath: qwenPath,
+    });
     const resumeSession = argv.resume || null;
     const resumeArgs = resumeSession ? ` --resume ${shellQuote(resumeSession)}` : '';
     const appendSystemPromptArg = systemPrompt ? ` --append-system-prompt "$(cat ${shellQuote(systemPromptFile)})"` : '';
-    const commandScript = `cd ${shellQuote(tempDir)} && ${shellQuote(qwenPath)} --model ${shellQuote(mappedModel)} --output-format stream-json --yolo${resumeArgs}${appendSystemPromptArg} --prompt "$(cat ${shellQuote(promptFile)})"`;
-    const fullCommand = `(cd "${tempDir}" && ${qwenPath} --model "${mappedModel}" --output-format stream-json --yolo${resumeSession ? ` --resume "${resumeSession}"` : ''}${systemPrompt ? ` --append-system-prompt "$(cat "${systemPromptFile}")"` : ''} --prompt "$(cat "${promptFile}")")`;
+    const commandScript = `cd ${shellQuote(tempDir)} && ${toolInvocation.displayCommand} --model ${shellQuote(mappedModel)} --output-format stream-json --yolo${resumeArgs}${appendSystemPromptArg} --prompt "$(cat ${shellQuote(promptFile)})"`;
+    const fullCommand = `(cd "${tempDir}" && ${toolInvocation.displayCommand} --model "${mappedModel}" --output-format stream-json --yolo${resumeSession ? ` --resume "${resumeSession}"` : ''}${systemPrompt ? ` --append-system-prompt "$(cat "${systemPromptFile}")"` : ''} --prompt "$(cat "${promptFile}")")`;
 
-    await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
-    await log(fullCommand);
-    await log('');
+    const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
+    if (preparedResult) return preparedResult;
 
     try {
       const execCommand = dollar({

package/src/session-monitor.lib.mjs

@@ -25,8 +25,7 @@ import { promisify } from 'util';
 import { formatSessionCompletionMessage, getSessionCompletionExitCode, classifySessionOutcome } from './work-session-formatting.lib.mjs';
 import { notifySubscribers, getSubscriberCount } from './telegram-subscribers.lib.mjs';
 import { classifyExitStatus, normalizeExitCode } from './session-status.lib.mjs';
-import path from 'node:path';
-import { readLastSessionIdFromLog, findLatestSessionLogId, buildResumeCommand, formatResumeSection } from './session-resume.lib.mjs';
+import { readLastSessionIdFromLog, buildResumeCommand, formatResumeSection } from './session-resume.lib.mjs';
 
 export { formatSessionCompletionMessage, getSessionCompletionExitCode } from './work-session-formatting.lib.mjs';
 
@@ -913,14 +912,11 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
             const logPath = statusResult?.logPath || sessionInfo?.logPath || null;
             // The id must be the AI TOOL's session id, not the isolation session
             //   id (sessionInfo.sessionId — wrong namespace for `solve --resume`).
-            //   Prefer the last `Session ID:` marker in the captured log; fall
-            //   back to the newest `<sessionId>.log` start-command wrote in the
-            //   same directory. If neither exists, offer no command (a bogus
-            //   resume id would be worse than none).
-            let lastSessionId = readLastSessionIdFromLog(logPath, { verbose });
-            if (!lastSessionId && logPath) {
-              lastSessionId = findLatestSessionLogId({ dir: path.dirname(logPath), verbose });
-            }
+            //   Scan backwards through this task's captured log for its last
+            //   `Session ID:` marker. Do not guess from neighboring UUID-named
+            //   logs: start-command stores unrelated tasks in the same backend
+            //   directory, which caused issue #2109's invalid resume id.
+            const lastSessionId = readLastSessionIdFromLog(logPath, { verbose });
             const resumeCommand = buildResumeCommand({ sessionInfo, lastSessionId });
             const resumeSection = formatResumeSection({ lastSessionId, command: resumeCommand });
             if (resumeSection) {

package/src/session-resume.lib.mjs

@@ -11,11 +11,10 @@
  *   1. **Use the LAST session id.** A single `/solve` run can spin up *many*
  *      tool sessions — auto-continue across usage-limit resets, uncommitted-
  *      changes restarts (`solve.watch`), and manual `--resume` chains. Every one
- *      prints a `Session ID:` marker to the captured log in chronological order,
- *      and start-command also renames the per-session log to `<sessionId>.log`.
+ *      prints a `Session ID:` marker to the captured log in chronological order.
  *      The most advanced context lives in the *last* of these, so resuming must
- *      pick the last id — never the first. {@link selectLastSessionId} /
- *      {@link findLatestSessionLogId} enforce that rule.
+ *      pick the last id — never the first. {@link selectLastSessionId} and
+ *      {@link readLastSessionIdFromLog} enforce that rule.
  *
  *   2. **Never storm.** Auto-resuming a killed session must be bounded so a job
  *      that reliably OOMs cannot spawn an infinite relaunch loop (which would be
@@ -41,6 +40,8 @@ const SESSION_ID_MARKER_RE = /Session ID:\s*`?([^\s`]+)`?/gi;
 // `<sessionId>.log` files start-command writes. Used to validate directory
 // scans so unrelated `*.log` files are never mistaken for a session.
 const SESSION_LOG_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEFAULT_LOG_SCAN_CHUNK_BYTES = 262144;
+const LOG_SCAN_OVERLAP_BYTES = 1024;
 
 /**
  * Extract every tool session id printed to a log, in the order they appear.
@@ -79,34 +80,52 @@ export function selectLastSessionId(text) {
 }
 
 /**
- * Read the LAST tool session id from a `/solve` execution log. Only the tail of
- * the file is scanned (the most recent session marker lives near the end), so
- * this stays cheap on multi-megabyte logs. Never throws — a missing/unreadable
- * log yields `null`.
+ * Read the LAST tool session id from a `/solve` execution log. The file is
+ * scanned backwards in bounded chunks: this normally stops after the tail
+ * chunk, while still finding a valid marker that precedes a long tool trace.
+ * Adjacent chunks overlap so a marker split at a chunk boundary is not lost.
+ * Never throws — a missing/unreadable log yields `null`.
  *
  * @param {string} logPath
  * @param {Object} [options]
  * @param {Object} [options.fsImpl=fs] - Injectable fs (for tests)
- * @param {number} [options.tailBytes=262144] - Trailing bytes to scan (256 KiB)
+ * @param {number} [options.tailBytes=262144] - Bytes per backwards scan chunk
  * @param {boolean} [options.verbose]
  * @returns {string|null}
  */
 export function readLastSessionIdFromLog(logPath, options = {}) {
-  const { fsImpl = fs, tailBytes = 262144, verbose = false } = options;
+  const { fsImpl = fs, tailBytes = DEFAULT_LOG_SCAN_CHUNK_BYTES, verbose = false } = options;
   if (!logPath) return null;
   try {
     const stat = fsImpl.statSync(logPath);
-    const start = Math.max(0, stat.size - tailBytes);
+    const chunkBytes = Number.isFinite(tailBytes) && tailBytes > 0 ? Math.floor(tailBytes) : DEFAULT_LOG_SCAN_CHUNK_BYTES;
     const fd = fsImpl.openSync(logPath, 'r');
     try {
-      const length = stat.size - start;
-      const buffer = Buffer.alloc(length);
-      fsImpl.readSync(fd, buffer, 0, length, start);
-      const id = selectLastSessionId(buffer.toString('utf8'));
-      if (verbose && id) {
-        console.log(`[VERBOSE] session-resume: last tool session id in ${logPath} is ${id}`);
+      let end = stat.size;
+      let laterPrefix = Buffer.alloc(0);
+      let chunksScanned = 0;
+      while (end > 0) {
+        const start = Math.max(0, end - chunkBytes);
+        const length = end - start;
+        const buffer = Buffer.alloc(length);
+        const bytesRead = fsImpl.readSync(fd, buffer, 0, length, start);
+        const current = bytesRead === length ? buffer : buffer.subarray(0, bytesRead);
+        const scanBuffer = laterPrefix.length > 0 ? Buffer.concat([current, laterPrefix]) : current;
+        const id = selectLastSessionId(scanBuffer.toString('utf8'));
+        chunksScanned += 1;
+        if (id) {
+          if (verbose) {
+            console.log(`[VERBOSE] session-resume: last tool session id in ${logPath} is ${id} (scanned ${chunksScanned} chunk${chunksScanned === 1 ? '' : 's'})`);
+          }
+          return id;
+        }
+        laterPrefix = current.subarray(0, Math.min(current.length, LOG_SCAN_OVERLAP_BYTES));
+        end = start;
       }
-      return id;
+      if (verbose) {
+        console.log(`[VERBOSE] session-resume: no tool session id found in ${logPath} after scanning ${chunksScanned} chunk${chunksScanned === 1 ? '' : 's'}`);
+      }
+      return null;
     } finally {
       fsImpl.closeSync(fd);
     }
@@ -121,10 +140,10 @@ export function readLastSessionIdFromLog(logPath, options = {}) {
 /**
  * Find the id of the most-recently-modified `<sessionId>.log` in a directory.
  *
- * start-command renames each tool session's log to `<sessionId>.log`, so the
- * newest such file is the last session of the run — a second, filesystem-based
- * source for the "use the last session" rule that works even when the captured
- * stdout log has been rotated away. Never throws.
+ * This helper is safe only when `dir` is already known to contain logs for one
+ * task. A shared start-command directory cannot attribute its newest UUID log
+ * to a particular `/solve` run, so completion notifications must not use this
+ * as a fallback. Never throws.
  *
  * @param {Object} options
  * @param {string} options.dir - Directory holding `<sessionId>.log` files
@@ -215,7 +234,8 @@ export function buildResumeCommand({ sessionInfo = {}, lastSessionId = null, bin
   const url = sessionInfo.url || (Array.isArray(sessionInfo.args) ? sessionInfo.args[0] : null);
   if (!url) return null;
 
-  const bin = binary || command;
+  const commandAlias = typeof sessionInfo.commandAlias === 'string' && /^[a-z0-9_-]+$/i.test(sessionInfo.commandAlias) ? sessionInfo.commandAlias : null;
+  const bin = binary || (commandAlias ? `/${commandAlias}` : command);
   let args;
   if (Array.isArray(sessionInfo.args) && sessionInfo.args.length > 0) {
     args = stripResumeFlag(sessionInfo.args);

package/src/session-store.lib.mjs

@@ -33,7 +33,9 @@ import path from 'node:path';
 // excluded so the snapshot stays small and safe to reload.
 // `args` (#1927 review follow-up) is persisted so a killed /solve can be resumed
 // with its exact original invocation plus `--resume <lastSessionId>`.
-const PERSISTABLE_FIELDS = ['chatId', 'messageId', 'startTime', 'url', 'command', 'isolationBackend', 'sessionId', 'containerFilesystemStartBytes', 'containerFilesystemLastBytes', 'containerFilesystemLastObservedAt', 'tool', 'infoBlock', 'urlContext', 'requesterUserId', 'showLimits', 'locale', 'logPath', 'args'];
+// `commandAlias` (#2109) preserves the Telegram spelling (`solve`, `codex`,
+// `claude`, etc.) so a bot notification never suggests a terminal-only command.
+const PERSISTABLE_FIELDS = ['chatId', 'messageId', 'startTime', 'url', 'command', 'commandAlias', 'isolationBackend', 'sessionId', 'containerFilesystemStartBytes', 'containerFilesystemLastBytes', 'containerFilesystemLastObservedAt', 'tool', 'infoBlock', 'urlContext', 'requesterUserId', 'showLimits', 'locale', 'logPath', 'args'];
 
 /**
  * Resolve the directory durable bot state is written to. Honors

package/src/solve.mjs

@@ -253,7 +253,8 @@ if (argv.planModel) {
 if (argv.subAgentModel) await validateAndExitOnInvalidClaudeSubAgentModel(argv.subAgentModel, tool, safeExit);
 
 // Perform all system checks (skip tool connection check in dry-run or when --skip-tool-connection-check; model validation always runs)
-const skipToolConnectionCheck = argv.dryRun || argv.skipToolConnectionCheck || argv.toolConnectionCheck === false;
+const prepareOnly = argv.dryRun || argv.onlyPrepareCommand;
+const skipToolConnectionCheck = prepareOnly || argv.skipToolConnectionCheck || argv.toolConnectionCheck === false;
 const { cascadePlaywrightMcpDisable, ensureSolvePlaywrightMcpReady } = await import('./playwright-mcp.lib.mjs');
 await cascadePlaywrightMcpDisable(argv, log);
 if (!(await performSystemChecks(argv.minDiskSpace || 10240, skipToolConnectionCheck, argv.model, argv))) {
@@ -864,6 +865,7 @@ try {
     await safeExit(shutdownExitCode, 'Graceful shutdown after AI working session', { skipPreExit: true });
   }
 
+  if (toolResult.preparedOnly) await safeExit(0, 'Command prepared', { skipPreExit: true });
   const { success } = toolResult;
   sessionId = toolResult.sessionId;
   let anthropicTotalCostUSD = toolResult.anthropicTotalCostUSD;

package/src/solve.validation.lib.mjs

@@ -303,7 +303,22 @@ export const performSystemChecks = async (minDiskSpace = 10240, skipToolConnecti
   // Skip tool connection validation if in dry-run mode or explicitly requested
   if (!skipToolConnection) {
     let isToolConnected;
-    if (argv.useAgentCommander) {
+    const { isFormalAiModel } = await import('./models/index.mjs');
+    if (isFormalAiModel(model)) {
+      const { validateFormalAiToolConnection } = await import('./formal-ai.lib.mjs');
+      const formalAiValidation = await validateFormalAiToolConnection(argv.tool || 'claude');
+      isToolConnected = formalAiValidation.valid;
+      if (isToolConnected) {
+        await log(`✅ Formal AI wrapper and ${argv.tool || 'claude'} CLI are available`);
+        if (formalAiValidation.version) {
+          await log(`📦 ${argv.tool || 'claude'} CLI version: ${formalAiValidation.version}`);
+        }
+      } else {
+        await log(`❌ Formal AI dispatch validation failed: ${formalAiValidation.error}`, { level: 'error' });
+        await log('   Install or update the wrapper with: cargo install formal-ai', { level: 'error' });
+        return false;
+      }
+    } else if (argv.useAgentCommander) {
       const agentCommanderLib = await import('./agent-commander.lib.mjs');
       isToolConnected = await agentCommanderLib.validateAgentCommanderConnection({
         tool: argv.tool || 'claude',

package/src/telegram-bot.mjs

@@ -820,13 +820,13 @@ async function handleSolveCommand(ctx) {
 
   if (check.canStart && check.startReserved) {
     const startingMessage = await safeReply(ctx, formatStartingWorkSessionMessage({ infoBlock, locale: solveLocale }), { reply_to_message_id: ctx.message.message_id });
-    await executeAndUpdateMessage(ctx, startingMessage, 'solve', argsWithLocale, infoBlock, effectiveSolveIsolation, solveTool, solveUrlContext, { showLimits: solveShowLimits, limitsAtStart: solveLimitsAtStart, locale: solveLocale });
+    await executeAndUpdateMessage(ctx, startingMessage, 'solve', argsWithLocale, infoBlock, effectiveSolveIsolation, solveTool, solveUrlContext, { showLimits: solveShowLimits, limitsAtStart: solveLimitsAtStart, locale: solveLocale, commandAlias: solveCommandName });
   } else {
     if (!solveQueue.executeCallback) {
       const _t = (s, i) => trackSession(s, i, VERBOSE);
       solveQueue.executeCallback = createIsolationAwareQueueCallback(ISOLATION_BACKEND, isolationRunner, _t, createQueueExecuteCallback(executeStartScreen, _t), VERBOSE);
     }
-    const queueItem = solveQueue.enqueue({ url: normalizedUrl, args: argsWithLocale, ctx, requester, infoBlock, tool: solveTool, perCommandIsolation: effectiveSolveIsolation, urlContext: solveUrlContext, showLimits: solveShowLimits, limitsAtStart: solveLimitsAtStart, locale: solveLocale });
+    const queueItem = solveQueue.enqueue({ url: normalizedUrl, args: argsWithLocale, ctx, requester, infoBlock, commandAlias: solveCommandName, tool: solveTool, perCommandIsolation: effectiveSolveIsolation, urlContext: solveUrlContext, showLimits: solveShowLimits, limitsAtStart: solveLimitsAtStart, locale: solveLocale });
     const queueMessage = buildSolveQueuedMessage({ locale: solveLocale, tool: solveTool, position: toolQueuedCount + 1, infoBlock, reason: check.reason ? escapeMarkdown(check.reason) : '' }); // tool-specific position (#1551)
     const queuedMessage = await safeReply(ctx, queueMessage, { reply_to_message_id: ctx.message.message_id });
     queueItem.messageInfo = { chatId: queuedMessage.chat.id, messageId: queuedMessage.message_id };

package/src/telegram-command-execution.lib.mjs

@@ -99,7 +99,7 @@ function executeWithCommand(startScreenCmd, command, args, verbose = false) {
  */
 export function buildExecuteAndUpdateMessage(deps) {
   const { resolveIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE, executeStartScreen, trackSession, untrackSession, AUTO_WATCH_MESSAGE, startAutoTerminalWatchForSession, bot, formatExecutingWorkSessionMessage, formatStartingWorkSessionMessage } = deps;
-  return async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock, perCommandIsolation = null, tool = 'claude', urlContext = null, { showLimits = false, limitsAtStart = null, locale = null } = {}) {
+  return async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock, perCommandIsolation = null, tool = 'claude', urlContext = null, { showLimits = false, limitsAtStart = null, locale = null, commandAlias = null } = {}) {
     const { chat, message_id: msgId } = startingMessage;
     const safeEdit = async text => {
       try {
@@ -111,7 +111,7 @@ export function buildExecuteAndUpdateMessage(deps) {
     const requesterUserId = ctx.from?.id ?? null; // Issue #1688: suppress duplicate /subscribe DM
     // #1927 review follow-up: persist the full args so a killed /solve can be
     //   resumed with its exact original invocation + `--resume <lastSessionId>`.
-    const baseSessionInfo = { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, tool, infoBlock, urlContext, requesterUserId, showLimits, limitsAtStart, locale, args: Array.isArray(args) ? [...args] : undefined }; // #594: showLimits/limitsAtStart
+    const baseSessionInfo = { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, commandAlias, tool, infoBlock, urlContext, requesterUserId, showLimits, limitsAtStart, locale, args: Array.isArray(args) ? [...args] : undefined }; // #594: showLimits/limitsAtStart
     const iso = await resolveIsolation(perCommandIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE);
     let result, session, sessionInfo;
     if (iso) {

package/src/telegram-isolation.lib.mjs

@@ -90,11 +90,13 @@ export function createIsolationAwareQueueCallback(botIsolationBackend, botIsolat
             startTime: new Date(),
             url: item.url,
             command: item.command || 'solve',
+            commandAlias: item.commandAlias || null,
             isolationBackend: iso.backend,
             sessionId: sid,
             containerFilesystemStartBytes: Number.isFinite(r.containerFilesystemStartBytes) ? r.containerFilesystemStartBytes : null,
             tool,
             infoBlock: item.infoBlock,
+            args: Array.isArray(item.args) ? [...item.args] : undefined,
             // Issue #1688: propagate URL context + requester through the queue so the
             //   completion notification can append a 'Pull request:' line and skip
             //   notifying the requester twice via /subscribe.

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

@@ -53,6 +53,7 @@ class SolveQueueItem {
     this.ctx = options.ctx;
     this.requester = options.requester;
     this.infoBlock = options.infoBlock;
+    this.commandAlias = options.commandAlias || null; // #2109: retain Telegram spelling for resume guidance
     this.tool = options.tool || 'claude';
     // Issue #1983: preserve per-command isolation through queued execution.
     this.perCommandIsolation = options.perCommandIsolation || null;
@@ -1442,16 +1443,14 @@ export function createQueueExecuteCallback(executeStartScreen, trackSessionFn) {
           startTime: new Date(),
           url: item.url,
           command: 'solve',
+          commandAlias: item.commandAlias || null,
           tool: item.tool || 'claude',
           infoBlock: item.infoBlock,
-          // Issue #1688: propagate URL context + requester so the completion
-          //   notification can append a 'Pull request:' line and skip
-          //   notifying the requester twice via /subscribe.
+          args: Array.isArray(item.args) ? [...item.args] : undefined,
+          // #1688: propagate URL context and requester to completion.
           urlContext: item.urlContext || null,
           requesterUserId: item.requesterUserId ?? null,
-          // Issue #594: --show-limits virtual option carries the start-of-task
-          //   snapshot from the queueing point through to the completion
-          //   handler so it can render an end-of-task delta.
+          // #594: carry the start-of-task limits snapshot to completion.
           showLimits: item.showLimits === true,
           limitsAtStart: item.limitsAtStart || null,
           locale: item.locale || null,