fix: buffer "start" events so auth retry does not leak phantom messages

[dnouri]

Problem

Users see frequent 401 authentication errors even though the extension already has speculative OAuth token refresh logic:

Error: 401 {"error":{"type":"authentication_error","message":"The API Key appears to be invalid or may have expired..."}}

Root cause

streamAnthropic (the default protocol path) emits a synthetic start event before the HTTP request begins. If the server returns 401, the stream emits error. Event sequence: start → error.

The retry logic was gated on !pushedAny && attempt === 0 && event.type === "error". But pushedAny was set to true as soon as the start event was pushed. When the error event arrived, the guard was already false and the refresh was skipped.

This happens frequently because Kimi tokens are short-lived. pi-coding-agent only refreshes when the local expires timestamp is reached, but servers routinely invalidate tokens a few minutes early. During that invalidation window the framework hands out a dead token, the request 401s, and the retry guard fails to catch it.

Why not just drop !pushedAny?

Removing the guard would fix the 401 leak, but it would let the synthetic start event escape into the session. The consumer (agent-loop.ts) creates a new empty assistant message on every start. On retry that leaves a dangling phantom message in the TUI and persisted session.

Fix

Buffer start events and only flush them once we see a non-error event that proves the stream is alive. If we retry, the buffer is discarded and no phantom message escapes. The buffer is at most one event.

What changed

• Replaced pushedAny with a prefixBuffer: AssistantMessageEvent[]
• start events are buffered instead of forwarded immediately
• On the first error with attempt === 0: refresh OAuth token and retry, discarding the buffer
• On any non-error event: flush the buffer, then stream normally
• On normal stream end or unhandled exception: flush remaining buffered events

---

Summary by cubic

Buffers synthetic "start" events so the first 401 triggers an auth refresh and retry without leaking empty assistant messages into the UI or session. This reduces spurious 401s and removes phantom messages during retries.

• Bug Fixes
  • Buffer "start" events and flush only after the first non-error; discard on retry to avoid phantom messages.
  • Refresh OAuth and retry on the first error (attempt 0), fixing missed retries caused by early "start" emissions.
  • Replace pushedAny with a prefixBuffer; flush the buffer on normal end or exceptions.

^{Written for commit 22982d0. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="index.ts">

<violation number="1" location="index.ts:872">
P2: Thrown upstream auth failures bypass token-refresh retry and can leak buffered `start` events, reintroducing phantom messages.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Thrown upstream auth failures bypass token-refresh retry and can leak buffered start events, reintroducing phantom messages.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At index.ts, line 872:

<comment>Thrown upstream auth failures bypass token-refresh retry and can leak buffered `start` events, reintroducing phantom messages.</comment>

<file context>
@@ -852,16 +860,25 @@ function streamSimpleKimi(
+
+          // First non-start, non-retry event: flush buffered prefix, then
+          // stream normally.
+          for (const e of prefixBuffer) filtered.push(e);
+          prefixBuffer = [];
           filtered.push(event);
</file context>