fix(acp): flush straggler chunks promptly after session/prompt returns

[swear01]

Summary

Fixes #609. Also applies to Gemini and Kimi which share the same AcpSdkBackend code path.

Root cause: After session/prompt returns, AcpSdkBackend drains buffered agentMessageChunk text and marks the turn complete, but leaves messageHandler alive. Models with long streaming tails (GPT-5.5, DeepSeek V4 Pro) keep sending chunks after that drain. Those chunks accumulate in the buffer with nothing to flush them — they only appear when the next user prompt's pre-prompt drain fires the old onUpdate callback, showing up in the wrong turn with broken markdown.

Fix: After the post-prompt drain, start a 50 ms interval timer (startLateFlushTimer) that keeps calling drainBuffers() on the live handler for up to 6 seconds. Straggler chunks are emitted within one poll tick instead of waiting for the next user message. The timer is cancelled at the start of the next prompt() call (before the handler is replaced) and on disconnect().

Changes

Single file: cli/src/agent/backends/acp/AcpSdkBackend.ts

• Add lateFlushTimer field + LATE_FLUSH_INTERVAL_MS (50 ms) / LATE_FLUSH_WINDOW_MS (6 s) constants
• startLateFlushTimer() — starts the interval, auto-stops after the window expires
• stopLateFlushTimer() — clears the interval; called at prompt start and disconnect
• Wire startLateFlushTimer() after drainBuffers() in the finally block of prompt()
• Wire stopLateFlushTimer() at the top of prompt() and in disconnect()

Test plan

• Start a session with OpenCode + a model that has a long streaming tail (GPT-5.5, DeepSeek V4 Pro)
• Ask for a long response; confirm the full output appears before the next prompt without needing a follow-up message
• Confirm code blocks / markdown formatting is intact
• Verify normal sessions (Claude, fast-streaming models) are unaffected

🤖 Generated with Claude Code

[github-actions]

Findings

• [Major] Late flush runs after the turn is reported idle — startLateFlushTimer() is fire-and-forget, so prompt() still emits turn_complete, clears isProcessingMessage, resolves waiters, and the launchers send ready while the old handler can continue emitting assistant text for up to 6 seconds. A user can send the next prompt during that window; the next prompt() stops the timer and drains the old handler only after the new user message has already been queued/displayed, and a tail longer than the pre-prompt drain timeout can still land in the new turn. Evidence: cli/src/agent/backends/acp/AcpSdkBackend.ts:295, with completion immediately after in the same finally block.
  Suggested fix:

  private async drainLateBuffers(): Promise<void> {
      const deadline = Date.now() + AcpSdkBackend.LATE_FLUSH_WINDOW_MS;
      while (Date.now() < deadline) {
          await new Promise<void>((resolve) => setTimeout(resolve, AcpSdkBackend.LATE_FLUSH_INTERVAL_MS));
          this.messageHandler?.drainBuffers();
      }
  }
  
  // In prompt() before usage/turn_complete and before isProcessingMessage=false:
  this.messageHandler?.drainBuffers();
  await this.drainLateBuffers();

Summary

• Review mode: initial
• The diff improves late chunk flushing, but the timer currently operates outside the turn lifecycle. Keep the late-drain window inside prompt() completion, or otherwise delay ready/notifyResponseComplete until the old handler is no longer accepting tail chunks.

Testing

• Not run (automation)

HAPI Bot

[github-actions]

[MAJOR] This timer is started but not awaited, so prompt() continues to emit turn_complete, clear isProcessingMessage, notify waiters, and let the launchers send ready while the old handler can still flush assistant text for up to 6 seconds. If the user sends the next prompt during that window, late text can still be emitted after the new user message or captured by the new handler once the pre-prompt drain times out.

Suggested fix:

private async drainLateBuffers(): Promise<void> {
    const deadline = Date.now() + AcpSdkBackend.LATE_FLUSH_WINDOW_MS;
    while (Date.now() < deadline) {
        await new Promise<void>((resolve) => setTimeout(resolve, AcpSdkBackend.LATE_FLUSH_INTERVAL_MS));
        this.messageHandler?.drainBuffers();
    }
}

this.messageHandler?.drainBuffers();
await this.drainLateBuffers();

[github-actions]

Findings

• [Major] Late flush still runs after the turn is reported idle — startLateFlushTimer() is started at cli/src/agent/backends/acp/AcpSdkBackend.ts:304, but prompt() then emits turn_complete, clears isProcessingMessage, resolves waiters, and returns at cli/src/agent/backends/acp/AcpSdkBackend.ts:320. The remote launchers flip thinking off and emit ready immediately after that return when the queue is empty (cli/src/opencode/opencodeRemoteLauncher.ts:256, cli/src/agent/runners/runAgentSession.ts:192), so any tail chunk flushed by the background interval can still appear after the ready notification or after the user has already queued the next turn. The added tests cover that a late chunk eventually flushes, but not that no assistant text arrives after turn completion/readiness.
  Suggested fix:

  private async drainLateBuffers(): Promise<void> {
      const deadline = Date.now() + AcpSdkBackend.LATE_FLUSH_WINDOW_MS;
      while (Date.now() < deadline) {
          await new Promise<void>((resolve) => setTimeout(resolve, AcpSdkBackend.LATE_FLUSH_INTERVAL_MS));
          this.messageHandler?.drainBuffers();
      }
  }
  
  // In prompt(), before usage/turn_complete and before isProcessingMessage=false:
  this.messageHandler?.drainBuffers();
  await this.drainLateBuffers();

Questions

• None

Summary

• Review mode: follow-up after new commits
• The previous lifecycle issue is only partially addressed: straggler chunks are retained for the prior handler, but the turn is still marked complete and the session can still announce ready while that handler is flushing in the background.

Testing

• Not run: bun test cli/src/agent/backends/acp/AcpSdkBackend.test.ts failed because bun is not installed in this runner.

HAPI Bot

[github-actions]

[MAJOR] This still starts the late flush as background work. Immediately afterward, prompt() emits turn_complete, clears isProcessingMessage, resolves response-complete waiters, and returns; the launchers then flip thinking off and emit ready when the queue is empty. A tail chunk flushed by this interval can therefore appear after the ready notification or after the user has queued the next turn.

Suggested fix:

private async drainLateBuffers(): Promise<void> {
    const deadline = Date.now() + AcpSdkBackend.LATE_FLUSH_WINDOW_MS;
    while (Date.now() < deadline) {
        await new Promise<void>((resolve) => setTimeout(resolve, AcpSdkBackend.LATE_FLUSH_INTERVAL_MS));
        this.messageHandler?.drainBuffers();
    }
}

// Before usage/turn_complete and before isProcessingMessage=false:
this.messageHandler?.drainBuffers();
await this.drainLateBuffers();

[github-actions]

Findings

• [Major] Late-flush quiet window can be skipped for post-return tails — drainLateBuffers() compares against the old lastSessionUpdateAt before it waits. If the ACP agent pauses for more than LATE_FLUSH_QUIET_PERIOD_MS before session/prompt resolves, this method returns immediately at cli/src/agent/backends/acp/AcpSdkBackend.ts:453, then turn_complete is emitted and the launcher can send ready; any chunk that arrives shortly after the response returns is buffered until a later boundary, which is the straggler behavior this PR is meant to fix.
  Suggested fix:

  private async drainLateBuffers(): Promise<void> {
      const quietBaseline = Date.now();
      const deadline = quietBaseline + AcpSdkBackend.LATE_FLUSH_WINDOW_MS;
  
      while (Date.now() < deadline) {
          const latestActivityAt = Math.max(this.lastSessionUpdateAt, quietBaseline);
          const elapsedSinceUpdate = Date.now() - latestActivityAt;
          if (elapsedSinceUpdate >= AcpSdkBackend.LATE_FLUSH_QUIET_PERIOD_MS) {
              return;
          }
  
          const remainingBudget = deadline - Date.now();
          const waitMs = Math.max(1, Math.min(AcpSdkBackend.LATE_FLUSH_INTERVAL_MS, remainingBudget));
          await new Promise<void>((resolve) => setTimeout(resolve, waitMs));
          this.messageHandler?.drainBuffers();
      }
  }

Questions

• None

Summary

• Review mode: follow-up after new commits
• The previous background-timer issue is mostly addressed by awaiting the late flush, but the new quiet check can still skip the post-return observation window when the last update is already old.

Testing

• Not run (automation): bun test cli/src/agent/backends/acp/AcpSdkBackend.test.ts could not run because bun is not installed in this runner.

HAPI Bot

[github-actions]

[MAJOR] drainLateBuffers() can return before it observes the period after session/prompt resolves. Because lastSessionUpdateAt may already be older than LATE_FLUSH_QUIET_PERIOD_MS when this method starts, the first loop iteration exits immediately; a chunk emitted just after the prompt response is then buffered after turn_complete/ready and is not flushed until a later boundary.

Suggested fix:

private async drainLateBuffers(): Promise<void> {
    const quietBaseline = Date.now();
    const deadline = quietBaseline + AcpSdkBackend.LATE_FLUSH_WINDOW_MS;

    while (Date.now() < deadline) {
        const latestActivityAt = Math.max(this.lastSessionUpdateAt, quietBaseline);
        const elapsedSinceUpdate = Date.now() - latestActivityAt;
        if (elapsedSinceUpdate >= AcpSdkBackend.LATE_FLUSH_QUIET_PERIOD_MS) {
            return;
        }

        const remainingBudget = deadline - Date.now();
        const waitMs = Math.max(1, Math.min(AcpSdkBackend.LATE_FLUSH_INTERVAL_MS, remainingBudget));
        await new Promise<void>((resolve) => setTimeout(resolve, waitMs));
        this.messageHandler?.drainBuffers();
    }
}

[github-actions]

Findings

• None

Questions

• None

Summary

• Review mode: follow-up after new commits
• No issues found in the latest diff. Previous late-flush quiet-window finding appears addressed by anchoring the quiet baseline at drainLateBuffers() entry and adding a regression test. Residual risk: timing-based behavior depends on real ACP tail cadence and could not be verified against live OpenCode/Gemini in this runner.

Testing

• Not run (automation): bun test cli/src/agent/backends/acp/AcpSdkBackend.test.ts and bun typecheck could not run because bun is not installed in this runner.

HAPI Bot

[github-actions]

Findings

• None

Questions

• None

Summary
Review mode: follow-up after new commits
No issues found in the latest PR diff. The current ACP late-flush path keeps the active handler installed through post-prompt draining, emits late chunks before turn_complete, and includes regression coverage for post-return stragglers and stale lastSessionUpdateAt quiet-window anchoring. Residual risk: real ACP tail cadence could not be validated against live OpenCode/Gemini/Kimi in this runner.

Testing

• Not run (automation): bun test cli/src/agent/backends/acp/AcpSdkBackend.test.ts and bun typecheck failed because bun is not installed in this runner.

HAPI Bot