@openacp/cli 2026.331.2 → 2026.331.4

package/dist/cli.js

@@ -3929,7 +3929,7 @@ function initLogger(config) {
         target: "pino-pretty",
         options: {
           colorize: true,
-          translateTime: "HH:mm:ss",
+          translateTime: "SYS:HH:MM:ss",
           ignore: "pid,hostname",
           singleLine: true
         },
@@ -4964,7 +4964,7 @@ var init_tunnel_registry = __esm({
         this.providerOptions = opts.providerOptions ?? {};
         this.registryPath = opts.registryPath ?? path16.join(os9.homedir(), ".openacp", "tunnels.json");
       }
-      async add(port, opts) {
+      async add(port, opts, _autoRetry = true) {
         if (this.entries.has(port)) {
           const existing = this.entries.get(port);
           if (existing.entry.status === "active" || existing.entry.status === "starting") {
@@ -5018,6 +5018,15 @@ var init_tunnel_registry = __esm({
           entry.status = "failed";
           log7.error({ port, err: err.message }, "Tunnel failed to start");
           this.scheduleSave();
+          const live = this.entries.get(port);
+          if (_autoRetry && live && !this.shuttingDown && live.entry.retryCount < MAX_RETRIES) {
+            const delay = BASE_RETRY_DELAY_MS * Math.pow(2, live.entry.retryCount);
+            log7.warn(
+              { port, retry: live.entry.retryCount + 1, maxRetries: MAX_RETRIES, delayMs: delay },
+              "Scheduling retry after initial start failure"
+            );
+            live.retryTimer = setTimeout(() => this.retry(port, opts), delay);
+          }
           throw err;
         });
         this.entries.set(port, { entry, process: provider, spawnPromise, retryTimer: null });
@@ -5034,7 +5043,7 @@ var init_tunnel_registry = __esm({
         if (live.retryTimer) clearTimeout(live.retryTimer);
         this.entries.delete(port);
         try {
-          const entry = await this.add(port, opts);
+          const entry = await this.add(port, opts, false);
           entry.retryCount = retryCount;
         } catch (err) {
           log7.error({ port, err: err.message, retry: retryCount }, "Tunnel retry failed");
@@ -9943,7 +9952,7 @@ async function handleArchive(ctx, core) {
     return;
   }
   await ctx.reply(
-    "\u26A0\uFE0F <b>Archive this session?</b>\n\nThis will:\n\u2022 Delete this topic and recreate it (clearing chat history)\n\u2022 The agent session will keep running\n\n<i>Chat history cannot be recovered.</i>",
+    "\u26A0\uFE0F <b>Archive this session?</b>\n\nThis will:\n\u2022 Stop the agent session\n\u2022 Delete this topic permanently\n\n<i>This cannot be undone.</i>",
     {
       parse_mode: "HTML",
       reply_markup: new InlineKeyboard3().text("\u{1F5D1} Yes, archive", `ar:yes:${identifier}`).text("\u274C Cancel", `ar:no:${identifier}`)
@@ -9964,18 +9973,7 @@ async function handleArchiveConfirm(ctx, core, chatId) {
     return;
   }
   const result = await core.archiveSession(identifier);
-  if (result.ok) {
-    const adapter = core.adapters.get("telegram");
-    if (adapter) {
-      try {
-        await adapter.sendMessage(identifier, {
-          type: "text",
-          text: "Chat history cleared. Session is still active \u2014 send a message to continue."
-        });
-      } catch {
-      }
-    }
-  } else {
+  if (!result.ok) {
     try {
       await ctx.editMessageText(`Failed to archive: <code>${escapeHtml4(result.error)}</code>`, { parse_mode: "HTML" });
     } catch {
@@ -15237,27 +15235,28 @@ var init_adapter = __esm({
           }
           return prev(method, payload, signal);
         });
-        await this.bot.api.setMyCommands(STATIC_COMMANDS, {
-          scope: { type: "chat", chat_id: this.telegramConfig.chatId }
-        });
+        this.registerCommandsWithRetry();
         this.bot.use((ctx, next) => {
           const chatId = ctx.chat?.id ?? ctx.callbackQuery?.message?.chat?.id;
           if (chatId !== this.telegramConfig.chatId) return;
           return next();
         });
-        const topics = await ensureTopics(
-          this.bot,
-          this.telegramConfig.chatId,
-          this.telegramConfig,
-          async (updates) => {
-            if (this.saveTopicIds) {
-              await this.saveTopicIds(updates);
-            } else {
-              await this.core.configManager.save({
-                channels: { telegram: updates }
-              });
+        const topics = await this.retryWithBackoff(
+          () => ensureTopics(
+            this.bot,
+            this.telegramConfig.chatId,
+            this.telegramConfig,
+            async (updates) => {
+              if (this.saveTopicIds) {
+                await this.saveTopicIds(updates);
+              } else {
+                await this.core.configManager.save({
+                  channels: { telegram: updates }
+                });
+              }
             }
-          }
+          ),
+          "ensureTopics"
         );
         this.notificationTopicId = topics.notificationTopicId;
         this.assistantTopicId = topics.assistantTopicId;
@@ -15505,6 +15504,40 @@ var init_adapter = __esm({
           });
         }
       }
+      /**
+       * Retry an async operation with exponential backoff.
+       * Used for Telegram API calls that may fail due to transient network issues.
+       */
+      async retryWithBackoff(fn, label, maxRetries = 5, baseDelayMs = 2e3) {
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+          try {
+            return await fn();
+          } catch (err) {
+            if (attempt === maxRetries) throw err;
+            const delay = baseDelayMs * Math.pow(2, attempt - 1);
+            log26.warn(
+              { err, attempt, maxRetries, delayMs: delay, operation: label },
+              `${label} failed, retrying in ${delay}ms`
+            );
+            await new Promise((r) => setTimeout(r, delay));
+          }
+        }
+        throw new Error("unreachable");
+      }
+      /**
+       * Register Telegram commands in the background with retries.
+       * Non-critical — bot works fine without autocomplete commands.
+       */
+      registerCommandsWithRetry() {
+        this.retryWithBackoff(
+          () => this.bot.api.setMyCommands(STATIC_COMMANDS, {
+            scope: { type: "chat", chat_id: this.telegramConfig.chatId }
+          }),
+          "setMyCommands"
+        ).catch((err) => {
+          log26.warn({ err }, "Failed to register Telegram commands after retries (non-critical)");
+        });
+      }
       async stop() {
         for (const tracker of this.sessionTrackers.values()) {
           tracker.destroy();
@@ -16221,10 +16254,6 @@ Task completed.
           this.sessionTrackers.delete(session.id);
         }
         await deleteSessionTopic(this.bot, chatId, oldTopicId);
-        const topicName = session.name ?? `Session ${session.id.slice(0, 6)}`;
-        const newTopicId = await createSessionTopic(this.bot, chatId, topicName);
-        session.archiving = false;
-        return String(newTopicId);
       }
     };
   }
@@ -18813,7 +18842,7 @@ async function setupIntegrations(config) {
       if (integration) {
         for (const item of integration.items) {
           const result = await item.install();
-          for (const log39 of result.logs) console.log(`  ${log39}`);
+          for (const log40 of result.logs) console.log(`  ${log40}`);
         }
       }
       console.log("Claude CLI integration installed.\n");
@@ -19176,6 +19205,10 @@ async function runSetup(configManager, opts) {
     const builtInOptions = [
       { label: "Telegram", value: "telegram" }
     ];
+    const officialAdapters = [
+      { label: "Discord", value: "official:@openacp/discord-adapter" },
+      { label: "Slack", value: "official:@openacp/slack-adapter" }
+    ];
     const communityOptions = communityAdapters.map((a) => ({
       label: `${a.icon} ${a.displayName}${a.verified ? " (verified)" : ""}`,
       value: `community:${a.name}`
@@ -19185,6 +19218,7 @@ async function runSetup(configManager, opts) {
         message: "Which channels do you want to set up?",
         options: [
           ...builtInOptions.map((o) => ({ value: o.value, label: o.label, hint: "built-in" })),
+          ...officialAdapters.map((o) => ({ value: o.value, label: o.label, hint: "official" })),
           ...communityOptions.length > 0 ? communityOptions.map((o) => ({ value: o.value, label: o.label, hint: "from plugin registry" })) : []
         ],
         required: true,
@@ -19214,6 +19248,54 @@ async function runSetup(configManager, opts) {
           description: telegramPlugin.description
         });
       }
+      if (channelId.startsWith("official:")) {
+        const npmPackage = channelId.slice("official:".length);
+        const { execFileSync: execFileSync8 } = await import("child_process");
+        const pluginsDir = path47.join(getGlobalRoot(), "plugins");
+        const nodeModulesDir = path47.join(pluginsDir, "node_modules");
+        const installedPath = path47.join(nodeModulesDir, npmPackage);
+        if (!fs41.existsSync(installedPath)) {
+          try {
+            clack9.log.step(`Installing ${npmPackage}...`);
+            execFileSync8("npm", ["install", npmPackage, "--prefix", pluginsDir, "--save"], {
+              stdio: "inherit",
+              timeout: 6e4
+            });
+          } catch {
+            console.log(fail(`Failed to install ${npmPackage}.`));
+            continue;
+          }
+        }
+        try {
+          const installedPkgPath = path47.join(nodeModulesDir, npmPackage, "package.json");
+          const installedPkg = JSON.parse(fs41.readFileSync(installedPkgPath, "utf-8"));
+          const pluginModule = await import(path47.join(nodeModulesDir, npmPackage, installedPkg.main ?? "dist/index.js"));
+          const plugin = pluginModule.default;
+          if (plugin?.install) {
+            const installCtx = createInstallContext2({
+              pluginName: plugin.name ?? npmPackage,
+              settingsManager,
+              basePath: settingsManager.getBasePath()
+            });
+            await plugin.install(installCtx);
+          }
+          pluginRegistry.register(plugin?.name ?? npmPackage, {
+            version: installedPkg.version,
+            source: "npm",
+            enabled: true,
+            settingsPath: settingsManager.getSettingsPath(plugin?.name ?? npmPackage),
+            description: plugin?.description ?? installedPkg.description
+          });
+        } catch (err) {
+          console.log(fail(`Failed to load ${npmPackage}: ${err.message}`));
+          pluginRegistry.register(npmPackage, {
+            version: "unknown",
+            source: "npm",
+            enabled: false,
+            settingsPath: settingsManager.getSettingsPath(npmPackage)
+          });
+        }
+      }
       if (channelId.startsWith("community:")) {
         const npmPackage = channelId.slice("community:".length);
         const { execFileSync: execFileSync8 } = await import("child_process");
@@ -19906,7 +19988,7 @@ function resolveAgentCommand(cmd) {
   }
   return { command: cmd, args: [] };
 }
-var log32, AgentInstance;
+var log33, AgentInstance;
 var init_agent_instance = __esm({
   "src/core/agents/agent-instance.ts"() {
     "use strict";
@@ -19918,7 +20000,7 @@ var init_agent_instance = __esm({
     init_mcp_manager();
     init_debug_tracer();
     init_log();
-    log32 = createChildLogger({ module: "agent-instance" });
+    log33 = createChildLogger({ module: "agent-instance" });
     AgentInstance = class _AgentInstance extends TypedEmitter {
       connection;
       child;
@@ -19940,7 +20022,7 @@ var init_agent_instance = __esm({
       static async spawnSubprocess(agentDef, workingDirectory) {
         const instance = new _AgentInstance(agentDef.name);
         const resolved = resolveAgentCommand(agentDef.command);
-        log32.debug(
+        log33.debug(
           {
             agentName: agentDef.name,
             command: resolved.command,
@@ -20014,13 +20096,13 @@ var init_agent_instance = __esm({
           }
         });
         if (initResponse.protocolVersion !== PROTOCOL_VERSION) {
-          log32.warn(
+          log33.warn(
             { expected: PROTOCOL_VERSION, got: initResponse.protocolVersion },
             "ACP protocol version mismatch \u2014 some features may not work correctly"
           );
         }
         instance.promptCapabilities = initResponse.agentCapabilities?.promptCapabilities;
-        log32.info(
+        log33.info(
           { promptCapabilities: instance.promptCapabilities ?? {} },
           "Agent prompt capabilities"
         );
@@ -20029,7 +20111,7 @@ var init_agent_instance = __esm({
       setupCrashDetection() {
         this.child.on("exit", (code, signal) => {
           if (this._destroying) return;
-          log32.info(
+          log33.info(
             { sessionId: this.sessionId, exitCode: code, signal },
             "Agent process exited"
           );
@@ -20044,11 +20126,11 @@ ${stderr}`
           }
         });
         this.connection.closed.then(() => {
-          log32.debug({ sessionId: this.sessionId }, "ACP connection closed");
+          log33.debug({ sessionId: this.sessionId }, "ACP connection closed");
         });
       }
       static async spawn(agentDef, workingDirectory, mcpServers) {
-        log32.debug(
+        log33.debug(
           { agentName: agentDef.name, command: agentDef.command },
           "Spawning agent"
         );
@@ -20065,14 +20147,14 @@ ${stderr}`
         instance.sessionId = response.sessionId;
         instance.debugTracer = createDebugTracer(response.sessionId, workingDirectory);
         instance.setupCrashDetection();
-        log32.info(
+        log33.info(
           { sessionId: response.sessionId, durationMs: Date.now() - spawnStart },
           "Agent spawn complete"
         );
         return instance;
       }
       static async resume(agentDef, workingDirectory, agentSessionId, mcpServers) {
-        log32.debug({ agentName: agentDef.name, agentSessionId }, "Resuming agent");
+        log33.debug({ agentName: agentDef.name, agentSessionId }, "Resuming agent");
         const spawnStart = Date.now();
         const instance = await _AgentInstance.spawnSubprocess(
           agentDef,
@@ -20085,12 +20167,12 @@ ${stderr}`
           });
           instance.sessionId = response.sessionId;
           instance.debugTracer = createDebugTracer(response.sessionId, workingDirectory);
-          log32.info(
+          log33.info(
             { sessionId: response.sessionId, durationMs: Date.now() - spawnStart },
             "Agent resume complete"
           );
         } catch (err) {
-          log32.warn(
+          log33.warn(
             { err, agentSessionId },
             "Resume failed, falling back to new session"
           );
@@ -20101,7 +20183,7 @@ ${stderr}`
           });
           instance.sessionId = response.sessionId;
           instance.debugTracer = createDebugTracer(response.sessionId, workingDirectory);
-          log32.info(
+          log33.info(
             { sessionId: response.sessionId, durationMs: Date.now() - spawnStart },
             "Agent fallback spawn complete"
           );
@@ -20381,7 +20463,7 @@ ${stderr}`
             contentBlocks.push({ type: "audio", data: data.toString("base64"), mimeType: att.mimeType });
           } else {
             if ((att.type === "image" || att.type === "audio") && !tooLarge) {
-              log32.debug(
+              log33.debug(
                 { type: att.type, capabilities: this.promptCapabilities ?? {} },
                 "Agent does not support %s content, falling back to file path",
                 att.type
@@ -21209,12 +21291,12 @@ var init_session_manager = __esm({
 });
 
 // src/core/sessions/session-bridge.ts
-var log33, SessionBridge;
+var log34, SessionBridge;
 var init_session_bridge = __esm({
   "src/core/sessions/session-bridge.ts"() {
     "use strict";
     init_log();
-    log33 = createChildLogger({ module: "session-bridge" });
+    log34 = createChildLogger({ module: "session-bridge" });
     SessionBridge = class {
       constructor(session, adapter, deps) {
         this.session = session;
@@ -21240,16 +21322,16 @@ var init_session_bridge = __esm({
             if (!result) return;
             this.tracer?.log("core", { step: "dispatch", sessionId, message: result.message });
             this.adapter.sendMessage(sessionId, result.message).catch((err) => {
-              log33.error({ err, sessionId }, "Failed to send message to adapter");
+              log34.error({ err, sessionId }, "Failed to send message to adapter");
             });
           } else {
             this.tracer?.log("core", { step: "dispatch", sessionId, message });
             this.adapter.sendMessage(sessionId, message).catch((err) => {
-              log33.error({ err, sessionId }, "Failed to send message to adapter");
+              log34.error({ err, sessionId }, "Failed to send message to adapter");
             });
           }
         } catch (err) {
-          log33.error({ err, sessionId }, "Error in sendMessage middleware");
+          log34.error({ err, sessionId }, "Error in sendMessage middleware");
         }
       }
       connect() {
@@ -21304,20 +21386,20 @@ var init_session_bridge = __esm({
                 }, async (e) => e).catch(() => {
                 });
               } catch (err) {
-                log33.error({ err, sessionId: this.session.id }, "Error handling agent event after middleware");
+                log34.error({ err, sessionId: this.session.id }, "Error handling agent event after middleware");
               }
             }).catch(() => {
               try {
                 this.handleAgentEvent(event);
               } catch (err) {
-                log33.error({ err, sessionId: this.session.id }, "Error handling agent event (middleware fallback)");
+                log34.error({ err, sessionId: this.session.id }, "Error handling agent event (middleware fallback)");
               }
             });
           } else {
             try {
               this.handleAgentEvent(event);
             } catch (err) {
-              log33.error({ err, sessionId: this.session.id }, "Error handling agent event");
+              log34.error({ err, sessionId: this.session.id }, "Error handling agent event");
             }
           }
         };
@@ -21383,7 +21465,7 @@ var init_session_bridge = __esm({
                   text: "",
                   attachment: att
                 });
-              }).catch((err) => log33.error({ err }, "Failed to save agent image"));
+              }).catch((err) => log34.error({ err }, "Failed to save agent image"));
             }
             break;
           }
@@ -21400,12 +21482,12 @@ var init_session_bridge = __esm({
                   text: "",
                   attachment: att
                 });
-              }).catch((err) => log33.error({ err }, "Failed to save agent audio"));
+              }).catch((err) => log34.error({ err }, "Failed to save agent audio"));
             }
             break;
           }
           case "commands_update":
-            log33.debug({ commands: event.commands }, "Commands available");
+            log34.debug({ commands: event.commands }, "Commands available");
             this.adapter.sendSkillCommands?.(this.session.id, event.commands);
             break;
           case "system_message":
@@ -21485,7 +21567,7 @@ var init_session_bridge = __esm({
           if (permReq.description.toLowerCase().includes("openacp")) {
             const allowOption = permReq.options.find((o) => o.isAllow);
             if (allowOption) {
-              log33.info(
+              log34.info(
                 { sessionId: this.session.id, requestId: permReq.id },
                 "Auto-approving openacp command"
               );
@@ -21505,7 +21587,7 @@ var init_session_bridge = __esm({
           if (this.session.dangerousMode) {
             const allowOption = permReq.options.find((o) => o.isAllow);
             if (allowOption) {
-              log33.info(
+              log34.info(
                 { sessionId: this.session.id, requestId: permReq.id, optionId: allowOption.id },
                 "Dangerous mode: auto-approving permission"
               );
@@ -21553,13 +21635,17 @@ var init_session_bridge = __esm({
           }
         };
         this.session.on("status_change", this.statusChangeHandler);
-        this.namedHandler = (name) => {
-          this.deps.sessionManager.patchRecord(this.session.id, { name });
+        this.namedHandler = async (name) => {
+          const record = this.deps.sessionManager.getSessionRecord(this.session.id);
+          const alreadyNamed = !!record?.name;
+          await this.deps.sessionManager.patchRecord(this.session.id, { name });
           this.deps.eventBus?.emit("session:updated", {
             sessionId: this.session.id,
             name
           });
-          this.adapter.renameSessionThread(this.session.id, name);
+          if (!alreadyNamed) {
+            await this.adapter.renameSessionThread(this.session.id, name);
+          }
         };
         this.session.on("named", this.namedHandler);
         this.promptCountHandler = (count) => {
@@ -21717,13 +21803,13 @@ function computeLineDiff(oldStr, newStr) {
     removed: Math.max(0, oldLines.length - prefixLen - suffixLen)
   };
 }
-var log34, MessageTransformer;
+var log35, MessageTransformer;
 var init_message_transformer = __esm({
   "src/core/message-transformer.ts"() {
     "use strict";
     init_extract_file_info();
     init_log();
-    log34 = createChildLogger({ module: "message-transformer" });
+    log35 = createChildLogger({ module: "message-transformer" });
     MessageTransformer = class {
       tunnelService;
       /** Cache rawInput from tool_call so it's available in tool_update (which often lacks it) */
@@ -21889,14 +21975,14 @@ var init_message_transformer = __esm({
           }
         }
         if (!this.tunnelService || !sessionContext) {
-          log34.debug(
+          log35.debug(
             { hasTunnel: !!this.tunnelService, hasCtx: !!sessionContext, kind },
             "enrichWithViewerLinks: skipping (no tunnel or session context)"
           );
           return;
         }
         const name = "name" in event ? event.name || "" : "";
-        log34.debug(
+        log35.debug(
           { name, kind, status: event.status, hasContent: !!event.content, hasRawInput: !!event.rawInput },
           "enrichWithViewerLinks: inspecting event"
         );
@@ -21908,7 +21994,7 @@ var init_message_transformer = __esm({
           event.meta
         );
         if (!fileInfo) {
-          log34.debug(
+          log35.debug(
             { name, kind, hasContent: !!event.content, hasRawInput: !!event.rawInput, hasMeta: !!event.meta },
             "enrichWithViewerLinks: extractFileInfo returned null"
           );
@@ -21916,10 +22002,10 @@ var init_message_transformer = __esm({
         }
         const publicUrl = this.tunnelService.getPublicUrl();
         if (publicUrl.startsWith("http://localhost") || publicUrl.startsWith("http://127.0.0.1")) {
-          log34.debug({ kind, filePath: fileInfo.filePath }, "enrichWithViewerLinks: skipping (no public tunnel URL)");
+          log35.debug({ kind, filePath: fileInfo.filePath }, "enrichWithViewerLinks: skipping (no public tunnel URL)");
           return;
         }
-        log34.info(
+        log35.info(
           {
             name,
             kind,
@@ -21965,12 +22051,12 @@ var init_message_transformer = __esm({
 // src/core/sessions/session-store.ts
 import fs45 from "fs";
 import path51 from "path";
-var log35, DEBOUNCE_MS2, JsonFileSessionStore;
+var log36, DEBOUNCE_MS2, JsonFileSessionStore;
 var init_session_store = __esm({
   "src/core/sessions/session-store.ts"() {
     "use strict";
     init_log();
-    log35 = createChildLogger({ module: "session-store" });
+    log36 = createChildLogger({ module: "session-store" });
     DEBOUNCE_MS2 = 2e3;
     JsonFileSessionStore = class {
       records = /* @__PURE__ */ new Map();
@@ -22058,7 +22144,7 @@ var init_session_store = __esm({
             fs45.readFileSync(this.filePath, "utf-8")
           );
           if (raw.version !== 1) {
-            log35.warn(
+            log36.warn(
               { version: raw.version },
               "Unknown session store version, skipping load"
             );
@@ -22067,9 +22153,9 @@ var init_session_store = __esm({
           for (const [id, record] of Object.entries(raw.sessions)) {
             this.records.set(id, record);
           }
-          log35.debug({ count: this.records.size }, "Loaded session records");
+          log36.debug({ count: this.records.size }, "Loaded session records");
         } catch (err) {
-          log35.error({ err }, "Failed to load session store, backing up corrupt file");
+          log36.error({ err }, "Failed to load session store, backing up corrupt file");
           try {
             fs45.renameSync(this.filePath, `${this.filePath}.bak`);
           } catch {
@@ -22089,7 +22175,7 @@ var init_session_store = __esm({
           }
         }
         if (removed > 0) {
-          log35.info({ removed }, "Cleaned up expired session records");
+          log36.info({ removed }, "Cleaned up expired session records");
           this.scheduleDiskWrite();
         }
       }
@@ -22104,19 +22190,20 @@ var init_session_store = __esm({
 });
 
 // src/core/sessions/session-factory.ts
-var log36, SessionFactory;
+var log37, SessionFactory;
 var init_session_factory = __esm({
   "src/core/sessions/session-factory.ts"() {
     "use strict";
     init_session2();
     init_log();
-    log36 = createChildLogger({ module: "session-factory" });
+    log37 = createChildLogger({ module: "session-factory" });
     SessionFactory = class {
-      constructor(agentManager, sessionManager, speechServiceAccessor, eventBus) {
+      constructor(agentManager, sessionManager, speechServiceAccessor, eventBus, instanceRoot) {
         this.agentManager = agentManager;
         this.sessionManager = sessionManager;
         this.speechServiceAccessor = speechServiceAccessor;
         this.eventBus = eventBus;
+        this.instanceRoot = instanceRoot;
       }
       middlewareChain;
       get speechService() {
@@ -22143,14 +22230,73 @@ var init_session_factory = __esm({
             channelId: result.channelId
           };
         }
-        const agentInstance = createParams.resumeAgentSessionId ? await this.agentManager.resume(
-          createParams.agentName,
-          createParams.workingDirectory,
-          createParams.resumeAgentSessionId
-        ) : await this.agentManager.spawn(
-          createParams.agentName,
-          createParams.workingDirectory
-        );
+        let agentInstance;
+        try {
+          agentInstance = createParams.resumeAgentSessionId ? await this.agentManager.resume(
+            createParams.agentName,
+            createParams.workingDirectory,
+            createParams.resumeAgentSessionId
+          ) : await this.agentManager.spawn(
+            createParams.agentName,
+            createParams.workingDirectory
+          );
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          const guidanceLines = [
+            `\u274C Failed to start agent "${createParams.agentName}": ${message}`,
+            "",
+            "Run the agent CLI once in a terminal for this OpenACP instance to complete login or setup."
+          ];
+          if (this.instanceRoot) {
+            guidanceLines.push(
+              "",
+              "Copy and run this command in your terminal:",
+              `  cd "${this.instanceRoot}" && openacp agents run ${createParams.agentName}`
+            );
+          } else {
+            guidanceLines.push(
+              "",
+              "Copy and run this command in your terminal (same project where you started OpenACP):",
+              `  openacp agents run ${createParams.agentName}`
+            );
+          }
+          guidanceLines.push(
+            "",
+            "After setup completes, retry creating the session here."
+          );
+          const guidance = {
+            type: "system_message",
+            message: guidanceLines.join("\n")
+          };
+          const failedSession = new Session({
+            id: createParams.existingSessionId,
+            channelId: createParams.channelId,
+            agentName: createParams.agentName,
+            workingDirectory: createParams.workingDirectory,
+            // Dummy agent instance — will never be prompted
+            agentInstance: {
+              sessionId: "",
+              prompt: async () => {
+              },
+              cancel: async () => {
+              },
+              destroy: async () => {
+              },
+              on: () => {
+              },
+              off: () => {
+              }
+            },
+            speechService: this.speechService
+          });
+          this.sessionManager.registerSession(failedSession);
+          failedSession.emit("agent_event", guidance);
+          this.eventBus.emit("agent:event", {
+            sessionId: failedSession.id,
+            event: guidance
+          });
+          throw err;
+        }
         agentInstance.middlewareChain = this.middlewareChain;
         const session = new Session({
           id: createParams.existingSessionId,
@@ -22583,7 +22729,7 @@ function createPluginContext(opts) {
     }
   };
   const baseLog = opts.log ?? noopLog;
-  const log39 = typeof baseLog.child === "function" ? baseLog.child({ plugin: pluginName }) : baseLog;
+  const log40 = typeof baseLog.child === "function" ? baseLog.child({ plugin: pluginName }) : baseLog;
   const storageImpl = new PluginStorageImpl(storagePath);
   const storage = {
     async get(key) {
@@ -22610,7 +22756,7 @@ function createPluginContext(opts) {
   const ctx = {
     pluginName,
     pluginConfig,
-    log: log39,
+    log: log40,
     storage,
     on(event, handler) {
       requirePermission(permissions, "events:read", "on()");
@@ -22645,7 +22791,7 @@ function createPluginContext(opts) {
       const registry = serviceRegistry.get("command-registry");
       if (registry && typeof registry.register === "function") {
         registry.register(def, pluginName);
-        log39.debug(`Command '/${def.name}' registered`);
+        log40.debug(`Command '/${def.name}' registered`);
       }
     },
     async sendMessage(_sessionId, _content) {
@@ -22966,7 +23112,7 @@ var init_lifecycle_manager = __esm({
 // src/core/core.ts
 import path54 from "path";
 import os26 from "os";
-var log37, OpenACPCore;
+var log38, OpenACPCore;
 var init_core = __esm({
   "src/core/core.ts"() {
     "use strict";
@@ -22984,7 +23130,7 @@ var init_core = __esm({
     init_middleware_chain();
     init_error_tracker();
     init_log();
-    log37 = createChildLogger({ module: "core" });
+    log38 = createChildLogger({ module: "core" });
     OpenACPCore = class {
       configManager;
       agentCatalog;
@@ -23045,7 +23191,8 @@ var init_core = __esm({
           this.agentManager,
           this.sessionManager,
           () => this.speechService,
-          this.eventBus
+          this.eventBus,
+          ctx?.root
         );
         this.lifecycleManager = new LifecycleManager({
           serviceRegistry: new ServiceRegistry(),
@@ -23066,7 +23213,7 @@ var init_core = __esm({
             if (configPath === "logging.level" && typeof value === "string") {
               const { setLogLevel: setLogLevel2 } = await Promise.resolve().then(() => (init_log(), log_exports));
               setLogLevel2(value);
-              log37.info({ level: value }, "Log level changed at runtime");
+              log38.info({ level: value }, "Log level changed at runtime");
             }
             if (configPath.startsWith("speech.")) {
               const speechSvc = this.speechService;
@@ -23077,7 +23224,7 @@ var init_core = __esm({
                   tts: { provider: null, providers: {} }
                 };
                 speechSvc.refreshProviders(newSpeechConfig);
-                log37.info("Speech service config updated at runtime");
+                log38.info("Speech service config updated at runtime");
               }
             }
           }
@@ -23095,10 +23242,21 @@ var init_core = __esm({
       }
       async start() {
         this.agentCatalog.refreshRegistryIfStale().catch((err) => {
-          log37.warn({ err }, "Background registry refresh failed");
+          log38.warn({ err }, "Background registry refresh failed");
         });
-        for (const adapter of this.adapters.values()) {
-          await adapter.start();
+        const failures = [];
+        for (const [name, adapter] of this.adapters.entries()) {
+          try {
+            await adapter.start();
+          } catch (err) {
+            log38.error({ err, adapter: name }, `Adapter "${name}" failed to start`);
+            failures.push({ name, error: err });
+          }
+        }
+        if (failures.length > 0 && failures.length === this.adapters.size) {
+          throw new Error(
+            `All adapters failed to start: ${failures.map((f) => f.name).join(", ")}`
+          );
         }
       }
       async stop() {
@@ -23129,20 +23287,9 @@ var init_core = __esm({
         if (!adapter) return { ok: false, error: "Adapter not found for session" };
         if (!adapter.archiveSessionTopic) return { ok: false, error: "Adapter does not support topic archiving" };
         try {
-          const newThreadId = await adapter.archiveSessionTopic(session.id);
-          session.threadId = newThreadId;
-          try {
-            const platform2 = {};
-            if (session.channelId === "telegram") {
-              platform2.topicId = Number(newThreadId);
-            } else {
-              platform2.threadId = newThreadId;
-            }
-            await this.sessionManager.patchRecord(sessionId, { platform: platform2 });
-          } catch (patchErr) {
-            log37.warn({ err: patchErr, sessionId }, "Failed to update session record after archive \u2014 session will work but may not survive restart");
-          }
-          return { ok: true, newThreadId };
+          await adapter.archiveSessionTopic(session.id);
+          await this.sessionManager.cancelSession(sessionId);
+          return { ok: true };
         } catch (err) {
           session.archiving = false;
           return { ok: false, error: err.message };
@@ -23150,7 +23297,7 @@ var init_core = __esm({
       }
       // --- Message Routing ---
       async handleMessage(message) {
-        log37.debug(
+        log38.debug(
           {
             channelId: message.channelId,
             threadId: message.threadId,
@@ -23169,7 +23316,7 @@ var init_core = __esm({
         }
         const access2 = this.securityGuard.checkAccess(message);
         if (!access2.allowed) {
-          log37.warn({ userId: message.userId, reason: access2.reason }, "Access denied");
+          log38.warn({ userId: message.userId, reason: access2.reason }, "Access denied");
           if (access2.reason.includes("Session limit")) {
             const adapter = this.adapters.get(message.channelId);
             if (adapter) {
@@ -23189,7 +23336,7 @@ var init_core = __esm({
           session = await this.lazyResume(message) ?? void 0;
         }
         if (!session) {
-          log37.warn(
+          log38.warn(
             { channelId: message.channelId, threadId: message.threadId },
             "No session found for thread (in-memory miss + lazy resume returned null)"
           );
@@ -23249,7 +23396,7 @@ var init_core = __esm({
           currentPromptCount: session.promptCount,
           agentSwitchHistory: session.agentSwitchHistory
         });
-        log37.info(
+        log38.info(
           { sessionId: session.id, agentName: params.agentName },
           "Session created via pipeline"
         );
@@ -23258,7 +23405,7 @@ var init_core = __esm({
       async handleNewSession(channelId, agentName, workspacePath, options) {
         const config = this.configManager.get();
         const resolvedAgent = agentName || config.defaultAgent;
-        log37.info({ channelId, agentName: resolvedAgent }, "New session request");
+        log38.info({ channelId, agentName: resolvedAgent }, "New session request");
         const agentDef = this.agentCatalog.resolve(resolvedAgent);
         const resolvedWorkspace = this.configManager.resolveWorkspace(
           workspacePath || agentDef?.workingDirectory
@@ -23407,7 +23554,7 @@ var init_core = __esm({
             params.contextOptions
           );
         } catch (err) {
-          log37.warn({ err }, "Context building failed, proceeding without context");
+          log38.warn({ err }, "Context building failed, proceeding without context");
         }
         const session = await this.createSession({
           channelId: params.channelId,
@@ -23449,6 +23596,21 @@ var init_core = __esm({
         const caps = getAgentCapabilities(toAgent);
         const canResume = !!(lastEntry && caps.supportsResume && lastEntry.promptCount === 0);
         const resumed = canResume;
+        const startEvent = {
+          type: "system_message",
+          message: `Switching from ${fromAgent} to ${toAgent}...`
+        };
+        session.emit("agent_event", startEvent);
+        this.eventBus.emit("agent:event", {
+          sessionId,
+          event: startEvent
+        });
+        this.eventBus.emit("session:agentSwitch", {
+          sessionId,
+          fromAgent,
+          toAgent,
+          status: "starting"
+        });
         const bridge = this.bridges.get(sessionId);
         if (bridge) bridge.disconnect();
         const switchAdapter = this.adapters.get(session.channelId);
@@ -23483,7 +23645,40 @@ var init_core = __esm({
               return instance;
             }
           });
+          const successEvent = {
+            type: "system_message",
+            message: resumed ? `Switched to ${toAgent} (resumed previous session).` : `Switched to ${toAgent} (new session).`
+          };
+          session.emit("agent_event", successEvent);
+          this.eventBus.emit("agent:event", {
+            sessionId,
+            event: successEvent
+          });
+          this.eventBus.emit("session:agentSwitch", {
+            sessionId,
+            fromAgent,
+            toAgent,
+            status: "succeeded",
+            resumed
+          });
         } catch (err) {
+          const errorMessage = err instanceof Error ? err.message : String(err);
+          const failedEvent = {
+            type: "system_message",
+            message: `Failed to switch to ${toAgent}: ${errorMessage}`
+          };
+          session.emit("agent_event", failedEvent);
+          this.eventBus.emit("agent:event", {
+            sessionId,
+            event: failedEvent
+          });
+          this.eventBus.emit("session:agentSwitch", {
+            sessionId,
+            fromAgent,
+            toAgent,
+            status: "failed",
+            error: errorMessage
+          });
           try {
             let rollbackInstance;
             try {
@@ -23501,10 +23696,10 @@ var init_core = __esm({
               const rollbackBridge = this.createBridge(session, adapter);
               rollbackBridge.connect();
             }
-            log37.warn({ sessionId, fromAgent, toAgent, err }, "Agent switch failed, rolled back to previous agent");
+            log38.warn({ sessionId, fromAgent, toAgent, err }, "Agent switch failed, rolled back to previous agent");
           } catch (rollbackErr) {
             session.fail(`Switch failed and rollback failed: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`);
-            log37.error({ sessionId, fromAgent, toAgent, err, rollbackErr }, "Agent switch failed and rollback also failed");
+            log38.error({ sessionId, fromAgent, toAgent, err, rollbackErr }, "Agent switch failed and rollback also failed");
           }
           throw err;
         }
@@ -23552,14 +23747,14 @@ var init_core = __esm({
           (p2) => String(p2.topicId) === message.threadId
         );
         if (!record) {
-          log37.debug(
+          log38.debug(
             { threadId: message.threadId, channelId: message.channelId },
             "No session record found for thread"
           );
           return null;
         }
         if (record.status === "error" || record.status === "cancelled") {
-          log37.debug(
+          log38.debug(
             {
               threadId: message.threadId,
               sessionId: record.sessionId,
@@ -23569,7 +23764,7 @@ var init_core = __esm({
           );
           return null;
         }
-        log37.info(
+        log38.info(
           {
             threadId: message.threadId,
             sessionId: record.sessionId,
@@ -23593,13 +23788,13 @@ var init_core = __esm({
             if (record.firstAgent) session.firstAgent = record.firstAgent;
             if (record.agentSwitchHistory) session.agentSwitchHistory = record.agentSwitchHistory;
             if (record.currentPromptCount != null) session.promptCount = record.currentPromptCount;
-            log37.info(
+            log38.info(
               { sessionId: session.id, threadId: message.threadId },
               "Lazy resume successful"
             );
             return session;
           } catch (err) {
-            log37.error({ err, record }, "Lazy resume failed");
+            log38.error({ err, record }, "Lazy resume failed");
             const adapter = this.adapters.get(message.channelId);
             if (adapter) {
               try {
@@ -24094,14 +24289,14 @@ async function runPostUpgradeChecks(config) {
         const { ensureCloudflared: ensureCloudflared2 } = await Promise.resolve().then(() => (init_install_cloudflared(), install_cloudflared_exports));
         await ensureCloudflared2();
       } catch (err) {
-        log38.warn(
+        log39.warn(
           { err: err.message },
           "Could not install cloudflared. Tunnel may not work."
         );
       }
     } else {
       if (!commandExists(config.tunnel.provider)) {
-        log38.warn(
+        log39.warn(
           `Tunnel provider "${config.tunnel.provider}" is not installed. Install it or switch to cloudflare (free, auto-installed).`
         );
       }
@@ -24113,7 +24308,7 @@ async function runPostUpgradeChecks(config) {
     if (integration) {
       const allInstalled = integration.items.every((item) => item.isInstalled());
       if (!allInstalled) {
-        log38.info(
+        log39.info(
           'Claude CLI integration not installed. Run "openacp integrate claude" for session transfer + tunnel skill.'
         );
       }
@@ -24123,7 +24318,7 @@ async function runPostUpgradeChecks(config) {
           const { ensureJq: ensureJq2 } = await Promise.resolve().then(() => (init_install_jq(), install_jq_exports));
           await ensureJq2();
         } catch (err) {
-          log38.warn(
+          log39.warn(
             { err: err.message },
             "Could not install jq. Handoff hooks may not work."
           );
@@ -24133,7 +24328,7 @@ async function runPostUpgradeChecks(config) {
   } catch {
   }
   if (!commandExists("unzip")) {
-    log38.warn(
+    log39.warn(
       "unzip is not installed. Some agent installations (binary distribution) may fail. Install: brew install unzip (macOS) or apt install unzip (Linux)"
     );
   }
@@ -24146,20 +24341,20 @@ async function runPostUpgradeChecks(config) {
       (a) => a.distribution === "uvx"
     );
     if (hasUvxAgent && !commandExists("uvx")) {
-      log38.warn(
+      log39.warn(
         "uvx is not installed but you have Python-based agents. Install: pip install uv"
       );
     }
   } catch {
   }
 }
-var log38;
+var log39;
 var init_post_upgrade = __esm({
   "src/cli/post-upgrade.ts"() {
     "use strict";
     init_log();
     init_agent_dependencies();
-    log38 = createChildLogger({ module: "post-upgrade" });
+    log39 = createChildLogger({ module: "post-upgrade" });
   }
 });
 
@@ -26323,7 +26518,7 @@ a "Handoff" slash command to Claude Code.
     if (uninstall) {
       console.log(`Removing ${agent}/${item.id}...`);
       const result = await item.uninstall();
-      for (const log39 of result.logs) console.log(`  ${log39}`);
+      for (const log40 of result.logs) console.log(`  ${log40}`);
       if (result.success) {
         console.log(`  ${item.name} removed.`);
       } else {
@@ -26333,7 +26528,7 @@ a "Handoff" slash command to Claude Code.
     } else {
       console.log(`Installing ${agent}/${item.id}...`);
       const result = await item.install();
-      for (const log39 of result.logs) console.log(`  ${log39}`);
+      for (const log40 of result.logs) console.log(`  ${log40}`);
       if (result.success) {
         console.log(`  ${item.name} installed.`);
       } else {