fix(prompt-gate): harden internal prompt dispatch

src/hooks/team-session-events/team-idle-wake-hint.test.ts

@@ -22,6 +22,10 @@ import {
   clearAllSessionPromptParams,
   getSessionPromptParams,
 } from "../../shared/session-prompt-params-state"
+import {
+  releaseAllPromptAsyncReservationsForTesting,
+  releasePromptAsyncReservation,
+} from "../shared/prompt-async-gate"
 import { createTeamIdleWakeHint } from "./team-idle-wake-hint"
 
 type WakeHintPromptInput = {
@@ -183,6 +187,7 @@ afterEach(async () => {
   clearTeamSessionRegistry()
   SessionCategoryRegistry.clear()
   clearAllSessionPromptParams()
+  releaseAllPromptAsyncReservationsForTesting()
   await Promise.all(temporaryDirectories.splice(0).map(async (directoryPath) => {
     await rm(directoryPath, { recursive: true, force: true })
   }))
@@ -295,6 +300,44 @@ describe("createTeamIdleWakeHint", () => {
     expect(promptAsyncSpy).toHaveBeenCalledTimes(0)
   })
 
+  test("#given wake hint promptAsync may have been accepted before EOF #when idle repeats after the gate hold #then the same unread batch is not hinted twice", async () => {
+    // given
+    const baseDir = await createTemporaryBaseDir()
+    const config = createConfig(baseDir)
+    const teamRunId = randomUUID()
+    await seedRuntimeState(createRuntimeState(teamRunId), config)
+    await seedUnreadMessage(teamRunId, config, randomUUID(), "first message body", 100)
+
+    const promptAsyncSpy = mock(async (_input: WakeHintPromptInput) => {
+      throw new Error("JSON Parse error: Unexpected EOF")
+    })
+    const handler = createTeamIdleWakeHint({
+      directory: "/tmp/project",
+      client: { session: { promptAsync: promptAsyncSpy } },
+    }, config, { idleSettleMs: 0 })
+
+    // when
+    await handler({
+      event: {
+        type: "session.idle",
+        properties: { sessionID: "member-session" },
+      },
+    })
+    const released = releasePromptAsyncReservation("member-session", "test:simulate-expired-hold", {
+      reservedBy: "team-idle-wake-hint",
+    })
+    await handler({
+      event: {
+        type: "session.idle",
+        properties: { sessionID: "member-session" },
+      },
+    })
+
+    // then
+    expect(released).toBe(true)
+    expect(promptAsyncSpy).toHaveBeenCalledTimes(1)
+  })
+
   test("pins the recipient's resolved subagent_type and model on the wake-hint promptAsync", async () => {
     // given
     const baseDir = await createTemporaryBaseDir()

src/hooks/team-session-events/team-idle-wake-hint.ts

@@ -8,8 +8,9 @@ import { ackMessages } from "../../features/team-mode/team-mailbox/ack"
 import { listUnreadMessages } from "../../features/team-mode/team-mailbox/inbox"
 import { loadRuntimeState, transitionRuntimeState } from "../../features/team-mode/team-state-store/store"
 import { resolveSessionEventID } from "../../shared/event-session-id"
+import { isAmbiguousPromptDispatchFailure } from "../../shared/prompt-failure-classifier"
 import { log } from "../../shared/logger"
-import { dispatchInternalPrompt } from "../shared/prompt-async-gate"
+import { dispatchInternalPrompt, isInternalPromptDispatchAccepted } from "../shared/prompt-async-gate"
 
 type PromptAsyncInput = {
   path: { id: string }
@@ -35,6 +36,7 @@ type TeamIdleWakeHintContext = {
 type HookInput = { event: { type: string; properties?: unknown } }
 export type HookImpl = (input: HookInput) => Promise<void>
 type TeamIdleWakeHintOptions = { idleSettleMs?: number }
+const WAKE_HINT_DUPLICATE_SUPPRESSION_MS = 30_000
 
 function getIdleSessionID(properties: unknown): string | undefined {
   return resolveSessionEventID(properties)
@@ -44,7 +46,13 @@ function buildWakeHint(unreadCount: number): string {
   return `You have ${unreadCount} new team messages. They will be injected on your next turn.`
 }
 
+function buildWakeHintBatchKey(teamRunId: string, memberName: string, messageIds: string[]): string {
+  return `${teamRunId}:${memberName}:${messageIds.toSorted().join(",")}`
+}
+
 export function createTeamIdleWakeHint(ctx: TeamIdleWakeHintContext, config: TeamModeConfig, options?: TeamIdleWakeHintOptions): HookImpl {
+  const recentWakeHintBatches = new Map<string, number>()
+
   return async ({ event }: HookInput): Promise<void> => {
     if (event.type !== "session.idle") return
 
@@ -110,6 +118,27 @@ export function createTeamIdleWakeHint(ctx: TeamIdleWakeHintContext, config: Tea
         return
       }
 
+      const now = Date.now()
+      const wakeHintBatchKey = buildWakeHintBatchKey(
+        runtimeState.teamRunId,
+        memberEntry.name,
+        unreadMessages.map((message) => message.messageId),
+      )
+      const suppressedUntil = recentWakeHintBatches.get(wakeHintBatchKey)
+      if (suppressedUntil !== undefined && suppressedUntil > now) {
+        log("team idle wake hint skipped for recently hinted unread batch", {
+          event: "team-mode-idle-wake-hint-duplicate-suppressed",
+          teamRunId: runtimeState.teamRunId,
+          memberName: memberEntry.name,
+          sessionID,
+          unreadCount: unreadMessages.length,
+        })
+        return
+      }
+      if (suppressedUntil !== undefined) {
+        recentWakeHintBatches.delete(wakeHintBatchKey)
+      }
+
       applyMemberSessionRouting(sessionID, memberEntry)
       const promptResult = await dispatchInternalPrompt({
         mode: "async",
@@ -123,7 +152,10 @@ export function createTeamIdleWakeHint(ctx: TeamIdleWakeHintContext, config: Tea
           query: { directory: ctx.directory },
         },
       })
-      if (promptResult.status !== "dispatched") {
+      if (!isInternalPromptDispatchAccepted(promptResult)) {
+        if (promptResult.status === "failed" && isAmbiguousPromptDispatchFailure(promptResult.error)) {
+          recentWakeHintBatches.set(wakeHintBatchKey, Date.now() + WAKE_HINT_DUPLICATE_SUPPRESSION_MS)
+        }
         log("team idle wake hint skipped by promptAsync gate", {
           event: "team-mode-idle-wake-hint-gated",
           teamRunId: runtimeState.teamRunId,
@@ -134,6 +166,7 @@ export function createTeamIdleWakeHint(ctx: TeamIdleWakeHintContext, config: Tea
         })
         return
       }
+      recentWakeHintBatches.set(wakeHintBatchKey, Date.now() + WAKE_HINT_DUPLICATE_SUPPRESSION_MS)
 
       log("team idle wake hint sent", {
         event: "team-mode-idle-wake-hint",