bosun 0.34.2 → 0.34.4

package/telegram-bot.mjs

@@ -118,6 +118,37 @@ import {
 } from "./presence.mjs";
 
 const __dirname = resolve(fileURLToPath(new URL(".", import.meta.url)));
+
+function isWslInteropRuntime() {
+  return Boolean(
+    process.env.WSL_DISTRO_NAME
+    || process.env.WSL_INTEROP
+    || (process.platform === "win32"
+      && String(process.env.HOME || "")
+        .trim()
+        .startsWith("/home/")),
+  );
+}
+
+function resolveTelegramConfigDir() {
+  if (process.env.BOSUN_HOME) return resolve(process.env.BOSUN_HOME);
+  if (process.env.BOSUN_DIR) return resolve(process.env.BOSUN_DIR);
+
+  const preferWindowsDirs = process.platform === "win32" && !isWslInteropRuntime();
+  const baseDir = preferWindowsDirs
+    ? process.env.APPDATA
+      || process.env.LOCALAPPDATA
+      || process.env.USERPROFILE
+      || process.env.HOME
+      || homedir()
+    : process.env.HOME
+      || process.env.XDG_CONFIG_HOME
+      || process.env.USERPROFILE
+      || process.env.APPDATA
+      || process.env.LOCALAPPDATA
+      || homedir();
+  return resolve(baseDir, "bosun");
+}
 const repoRoot = resolveRepoRoot();
 const BosunDir = __dirname;
 const statusPath = resolve(repoRoot, ".cache", "ve-orchestrator-status.json");
@@ -329,6 +360,23 @@ function delayMs(ms) {
   return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
 }
 
+const SAFE_DETACH_PREFIX = "[telegram-bot] async-detach";
+
+function safeDetach(label, taskOrPromise) {
+  const tag = label
+    ? `${SAFE_DETACH_PREFIX}:${String(label)}`
+    : SAFE_DETACH_PREFIX;
+  try {
+    const result =
+      typeof taskOrPromise === "function" ? taskOrPromise() : taskOrPromise;
+    Promise.resolve(result).catch((err) => {
+      console.warn(`${tag} failed: ${err?.message || err}`);
+    });
+  } catch (err) {
+    console.warn(`${tag} failed: ${err?.message || err}`);
+  }
+}
+
 function shouldUseCurlPrimary() {
   return (
     TELEGRAM_CURL_FALLBACK &&
@@ -1088,6 +1136,25 @@ async function bumpStickyMenu(chatId) {
   });
 }
 
+async function refreshStickyMenu(chatId, screenId = "home", params = {}) {
+  const state = stickyMenuState.get(chatId);
+  if (state?.messageId) {
+    try {
+      await deleteDirect(chatId, state.messageId);
+    } catch {
+      /* best effort */
+    }
+  }
+  const timer = stickyMenuTimers.get(chatId);
+  if (timer) {
+    clearTimeout(timer);
+    stickyMenuTimers.delete(chatId);
+  }
+  stickyMenuState.delete(chatId);
+  clearPendingUiInput(chatId);
+  await showUiScreen(chatId, null, screenId, params, { sticky: true });
+}
+
 // ── Telegram API Helpers ─────────────────────────────────────────────────────
 
 /**
@@ -2257,7 +2324,7 @@ async function handleUpdate(update) {
   // Free-text agent task runs in a separate queue so polling isn't blocked.
   // If agent is already busy, handle immediately so follow-ups can be queued.
   if (isPrimaryBusy()) {
-    void handleFreeText(text, chatId);
+    safeDetach("free-text", () => handleFreeText(text, chatId));
     return;
   }
   enqueueAgentTask(() => handleFreeText(text, chatId));
@@ -2432,7 +2499,7 @@ async function cmdWorkspace(chatId, text) {
     .trim();
   const [sub, ...rest] = raw ? raw.split(/\s+/) : [];
   const subcmd = String(sub || "list").toLowerCase();
-  const configDir = process.env.BOSUN_DIR || join(homedir(), "bosun");
+  const configDir = resolveTelegramConfigDir();
 
   try {
     if (subcmd === "scan") {
@@ -3951,13 +4018,13 @@ function uiNavRow(parent) {
   if (!parent) {
     return [
       uiButton("🏠 Home", uiGoAction("home")),
-      uiButton("✖ Close", "cb:close_menu"),
+      uiButton("❌ Close", "cb:close_menu"),
     ];
   }
   return [
     uiButton("⬅️ Back", uiGoAction(parent)),
     uiButton("🏠 Home", uiGoAction("home")),
-    uiButton("✖ Close", "cb:close_menu"),
+    uiButton("❌ Close", "cb:close_menu"),
   ];
 }
 
@@ -4191,7 +4258,7 @@ Object.assign(UI_SCREENS, {
             text: "📱 Open Control Center",
             web_app: { url: telegramWebAppUrl },
           },
-          uiButton("✖", "cb:close_menu"),
+          uiButton("❌", "cb:close_menu"),
         ]);
         if (telegramUiUrl) {
           rows.unshift([
@@ -4201,10 +4268,10 @@ Object.assign(UI_SCREENS, {
       } else if (telegramUiUrl) {
         rows.unshift([
           { text: "🌐 Open Control Center", url: getBrowserUiUrl() || telegramUiUrl },
-          uiButton("✖", "cb:close_menu"),
+          uiButton("❌", "cb:close_menu"),
         ]);
       } else {
-        rows.unshift([uiButton("✖ Close Menu", "cb:close_menu")]);
+        rows.unshift([uiButton("❌ Close Menu", "cb:close_menu")]);
       }
       return buildKeyboard(rows);
     },
@@ -5038,7 +5105,7 @@ Object.assign(UI_SCREENS, {
     body: () => "Choose a local workspace to set active for task routing.",
     keyboard: async (ctx) => {
       const page = parsePageParam(ctx.params?.page);
-      const configDir = process.env.BOSUN_DIR || join(homedir(), "bosun");
+      const configDir = resolveTelegramConfigDir();
       const workspaces = listLocalWorkspaces(configDir);
       const active = getActiveLocalWorkspace(configDir);
       if (!workspaces.length) {
@@ -5302,7 +5369,7 @@ Object.assign(UI_SCREENS, {
     body: () => "Browse, manage, and interact with your managed workspaces.",
     keyboard: async (ctx) => {
       const page = parsePageParam(ctx.params?.page);
-      const configDir = process.env.BOSUN_DIR || join(homedir(), "bosun");
+      const configDir = resolveTelegramConfigDir();
       const workspaces = listLocalWorkspaces(configDir);
       const active = getActiveLocalWorkspace(configDir);
       if (!workspaces.length) {
@@ -6060,7 +6127,7 @@ async function cmdApp(chatId) {
 async function cmdMenu(chatId) {
   syncUiUrlsFromServer();
   if (telegramApiReachable !== false) {
-    void refreshMenuButton();
+    safeDetach("menu-button-refresh", refreshMenuButton);
   }
   clearPendingUiInput(chatId);
   await showUiScreen(chatId, null, "home", {}, { sticky: true });
@@ -6774,10 +6841,10 @@ async function cmdStartTask(chatId, args) {
       );
       return;
     }
-    void executor.executeTask(task, {
+    safeDetach("manual-start", () => executor.executeTask(task, {
       sdk: sdk || undefined,
       model: model || undefined,
-    });
+    }));
     await sendReply(
       chatId,
       `✅ Manual start queued for ${task.title || task.id}.` +
@@ -9089,7 +9156,7 @@ async function cmdBackground(chatId, args) {
       chatId,
       `🛰️ Background task queued: "${task.slice(0, 80)}${task.length > 80 ? "…" : ""}"`,
     );
-    void handleFreeText(task, chatId, { background: true, isolated: true });
+    safeDetach("background-free-text", () => handleFreeText(task, chatId, { background: true, isolated: true }));
     return;
   }
 
@@ -9448,11 +9515,11 @@ async function handleFreeText(text, chatId, options = {}) {
     const elapsed = now - lastEditAt;
     if (elapsed >= EDIT_THROTTLE_MS) {
       editPending = true;
-      void doEdit();
+      safeDetach("agent-edit", doEdit);
     } else {
       editPending = true;
       if (editTimer) clearTimeout(editTimer);
-      editTimer = setTimeout(() => void doEdit(), EDIT_THROTTLE_MS - elapsed);
+      editTimer = setTimeout(() => safeDetach("agent-edit", doEdit), EDIT_THROTTLE_MS - elapsed);
     }
   };
 
@@ -9796,8 +9863,8 @@ function startPresenceLoop() {
       );
     }
   };
-  setTimeout(() => void sendPresence(), intervalMs);
-  setInterval(() => void sendPresence(), intervalMs);
+  setTimeout(() => safeDetach("presence-heartbeat", sendPresence), intervalMs);
+  setInterval(() => safeDetach("presence-heartbeat", sendPresence), intervalMs);
 }
 
 function hasPresenceChanged(prev, curr) {
@@ -10439,6 +10506,11 @@ export async function startTelegramBot() {
   if (miniAppEnabled || miniAppPort > 0) {
     try {
       await startTelegramUiServer({
+        // Background monitor/bot runtime should not keep opening browser tabs.
+        // Set BOSUN_UI_AUTO_OPEN_BROWSER=1 to opt-in.
+        skipAutoOpen: !["1", "true", "yes", "on"].includes(
+          String(process.env.BOSUN_UI_AUTO_OPEN_BROWSER || "").toLowerCase(),
+        ),
         dependencies: {
           execPrimaryPrompt,
           getInternalExecutor: _getInternalExecutor,
@@ -10446,7 +10518,7 @@ export async function startTelegramBot() {
           getAgentEventBus: _getAgentEventBus,
           handleUiCommand: handleUiCommand,
           getSyncEngine: _getSyncEngine,
-          configDir: process.env.BOSUN_DIR || join(homedir(), "bosun"),
+          configDir: resolveTelegramConfigDir(),
           onProjectSyncAlert: async (alert) => {
             if (!_sendTelegramMessage) return;
             const text = String(alert?.message || "Project sync alert");
@@ -10467,16 +10539,16 @@ export async function startTelegramBot() {
 
       // Immediately sync the menu button, then periodically refresh
       if (reachable) {
-        void refreshMenuButton();
+        safeDetach("menu-button-refresh", refreshMenuButton);
       }
       if (reachable && !menuButtonRefreshTimer) {
-        menuButtonRefreshTimer = setInterval(() => void refreshMenuButton(), MENU_BUTTON_REFRESH_MS);
+        menuButtonRefreshTimer = setInterval(() => safeDetach("menu-button-refresh", refreshMenuButton), MENU_BUTTON_REFRESH_MS);
       }
 
       // React immediately when the tunnel URL changes (e.g. after restart)
       onTunnelUrlChange((url) => {
         console.log(`[telegram-bot] tunnel URL changed: ${url} — refreshing menu button`);
-        void refreshMenuButton();
+        safeDetach("menu-button-refresh", refreshMenuButton);
       });
 
       // Notify about firewall issues if detected (24h cooldown)
@@ -10588,8 +10660,9 @@ export async function startTelegramBot() {
   } else {
     await sendDirect(
       telegramChatId,
-      `🤖 Bosun primary agent online (${getPrimaryAgentName()}).\n\nType /menu for the control center or send any message to chat with the agent.`,
+      `🤖 Bosun primary agent online (${getPrimaryAgentName()}).\n\nType /menu for the control center or send any message to chat with the agent.\n\nRefreshing control center menu below…`,
     );
+    await refreshStickyMenu(telegramChatId, "home", {});
 
     // ── SECURITY: Alert when ALLOW_UNSAFE is enabled (especially with tunnel) ──
     const _isUnsafe = ["1", "true", "yes"].includes(
@@ -10691,7 +10764,7 @@ export function stopTelegramBot(options = {}) {
     }
     stopBatchFlushLoop();
   }
-  void releaseTelegramPollLock();
+  safeDetach("poll-lock-release", releaseTelegramPollLock);
   stopTelegramUiServer();
   if (menuButtonRefreshTimer) {
     clearInterval(menuButtonRefreshTimer);

package/ui/modules/settings-schema.js

@@ -131,6 +131,12 @@ export const SETTINGS_SCHEMA = [
 
   // ── GitHub / Git ─────────────────────────────────────────
   { key: "GITHUB_TOKEN",                   label: "GitHub Token",               category: "github", type: "secret", sensitive: true, description: "Personal access token or fine-grained token for GitHub API. Required for GitHub kanban backend." },
+  { key: "BOSUN_GITHUB_CLIENT_ID",         label: "GitHub OAuth Client ID",     category: "github", type: "string", description: "OAuth client ID used for GitHub device flow sign-in in the Bosun portal." },
+  { key: "BOSUN_GITHUB_CLIENT_SECRET",     label: "GitHub OAuth Client Secret", category: "github", type: "secret", sensitive: true, description: "OAuth client secret used for GitHub web callback exchange.", advanced: true },
+  { key: "BOSUN_GITHUB_APP_ID",            label: "GitHub App ID",              category: "github", type: "string", description: "Numeric Bosun GitHub App ID used for installation token auth.", advanced: true },
+  { key: "BOSUN_GITHUB_PRIVATE_KEY_PATH",  label: "GitHub App Private Key",     category: "github", type: "string", description: "Absolute path to the Bosun GitHub App .pem private key.", advanced: true },
+  { key: "BOSUN_GITHUB_WEBHOOK_SECRET",    label: "GitHub App Webhook Secret",  category: "github", type: "secret", sensitive: true, description: "Webhook HMAC secret for validating GitHub App webhook deliveries.", advanced: true },
+  { key: "BOSUN_GITHUB_USER_TOKEN",        label: "GitHub User Token Override", category: "github", type: "secret", sensitive: true, description: "Optional direct OAuth user token override (skips auth-state lookup).", advanced: true },
   { key: "GITHUB_REPOSITORY",              label: "Repository",                 category: "github", type: "string", description: "GitHub repository in owner/repo format. Auto-detected from git remote if not set.", validate: "^[\\w.-]+/[\\w.-]+$" },
   { key: "GITHUB_PROJECT_MODE",            label: "Project Mode",               category: "github", type: "select", defaultVal: "issues", options: ["issues", "kanban"], description: "Use GitHub Issues directly, or GitHub Projects v2 kanban board." },
   { key: "GITHUB_PROJECT_NUMBER",          label: "Project Number",             category: "github", type: "number", min: 1, description: "GitHub Projects v2 number. Required when project mode is 'kanban'." },

package/ui/tabs/control.js

@@ -868,11 +868,12 @@ export function ControlTab() {
             <div class="card-subtitle mt-sm">Kanban</div>
             <${SegmentedControl}
               options=${[
+                { value: "internal", label: "Internal" },
                 { value: "vk", label: "VK" },
                 { value: "github", label: "GitHub" },
                 { value: "jira", label: "Jira" },
               ]}
-              value=${config?.kanbanBackend || "github"}
+              value=${config?.kanbanBackend || "internal"}
               onChange=${(v) => updateConfig("kanban", v)}
             />
             ${regions.length > 1 && html`

package/ui/tabs/settings.js

@@ -715,11 +715,29 @@ function ServerConfigMode() {
           method: "POST",
           body: JSON.stringify({ changes }),
         });
-      } catch (primaryErr) {
-        // Legacy/demo compatibility endpoint.
+      } catch (error_) {
+        const message = String(error_?.message || "");
+        const shouldTryLegacy =
+          /Request failed \((404|405|501)\)/.test(message)
+          || /Failed to fetch|NetworkError|Load failed/i.test(message);
+
+        if (!shouldTryLegacy) throw error_;
+
+        const legacyKeyMap = {
+          INTERNAL_EXECUTOR_SDK: "sdk",
+          KANBAN_BACKEND: "kanban",
+          EXECUTOR_REGIONS: "region",
+        };
+        const entries = Object.entries(changes);
+        if (entries.length !== 1) throw error_;
+
+        const [envKey, value] = entries[0];
+        const legacyKey = legacyKeyMap[envKey];
+        if (!legacyKey) throw error_;
+
         res = await apiFetch("/api/config/update", {
           method: "POST",
-          body: JSON.stringify(changes),
+          body: JSON.stringify({ key: legacyKey, value }),
         });
       }
       if (res?.ok || (res && typeof res === "object" && !Array.isArray(res))) {

package/ui-server.mjs

@@ -5,7 +5,7 @@ import { open, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { get as httpsGet } from "node:https";
 import { createServer as createHttpsServer } from "node:https";
-import { networkInterfaces } from "node:os";
+import { networkInterfaces, homedir } from "node:os";
 import { connect as netConnect } from "node:net";
 import { resolve, extname, dirname, basename, relative } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -27,6 +27,8 @@ function getLocalLanIp() {
 import { WebSocketServer } from "ws";
 import {
   getKanbanAdapter,
+  getKanbanBackendName,
+  setKanbanBackend,
   markTaskIgnored,
   unmarkTaskIgnored,
 } from "./kanban-adapter.mjs";
@@ -1249,9 +1251,38 @@ let uiDeps = {};
  * Ensures the directory exists.
  */
 function resolveUiConfigDir() {
+  if (process.env.BOSUN_CONFIG_PATH) {
+    const fromConfigPath = dirname(resolve(process.env.BOSUN_CONFIG_PATH));
+    try { mkdirSync(fromConfigPath, { recursive: true }); } catch { /* ok */ }
+    if (!uiDeps.configDir) uiDeps.configDir = fromConfigPath;
+    return fromConfigPath;
+  }
+  const isWslInteropRuntime = Boolean(
+    process.env.WSL_DISTRO_NAME
+    || process.env.WSL_INTEROP
+    || (process.platform === "win32"
+      && String(process.env.HOME || "")
+        .trim()
+        .startsWith("/home/")),
+  );
+  const preferWindowsDirs = process.platform === "win32" && !isWslInteropRuntime;
+  const baseDir = preferWindowsDirs
+    ? process.env.APPDATA
+      || process.env.LOCALAPPDATA
+      || process.env.USERPROFILE
+      || process.env.HOME
+      || homedir()
+    : process.env.HOME
+      || process.env.XDG_CONFIG_HOME
+      || process.env.USERPROFILE
+      || process.env.APPDATA
+      || process.env.LOCALAPPDATA
+      || homedir();
+
   const dir = uiDeps.configDir
+    || process.env.BOSUN_HOME
     || process.env.BOSUN_DIR
-    || resolve(process.env.HOME || process.env.USERPROFILE || "", "bosun");
+    || resolve(baseDir, "bosun");
   if (dir) {
     try { mkdirSync(dir, { recursive: true }); } catch { /* ok */ }
     // Cache it so subsequent calls don't re-resolve
@@ -1308,6 +1339,8 @@ const SETTINGS_KNOWN_KEYS = [
   "BOSUN_PROMPT_PLANNER",
   "GITHUB_TOKEN", "GITHUB_REPOSITORY", "GITHUB_PROJECT_MODE",
   "GITHUB_PROJECT_NUMBER", "GITHUB_DEFAULT_ASSIGNEE", "GITHUB_AUTO_ASSIGN_CREATOR",
+  "BOSUN_GITHUB_APP_ID", "BOSUN_GITHUB_PRIVATE_KEY_PATH", "BOSUN_GITHUB_CLIENT_ID", "BOSUN_GITHUB_CLIENT_SECRET",
+  "BOSUN_GITHUB_WEBHOOK_SECRET", "BOSUN_GITHUB_USER_TOKEN",
   "GITHUB_PROJECT_WEBHOOK_PATH", "GITHUB_PROJECT_WEBHOOK_SECRET", "GITHUB_PROJECT_WEBHOOK_REQUIRE_SIGNATURE",
   "GITHUB_PROJECT_SYNC_ALERT_FAILURE_THRESHOLD", "GITHUB_PROJECT_SYNC_RATE_LIMIT_ALERT_THRESHOLD",
   "VK_TARGET_BRANCH", "CODEX_ANALYZE_MERGE_STRATEGY", "DEPENDABOT_AUTO_MERGE",
@@ -1342,6 +1375,7 @@ const SETTINGS_SENSITIVE_KEYS = new Set([
   "TELEGRAM_BOT_TOKEN", "TELEGRAM_CHAT_ID", "GITHUB_TOKEN",
   "OPENAI_API_KEY", "AZURE_OPENAI_API_KEY", "CODEX_MODEL_PROFILE_XL_API_KEY", "CODEX_MODEL_PROFILE_M_API_KEY",
   "ANTHROPIC_API_KEY", "COPILOT_CLI_TOKEN", "GITHUB_PROJECT_WEBHOOK_SECRET",
+  "BOSUN_GITHUB_CLIENT_SECRET", "BOSUN_GITHUB_WEBHOOK_SECRET", "BOSUN_GITHUB_USER_TOKEN",
   "CLOUDFLARE_TUNNEL_CREDENTIALS",
 ]);
 
@@ -1504,11 +1538,7 @@ function validateConfigSchemaChanges(changes) {
         fieldErrors[envKey] = err.message || "Invalid value";
       }
     }
-    if (Object.keys(fieldErrors).length === 0) {
-      for (const envKey of pathMap.values()) {
-        fieldErrors[envKey] = "Invalid value (config schema)";
-      }
-    }
+    if (Object.keys(fieldErrors).length === 0) return {};
     return fieldErrors;
   } catch {
     return {};
@@ -5758,6 +5788,16 @@ async function handleApi(req, res, url) {
     const regionEnv = (process.env.EXECUTOR_REGIONS || "").trim();
     const regions = regionEnv ? regionEnv.split(",").map((r) => r.trim()).filter(Boolean) : ["auto"];
     const pkg = JSON.parse(readFileSync(resolve(__dirname, "package.json"), "utf8"));
+    let runtimeKanbanBackend = "internal";
+    try {
+      runtimeKanbanBackend = String(
+        getKanbanBackendName() || process.env.KANBAN_BACKEND || "internal",
+      ).trim().toLowerCase();
+    } catch {
+      runtimeKanbanBackend = String(
+        process.env.KANBAN_BACKEND || "internal",
+      ).trim().toLowerCase();
+    }
     jsonResponse(res, 200, {
       ok: true,
       version: pkg.version,
@@ -5769,7 +5809,7 @@ async function handleApi(req, res, url) {
       wsEnabled: true,
       authRequired: !isAllowUnsafe(),
       sdk: process.env.EXECUTOR_SDK || "auto",
-      kanbanBackend: process.env.KANBAN_BACKEND || "github",
+      kanbanBackend: runtimeKanbanBackend,
       regions,
     });
     return;
@@ -5790,6 +5830,13 @@ async function handleApi(req, res, url) {
         return;
       }
       process.env[envKey] = value;
+      if (envKey === "KANBAN_BACKEND") {
+        try {
+          setKanbanBackend(String(value).trim().toLowerCase());
+        } catch (err) {
+          console.warn(`[config] failed to switch kanban backend: ${err.message}`);
+        }
+      }
       // Also send chat command for backward compat
       const cmdMap = { sdk: `/sdk ${value}`, kanban: `/kanban ${value}`, region: `/region ${value}` };
       const handler = uiDeps.handleUiCommand;
@@ -5895,6 +5942,15 @@ async function handleApi(req, res, url) {
         process.env[key] = strVal;
         strChanges[key] = strVal;
       }
+      if (Object.prototype.hasOwnProperty.call(strChanges, "KANBAN_BACKEND")) {
+        try {
+          setKanbanBackend(
+            String(strChanges.KANBAN_BACKEND).trim().toLowerCase(),
+          );
+        } catch (err) {
+          console.warn(`[settings] failed to switch kanban backend: ${err.message}`);
+        }
+      }
       // Write to .env file
       const updated = updateEnvFile(strChanges);
       const configUpdate = updateConfigFile(changes);
@@ -6136,7 +6192,7 @@ async function handleApi(req, res, url) {
           jsonResponse(res, 404, { ok: false, error: "Task not found." });
           return;
         }
-        executor.executeTask(task).catch((error) => {
+        executor.executeTask(task, { force: true }).catch((error) => {
           console.warn(
             `[telegram-ui] dispatch failed for ${taskId}: ${error.message}`,
           );
@@ -6782,7 +6838,43 @@ export async function startTelegramUiServer(options = {}) {
 
   const rawPort = options.port ?? getDefaultPort();
   const port = Number(rawPort);
-  if (!Number.isFinite(port) || port < 0) return null;
+  const isTestRun =
+    Boolean(process.env.VITEST) ||
+    process.env.NODE_ENV === "test" ||
+    Boolean(process.env.JEST_WORKER_ID);
+  const allowEphemeralPort =
+    options.allowEphemeralPort === true ||
+    process.env.BOSUN_UI_ALLOW_EPHEMERAL_PORT === "1" ||
+    isTestRun;
+  const portSource =
+    options.port != null
+      ? "options.port"
+      : process.env.TELEGRAM_UI_PORT
+        ? "env.TELEGRAM_UI_PORT"
+        : "default(0)";
+
+  if (!Number.isFinite(port) || port < 0) {
+    console.warn(
+      `[telegram-ui] invalid ui port: raw=${String(rawPort)} source=${portSource}`,
+    );
+    return null;
+  }
+  if (port === 0 && !allowEphemeralPort) {
+    console.warn(
+      `[telegram-ui] refusing ephemeral ui port (resolved 0 from ${portSource}); ` +
+      `set TELEGRAM_UI_PORT (for example 4400) or set BOSUN_UI_ALLOW_EPHEMERAL_PORT=1`,
+    );
+    return null;
+  }
+
+  const autoOpenEnabled = ["1", "true", "yes", "on"].includes(
+    String(process.env.BOSUN_UI_AUTO_OPEN_BROWSER || "")
+      .trim()
+      .toLowerCase(),
+  );
+  console.log(
+    `[telegram-ui] startup config: port=${port} source=${portSource} autoOpen=${autoOpenEnabled ? "enabled" : "disabled"}`,
+  );
 
   injectUiDependencies(options.dependencies || {});
 
@@ -7042,12 +7134,14 @@ export async function startTelegramUiServer(options = {}) {
   //  - skip when caller passes skipAutoOpen
   //  - skip during Vitest / Jest test runs (avoids opening 20+ tabs during `npm test`)
   //  - only open ONCE per process (singleton guard — prevents loops on server restart)
-  const isTestRun = process.env.VITEST || process.env.NODE_ENV === "test" || process.env.JEST_WORKER_ID;
+  const isTestRunRuntime =
+    process.env.VITEST || process.env.NODE_ENV === "test" || process.env.JEST_WORKER_ID;
   if (
+    autoOpenEnabled &&
     process.env.BOSUN_DESKTOP !== "1" &&
     !options.skipAutoOpen &&
     !_browserOpened &&
-    !isTestRun
+    !isTestRunRuntime
   ) {
     _browserOpened = true;
     const openUrl = `${protocol}://${lanIp}:${actualPort}/?token=${sessionToken}`;

package/workflow-nodes.mjs

@@ -26,6 +26,76 @@ import { randomUUID } from "node:crypto";
 const TAG = "[workflow-nodes]";
 const PORTABLE_WORKTREE_COUNT_COMMAND = "node -e \"const cp=require('node:child_process');const wt=cp.execSync('git worktree list --porcelain',{encoding:'utf8'});const count=(wt.match(/^worktree /gm)||[]).length;process.stdout.write(String(count)+'\\\\n');\"";
 const PORTABLE_PRUNE_AND_COUNT_WORKTREES_COMMAND = "node -e \"const cp=require('node:child_process');cp.execSync('git worktree prune',{stdio:'ignore'});const wt=cp.execSync('git worktree list --porcelain',{encoding:'utf8'});const count=(wt.match(/^worktree /gm)||[]).length;process.stdout.write(String(count)+'\\\\n');\"";
+const WORKFLOW_AGENT_HEARTBEAT_MS = (() => {
+  const raw = Number(process.env.WORKFLOW_AGENT_HEARTBEAT_MS || 30000);
+  if (!Number.isFinite(raw)) return 30000;
+  return Math.max(5000, Math.min(120000, Math.trunc(raw)));
+})();
+
+function trimLogText(value, max = 180) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (!text) return "";
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+function summarizeAgentStreamEvent(event) {
+  const type = String(event?.type || "").trim();
+  if (!type) return "";
+
+  if (
+    type === "response.output_text.delta" ||
+    type === "response.output_text.done" ||
+    type === "item.updated"
+  ) {
+    return "";
+  }
+
+  if (type === "tool_call") {
+    return `Tool call: ${event?.tool_name || event?.data?.tool_name || "unknown"}`;
+  }
+
+  if (type === "tool_result") {
+    const name = event?.tool_name || event?.data?.tool_name || "unknown";
+    return `Tool result: ${name}`;
+  }
+
+  if (type === "error") {
+    return `Agent error: ${trimLogText(event?.error || event?.message || "unknown error", 220)}`;
+  }
+
+  const messageText = trimLogText(
+    event?.message?.content ||
+      event?.message?.text ||
+      event?.content ||
+      event?.text ||
+      event?.data?.content ||
+      event?.data?.text ||
+      "",
+    220,
+  );
+
+  if (messageText) {
+    if (
+      type === "agent_message" ||
+      type === "assistant_message" ||
+      type === "message" ||
+      type === "item.completed"
+    ) {
+      return `Agent: ${messageText}`;
+    }
+    return `${type}: ${messageText}`;
+  }
+
+  if (
+    type === "turn.complete" ||
+    type === "session.completed" ||
+    type === "response.completed"
+  ) {
+    return `Agent event: ${type}`;
+  }
+
+  return "";
+}
 
 function normalizeLegacyWorkflowCommand(command) {
   let normalized = String(command || "");
@@ -460,8 +530,45 @@ registerNodeType("action.run_agent", {
     // Use the engine's service injection to call agent pool
     const agentPool = engine.services?.agentPool;
     if (agentPool?.launchEphemeralThread) {
-      const result = await agentPool.launchEphemeralThread(finalPrompt, cwd, timeoutMs);
-      ctx.log(node.id, `Agent completed: success=${result.success}`);
+      let streamEventCount = 0;
+      let lastStreamLog = "";
+      const startedAt = Date.now();
+      const launchExtra = {};
+      if (sdk && sdk !== "auto") launchExtra.sdk = sdk;
+
+      launchExtra.onEvent = (event) => {
+        try {
+          const line = summarizeAgentStreamEvent(event);
+          if (!line || line === lastStreamLog) return;
+          lastStreamLog = line;
+          streamEventCount += 1;
+          ctx.log(node.id, line);
+        } catch {
+          // Stream callbacks must never crash workflow execution.
+        }
+      };
+
+      const heartbeat = setInterval(() => {
+        const elapsedSec = Math.max(1, Math.round((Date.now() - startedAt) / 1000));
+        ctx.log(node.id, `Agent still running (${elapsedSec}s elapsed)`);
+      }, WORKFLOW_AGENT_HEARTBEAT_MS);
+
+      let result;
+      try {
+        result = await agentPool.launchEphemeralThread(
+          finalPrompt,
+          cwd,
+          timeoutMs,
+          launchExtra,
+        );
+      } finally {
+        clearInterval(heartbeat);
+      }
+
+      ctx.log(
+        node.id,
+        `Agent completed: success=${result.success} streamEvents=${streamEventCount}`,
+      );
 
       // Propagate session/thread IDs for downstream chaining
       const threadId = result.threadId || result.sessionId || null;