fix(gateway): bound traced channel startup handoff

steipete · steipete · commit ae54d810bc00 · 2026-05-16T14:12:40.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Gateway/channels: hand off traced channel account startup outside the startup diagnostic phase so long-lived channel tasks do not keep liveness warnings pinned to channel startup. Refs #82398.
 - Gateway/WebChat: route image attachments through a configured vision-capable `imageModel` plan before inlining images, and carry that image-model fallback chain through runtime retries. (#82524) Thanks @frankekn.
 - WebChat: show progress while manual `/compact` is running by streaming a session operation event to subscribed Control UI clients. Fixes #82407. Thanks @Conan-Scott.
 - Codex app-server: limit canonical OpenAI Codex app-server attribution rewrites to local transcript and trajectory records, leaving runtime/tool routing on the selected OpenAI model metadata so OpenAI API-key backup profiles keep their billing path.
diff --git a/src/gateway/server-channels.test.ts b/src/gateway/server-channels.test.ts
@@ -733,12 +733,53 @@ describe("server-channels auto restart", () => {
     const manager = createManager({ startupTrace });
 
     await manager.startChannels();
+    expect(startAccount).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(0);
+    await flushMicrotasks();
 
     const names = measureMock.mock.calls.map(([name]) => name);
     expect(names).toContain("channels.discord.start");
     expect(names).toContain("channels.discord.list-accounts");
     expect(names).toContain("channels.discord.runtime");
     expect(names).toContain("channels.discord.approval-bootstrap");
+    expect(names).toContain("channels.discord.start-account-handoff");
+    expect(startAccount).toHaveBeenCalledTimes(1);
+  });
+
+  it("ends startup trace spans before long-lived channel account tasks settle", async () => {
+    const activeNames = new Set<string>();
+    const measuredNames: string[] = [];
+    const startupTrace = {
+      measure: async <T>(name: string, run: () => T | Promise<T>) => {
+        activeNames.add(name);
+        measuredNames.push(name);
+        try {
+          return await run();
+        } finally {
+          activeNames.delete(name);
+        }
+      },
+    };
+    const channelTask = createDeferred();
+    const startAccount = vi.fn(() => channelTask.promise);
+
+    installTestRegistry(createTestPlugin({ startAccount }));
+    const manager = createManager({ startupTrace });
+
+    await manager.startChannels();
+    await vi.advanceTimersByTimeAsync(0);
+    await flushMicrotasks();
+
+    expect(startAccount).toHaveBeenCalledTimes(1);
+    expect(measuredNames).toContain("channels.discord.start-account-handoff");
+    expect(activeNames.has("channels.discord.start-account-handoff")).toBe(false);
+    expect(
+      manager.getRuntimeSnapshot().channelAccounts.discord?.[DEFAULT_ACCOUNT_ID]?.running,
+    ).toBe(true);
+
+    channelTask.resolve();
+    await flushMicrotasks();
   });
 
   it("limits whole-channel account startup fanout to four", async () => {
diff --git a/src/gateway/server-channels.ts b/src/gateway/server-channels.ts
@@ -39,6 +39,13 @@ const MAX_RESTART_ATTEMPTS = 10;
 const CHANNEL_STOP_ABORT_TIMEOUT_MS = 5_000;
 const CHANNEL_STARTUP_CONCURRENCY = 4;
 
+function waitForChannelStartupHandoff(): Promise<void> {
+  return new Promise((resolve) => {
+    const handle = setImmediate(resolve);
+    handle.unref?.();
+  });
+}
+
 type ChannelRuntimeStore = {
   aborts: Map<string, AbortController>;
   starting: Map<string, Promise<void>>;
@@ -512,9 +519,13 @@ export function createChannelManager(opts: ChannelManagerOptions): ChannelManage
             lastError: null,
             reconnectAttempts: preserveRestartAttempts ? (restartAttempts.get(rKey) ?? 0) : 0,
           });
-          const task = Promise.resolve().then(() =>
-            measureStartup(`channels.${channelId}.start-account`, () =>
-              startAccount({
+          const task = Promise.resolve().then(async () => {
+            if (startupTrace) {
+              await waitForChannelStartupHandoff();
+            }
+            let startAccountTask: ReturnType<typeof startAccount> | undefined;
+            await measureStartup(`channels.${channelId}.start-account-handoff`, () => {
+              startAccountTask = startAccount({
                 cfg,
                 accountId: id,
                 account,
@@ -524,9 +535,10 @@ export function createChannelManager(opts: ChannelManagerOptions): ChannelManage
                 getStatus: () => getRuntime(channelId, id),
                 setStatus: (next) => setRuntime(channelId, id, next),
                 ...(channelRuntimeForTask ? { channelRuntime: channelRuntimeForTask } : {}),
-              }),
-            ),
-          );
+              });
+            });
+            await startAccountTask;
+          });
           const trackedPromise = task
             .then(() => {
               if (abort.signal.aborted || manuallyStopped.has(rKey)) {
