fix: handle undefined sessionStatus in pollRunningTasks (#2387)

When a completed session is no longer returned by session.status(),
allStatuses[sessionID] is undefined. Previously this fell through to
a 'still running' log, leaving the task stuck as running forever.

Match the sync-session-poller pattern: only continue (skip completion
check) when sessionStatus EXISTS and is not idle. When undefined,
fall through to validateSessionHasOutput + checkSessionTodos +
tryCompleteTask, same as idle.

src/features/background-agent/manager.polling.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect } from "bun:test"
 import { tmpdir } from "node:os"
 import type { PluginInput } from "@opencode-ai/plugin"
 import { BackgroundManager } from "./manager"
+import type { BackgroundTask } from "./types"
 
 function createManagerWithStatus(statusImpl: () => Promise<{ data: Record<string, { type: string }> }>): BackgroundManager {
   const client = {
@@ -51,3 +52,105 @@ describe("BackgroundManager polling overlap", () => {
     expect(statusCallCount).toBe(1)
   })
 })
+
+
+function createRunningTask(sessionID: string): BackgroundTask {
+  return {
+    id: `bg_test_${sessionID}`,
+    sessionID,
+    parentSessionID: "parent-session",
+    parentMessageID: "parent-msg",
+    description: "test task",
+    prompt: "test",
+    agent: "explore",
+    status: "running",
+    startedAt: new Date(),
+    progress: { toolCalls: 0, lastUpdate: new Date() },
+  }
+}
+
+function injectTask(manager: BackgroundManager, task: BackgroundTask): void {
+  const tasks = (manager as unknown as { tasks: Map<string, BackgroundTask> }).tasks
+  tasks.set(task.id, task)
+}
+
+function createManagerWithClient(clientOverrides: Record<string, unknown> = {}): BackgroundManager {
+  const client = {
+    session: {
+      status: async () => ({ data: {} }),
+      prompt: async () => ({}),
+      promptAsync: async () => ({}),
+      abort: async () => ({}),
+      todo: async () => ({ data: [] }),
+      messages: async () => ({
+        data: [{
+          info: { role: "assistant", finish: "end_turn", id: "msg-2" },
+          parts: [{ type: "text", text: "done" }],
+        }, {
+          info: { role: "user", id: "msg-1" },
+          parts: [{ type: "text", text: "go" }],
+        }],
+      }),
+      ...clientOverrides,
+    },
+  }
+  return new BackgroundManager({ client, directory: tmpdir() } as unknown as PluginInput)
+}
+
+describe("BackgroundManager pollRunningTasks", () => {
+  describe("#given a running task whose session is no longer in status response", () => {
+    test("#when pollRunningTasks runs #then completes the task instead of leaving it running", async () => {
+      //#given
+      const manager = createManagerWithClient()
+      const task = createRunningTask("ses-gone")
+      injectTask(manager, task)
+
+      //#when
+      const poll = (manager as unknown as { pollRunningTasks: () => Promise<void> }).pollRunningTasks
+      await poll.call(manager)
+      manager.shutdown()
+
+      //#then
+      expect(task.status).toBe("completed")
+      expect(task.completedAt).toBeDefined()
+    })
+  })
+
+  describe("#given a running task whose session status is idle", () => {
+    test("#when pollRunningTasks runs #then completes the task", async () => {
+      //#given
+      const manager = createManagerWithClient({
+        status: async () => ({ data: { "ses-idle": { type: "idle" } } }),
+      })
+      const task = createRunningTask("ses-idle")
+      injectTask(manager, task)
+
+      //#when
+      const poll = (manager as unknown as { pollRunningTasks: () => Promise<void> }).pollRunningTasks
+      await poll.call(manager)
+      manager.shutdown()
+
+      //#then
+      expect(task.status).toBe("completed")
+    })
+  })
+
+  describe("#given a running task whose session status is busy", () => {
+    test("#when pollRunningTasks runs #then keeps the task running", async () => {
+      //#given
+      const manager = createManagerWithClient({
+        status: async () => ({ data: { "ses-busy": { type: "busy" } } }),
+      })
+      const task = createRunningTask("ses-busy")
+      injectTask(manager, task)
+
+      //#when
+      const poll = (manager as unknown as { pollRunningTasks: () => Promise<void> }).pollRunningTasks
+      await poll.call(manager)
+      manager.shutdown()
+
+      //#then
+      expect(task.status).toBe("running")
+    })
+  })
+})

src/features/background-agent/manager.ts

@@ -1501,32 +1501,7 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
 
       try {
         const sessionStatus = allStatuses[sessionID]
-        
-        if (sessionStatus?.type === "idle") {
-          // Edge guard: Validate session has actual output before completing
-          const hasValidOutput = await this.validateSessionHasOutput(sessionID)
-          if (!hasValidOutput) {
-            log("[background-agent] Polling idle but no valid output yet, waiting:", task.id)
-            continue
-          }
-
-          // Re-check status after async operation
-          if (task.status !== "running") continue
-
-          const hasIncompleteTodos = await this.checkSessionTodos(sessionID)
-          if (hasIncompleteTodos) {
-            log("[background-agent] Task has incomplete todos via polling, waiting:", task.id)
-            continue
-          }
-
-          await this.tryCompleteTask(task, "polling (idle status)")
-          continue
-        }
-
-        // Session is still actively running (not idle).
-        // Progress is already tracked via handleEvent(message.part.updated),
-        // so we skip the expensive session.messages() fetch here.
-        // Completion will be detected when session transitions to idle.
+        // Handle retry before checking running state
         if (sessionStatus?.type === "retry") {
           const retryMessage = typeof (sessionStatus as { message?: string }).message === "string"
             ? (sessionStatus as { message?: string }).message
@@ -1537,12 +1512,40 @@ Use \`background_output(task_id="${task.id}")\` to retrieve this result when rea
           }
         }
 
-        log("[background-agent] Session still running, relying on event-based progress:", {
-          taskId: task.id,
-          sessionID,
-          sessionStatus: sessionStatus?.type ?? "not_in_status",
-          toolCalls: task.progress?.toolCalls ?? 0,
-        })
+        // Match sync-session-poller pattern: only skip completion check when
+        // status EXISTS and is not idle (i.e., session is actively running).
+        // When sessionStatus is undefined, the session has completed and dropped
+        // from the status response — fall through to completion detection.
+        if (sessionStatus && sessionStatus.type !== "idle") {
+          log("[background-agent] Session still running, relying on event-based progress:", {
+            taskId: task.id,
+            sessionID,
+            sessionStatus: sessionStatus.type,
+            toolCalls: task.progress?.toolCalls ?? 0,
+          })
+          continue
+        }
+
+        // Session is idle or no longer in status response (completed/disappeared)
+        const completionSource = sessionStatus?.type === "idle"
+          ? "polling (idle status)"
+          : "polling (session gone from status)"
+        const hasValidOutput = await this.validateSessionHasOutput(sessionID)
+        if (!hasValidOutput) {
+          log("[background-agent] Polling idle/gone but no valid output yet, waiting:", task.id)
+          continue
+        }
+
+        // Re-check status after async operation
+        if (task.status !== "running") continue
+
+        const hasIncompleteTodos = await this.checkSessionTodos(sessionID)
+        if (hasIncompleteTodos) {
+          log("[background-agent] Task has incomplete todos via polling, waiting:", task.id)
+          continue
+        }
+
+        await this.tryCompleteTask(task, completionSource)
       } catch (error) {
         log("[background-agent] Poll error for task:", { taskId: task.id, error })
       }