fix(background-agent): defer active parent wakes

src/features/background-agent/manager.ts

@@ -63,6 +63,10 @@ import {
 } from "./attempt-lifecycle"
 import { registerManagerForCleanup, unregisterManagerForCleanup } from "./process-cleanup"
 import { setContinuationMarkerSource } from "../../features/run-continuation-state"
+import {
+  isSessionActive as isOpenCodeSessionActive,
+  settleAfterSessionIdle,
+} from "../../hooks/shared/session-idle-settle"
 import {
   findNearestMessageExcludingCompaction,
   resolvePromptContextFromSessionMessages,
@@ -100,6 +104,13 @@ type ParentWakePromptContext = {
   tools?: Record<string, boolean>
 }
 
+type PendingParentWake = {
+  promptContext: ParentWakePromptContext
+  notifications: string[]
+}
+
+const PENDING_PARENT_WAKE_RETRY_MS = 1_000
+
 interface MessagePartInfo {
   id?: string
   sessionID?: string
@@ -221,6 +232,8 @@ export class BackgroundManager {
   private completedTaskSummaries: Map<string, BackgroundTaskNotificationTask[]> = new Map()
   private idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
   private notificationQueueByParent: Map<string, Promise<void>> = new Map()
+  private pendingParentWakes: Map<string, PendingParentWake> = new Map()
+  private pendingParentWakeTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
   private observedOutputSessions: Set<string> = new Set()
   private observedIncompleteTodosBySession: Map<string, boolean> = new Map()
   private rootDescendantCounts: Map<string, number>
@@ -1410,6 +1423,12 @@ The fallback retry session is now created and can be inspected directly.
 
     if (event.type === "session.idle") {
       if (!props || typeof props !== "object") return
+      const sessionID = resolveSessionEventID(props)
+      if (sessionID) {
+        void this.enqueueNotificationForParent(sessionID, () => this.flushPendingParentWake(sessionID)).catch((error) => {
+          log("[background-agent] Failed to flush pending parent wake:", { sessionID, error })
+        })
+      }
       handleSessionIdleBackgroundEvent({
         properties: props as Record<string, unknown>,
         findBySession: (id) => {
@@ -2216,30 +2235,41 @@ The task was re-queued on a fallback model after a retryable failure.
           ...(variant !== undefined ? { variant } : {}),
           ...(resolvedTools ? { tools: resolvedTools } : {}),
         }
-        try {
-          await promptAsyncInDirectory(this.client, {
-            path: { id: task.parentSessionId },
-            body: {
-              noReply: !shouldReply,
-              ...parentPromptContext,
-              parts: [createInternalAgentTextPart(notification)],
-            },
-          }, this.directory)
-          log("[background-agent] Sent notification to parent session:", {
+        const shouldDeferReply = shouldReply && await this.isSessionActive(task.parentSessionId)
+
+        if (shouldDeferReply) {
+          this.queuePendingParentWake(task.parentSessionId, notification, parentPromptContext)
+          log("[background-agent] Deferred notification until parent session is idle:", {
             taskId: task.id,
             allComplete,
             isTaskFailure,
-            noReply: !shouldReply,
           })
-        } catch (error) {
-          if (isAbortedSessionError(error)) {
-            log("[background-agent] Parent session aborted while sending notification; continuing cleanup:", {
+        } else {
+          try {
+            await promptAsyncInDirectory(this.client, {
+              path: { id: task.parentSessionId },
+              body: {
+                noReply: !shouldReply,
+                ...parentPromptContext,
+                parts: [createInternalAgentTextPart(notification)],
+              },
+            }, this.directory)
+            log("[background-agent] Sent notification to parent session:", {
               taskId: task.id,
-              parentSessionID: task.parentSessionId,
+              allComplete,
+              isTaskFailure,
+              noReply: !shouldReply,
             })
-            this.queuePendingNotification(task.parentSessionId, notification)
-          } else {
-            log("[background-agent] Failed to send notification:", error)
+          } catch (error) {
+            if (isAbortedSessionError(error)) {
+              log("[background-agent] Parent session aborted while sending notification; continuing cleanup:", {
+                taskId: task.id,
+                parentSessionID: task.parentSessionId,
+              })
+              this.queuePendingNotification(task.parentSessionId, notification)
+            } else {
+              log("[background-agent] Failed to send notification:", error)
+            }
           }
         }
       } else {
@@ -2254,6 +2284,93 @@ The task was re-queued on a fallback model after a retryable failure.
     }
   }
 
+  private async isSessionActive(sessionID: string): Promise<boolean> {
+    return isOpenCodeSessionActive(this.client, sessionID)
+  }
+
+  private queuePendingParentWake(
+    sessionID: string,
+    notification: string,
+    promptContext: ParentWakePromptContext,
+  ): void {
+    const pendingWake = this.pendingParentWakes.get(sessionID)
+    if (pendingWake) {
+      pendingWake.notifications.push(notification)
+      pendingWake.promptContext = promptContext
+    } else {
+      this.pendingParentWakes.set(sessionID, {
+        promptContext,
+        notifications: [notification],
+      })
+    }
+    this.schedulePendingParentWakeFlush(sessionID)
+  }
+
+  private async flushPendingParentWake(sessionID: string): Promise<void> {
+    const pendingWake = this.pendingParentWakes.get(sessionID)
+    if (!pendingWake) {
+      this.clearPendingParentWakeTimer(sessionID)
+      return
+    }
+
+    if (await this.isSessionActive(sessionID)) {
+      this.schedulePendingParentWakeFlush(sessionID)
+      return
+    }
+
+    this.pendingParentWakes.delete(sessionID)
+    this.clearPendingParentWakeTimer(sessionID)
+    await settleAfterSessionIdle()
+
+    if (await this.isSessionActive(sessionID)) {
+      this.pendingParentWakes.set(sessionID, pendingWake)
+      this.schedulePendingParentWakeFlush(sessionID)
+      return
+    }
+
+    const notificationContent = pendingWake.notifications.join("\n\n")
+
+    try {
+      await promptAsyncInDirectory(this.client, {
+        path: { id: sessionID },
+        body: {
+          noReply: false,
+          ...pendingWake.promptContext,
+          parts: [createInternalAgentTextPart(notificationContent)],
+        },
+      }, this.directory)
+      log("[background-agent] Sent deferred parent wake:", { sessionID })
+    } catch (error) {
+      this.queuePendingNotification(sessionID, notificationContent)
+      log("[background-agent] Failed to send deferred parent wake:", { sessionID, error })
+    }
+  }
+
+  private schedulePendingParentWakeFlush(sessionID: string): void {
+    if (this.pendingParentWakeTimers.has(sessionID)) {
+      return
+    }
+
+    const timer = setTimeout(() => {
+      this.pendingParentWakeTimers.delete(sessionID)
+      void this.enqueueNotificationForParent(sessionID, () => this.flushPendingParentWake(sessionID)).catch((error) => {
+        log("[background-agent] Failed to retry pending parent wake:", { sessionID, error })
+      })
+    }, PENDING_PARENT_WAKE_RETRY_MS)
+
+    this.pendingParentWakeTimers.set(sessionID, timer)
+  }
+
+  private clearPendingParentWakeTimer(sessionID: string): void {
+    const timer = this.pendingParentWakeTimers.get(sessionID)
+    if (!timer) {
+      return
+    }
+
+    clearTimeout(timer)
+    this.pendingParentWakeTimers.delete(sessionID)
+  }
+
   private hasRunningTasks(): boolean {
     for (const task of this.tasks.values()) {
       if (task.status === "running") return true
@@ -2574,6 +2691,11 @@ The task was re-queued on a fallback model after a retryable failure.
     }
     this.idleDeferralTimers.clear()
 
+    for (const timer of this.pendingParentWakeTimers.values()) {
+      clearTimeout(timer)
+    }
+    this.pendingParentWakeTimers.clear()
+
     for (const sessionID of trackedSessionIDs) {
       subagentSessions.delete(sessionID)
       SessionCategoryRegistry.remove(sessionID)
@@ -2585,6 +2707,7 @@ The task was re-queued on a fallback model after a retryable failure.
     this.notifications.clear()
     this.pendingNotifications.clear()
     this.pendingByParent.clear()
+    this.pendingParentWakes.clear()
     this.notificationQueueByParent.clear()
     this.rootDescendantCounts.clear()
     this.queuesByKey.clear()