Merge pull request #4015 from code-yeongyu/fix/background-output-bg-id-20260514

fix(background-task): retry transient missing output tasks

src/tools/background-task/create-background-output.blocking.test.ts

@@ -52,6 +52,47 @@ function createMockClient(): BackgroundOutputClient {
 }
 
 describe("createBackgroundOutput block=true polling", () => {
+  test("retries a missing background task id before reporting not found", async () => {
+    // #given
+    let lookupCount = 0
+    const task = createTask({
+      id: "bg_retry_visible",
+      status: "completed",
+      sessionId: "ses-retry-visible",
+    })
+    const manager: BackgroundOutputManager = {
+      getTask: (id: string) => {
+        if (id !== task.id) return undefined
+        lookupCount += 1
+        return lookupCount === 1 ? undefined : task
+      },
+    }
+    const client: BackgroundOutputClient = {
+      session: {
+        messages: async () => ({
+          data: [
+            {
+              id: "m1",
+              info: { role: "assistant", time: "2026-01-01T00:00:00Z" },
+              parts: [{ type: "text", text: "visible result" }],
+            },
+          ],
+        }),
+      },
+    }
+
+    const tool = createBackgroundOutput(manager, client)
+
+    // #when
+    const output = await tool.execute({ task_id: task.id }, mockContext)
+
+    // #then
+    expect(lookupCount).toBe(2)
+    expect(output).toContain("Task Result")
+    expect(output).toContain("visible result")
+    expect(output).not.toContain("Task not found")
+  })
+
   test("returns terminal error output when task fails during blocking wait", async () => {
     // #given
     let pollCount = 0

src/tools/background-task/create-background-output.ts

@@ -1,6 +1,7 @@
 import { tool, type ToolDefinition } from "@opencode-ai/plugin"
 import type { BackgroundTask } from "../../features/background-agent"
 import { publishToolMetadata } from "../../features/tool-metadata-store"
+import { log } from "../../shared/logger"
 import type { BackgroundOutputArgs } from "./types"
 import type { BackgroundOutputClient, BackgroundOutputManager } from "./clients"
 import { BACKGROUND_OUTPUT_DESCRIPTION } from "./constants"
@@ -13,6 +14,7 @@ import { getAgentDisplayName } from "../../shared/agent-display-names"
 import { recordBackgroundOutputConsumption } from "../../shared/background-output-consumption"
 
 const SISYPHUS_JUNIOR_AGENT = getAgentDisplayName("sisyphus-junior")
+const MISSING_BACKGROUND_TASK_RETRY_DELAY_MS = 100
 
 type ToolContextWithMetadata = {
   sessionID: string
@@ -40,6 +42,41 @@ function isSessionId(value: string): boolean {
   return /^ses[_-]/.test(value)
 }
 
+function isBackgroundTaskId(value: string): boolean {
+  return /^bg[_-]/.test(value)
+}
+
+async function getTaskWithMissingRetry(
+  manager: BackgroundOutputManager,
+  taskId: string,
+): Promise<BackgroundTask | undefined> {
+  const task = manager.getTask(taskId)
+  if (task || !isBackgroundTaskId(taskId)) {
+    return task
+  }
+
+  log("[background_output] background task missing on first lookup; retrying", {
+    taskId,
+    retryDelayMs: MISSING_BACKGROUND_TASK_RETRY_DELAY_MS,
+  })
+
+  await delay(MISSING_BACKGROUND_TASK_RETRY_DELAY_MS)
+  const retriedTask = manager.getTask(taskId)
+
+  log(
+    retriedTask
+      ? "[background_output] recovered background task after missing lookup retry"
+      : "[background_output] background task still missing after retry",
+    {
+      taskId,
+      status: retriedTask?.status,
+      sessionId: retriedTask?.sessionId,
+    }
+  )
+
+  return retriedTask
+}
+
 function formatTaskNotFoundMessage(taskId: string): string {
   if (!isSessionId(taskId)) {
     return `Task not found: ${taskId}`
@@ -74,7 +111,7 @@ export function createBackgroundOutput(manager: BackgroundOutputManager, client:
     async execute(args: BackgroundOutputArgs, toolContext) {
       try {
         const ctx = toolContext as ToolContextWithMetadata
-        const task = manager.getTask(args.task_id)
+        const task = await getTaskWithMissingRetry(manager, args.task_id)
         if (!task) {
           return formatTaskNotFoundMessage(args.task_id)
         }
@@ -103,7 +140,7 @@ export function createBackgroundOutput(manager: BackgroundOutputManager, client:
           while (Date.now() - startTime < timeoutMs) {
             await delay(1000)
 
-            const currentTask = manager.getTask(args.task_id)
+            const currentTask = await getTaskWithMissingRetry(manager, args.task_id)
             if (!currentTask) {
               return `Task was deleted: ${args.task_id}`
             }
@@ -116,7 +153,7 @@ export function createBackgroundOutput(manager: BackgroundOutputManager, client:
           }
 
           if (isTaskActiveStatus(resolvedTask.status)) {
-            const finalCheck = manager.getTask(args.task_id)
+            const finalCheck = await getTaskWithMissingRetry(manager, args.task_id)
             if (finalCheck) {
               resolvedTask = finalCheck
             }