@blackbelt-technology/pi-agent-dashboard 0.5.2 → 0.5.4

package/packages/extension/src/__tests__/bridge-followup-chat-order.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Bridge wire-ordering invariant for drained queued user messages.
+ *
+ * Applies to BOTH drain boundaries:
+ *   - Steer drain at `turn_end`     (Enter while streaming)
+ *   - Follow-up drain at `agent_end` (Alt+Enter while streaming)
+ *
+ * Pi emits four events synchronously back-to-back at the drain boundary:
+ *
+ *   1. message_end   (assistant — the final response of the just-completed turn)
+ *   2. turn_end OR agent_end (the drain boundary)
+ *   3. message_start (user — the drained steer or follow-up text, e.g. "asd")
+ *   4. message_end   (user — same text)
+ *
+ * Pre-fix bug: the bridge defers `message_end` sends via `setTimeout(0)`
+ * (for entryId capture per `fix-per-message-fork`) but sends `message_start`
+ * synchronously. The drained user `message_start` therefore lands on the
+ * wire BEFORE the preceding assistant `message_end`. The client's reducer
+ * appends the user message to `state.messages[]` at `message_start`, then
+ * the assistant message at the (later) `message_end` — so the chat shows
+ * the follow-up "asd" ABOVE the assistant's final response.
+ *
+ * Fix: defer user `message_start` sends via the same `setTimeout(0)`. All
+ * user-role messages are queued in the timer FIFO behind any pending
+ * `message_end` deferrals, preserving pi's emit order on the wire.
+ *
+ * Assistant `message_start` MUST stay sync — `message_update` events fire
+ * sync and depend on the reducer having seen `message_start` first (to
+ * reset `streamingTextFlushed`).
+ *
+ * See change: add-followup-edit-and-steer-cancel (chat-order scenario).
+ */
+
+import { describe, it, expect } from "vitest";
+
+interface WireEvent {
+  eventType: string;
+  role?: "user" | "assistant";
+  content?: string;
+}
+
+/**
+ * Simulates the bridge's event-forwarding pipeline with the new
+ * deferral rule applied to USER message_start. Runs everything in
+ * a single synchronous tick to mirror pi's emit cadence, then drains
+ * the macrotask queue to capture the final wire order.
+ */
+class BridgeSim {
+  readonly wire: WireEvent[] = [];
+
+  onMessageStart(role: "user" | "assistant", content: string): void {
+    if (role === "user") {
+      // FIX: defer user message_start to match message_end's deferral.
+      setTimeout(() => {
+        this.wire.push({ eventType: "message_start", role, content });
+      }, 0);
+      return;
+    }
+    // Assistant message_start sent sync (message_update depends on it).
+    this.wire.push({ eventType: "message_start", role, content });
+  }
+
+  onMessageEnd(role: "user" | "assistant", content: string): void {
+    // Existing behaviour: ALL message_end sends are deferred via setTimeout(0)
+    // for entryId capture (fix-per-message-fork).
+    setTimeout(() => {
+      this.wire.push({ eventType: "message_end", role, content });
+    }, 0);
+  }
+
+  onAgentEnd(): void {
+    // Sent sync.
+    this.wire.push({ eventType: "agent_end" });
+  }
+
+  onTurnEnd(): void {
+    // Sent sync (mirrors agent_end).
+    this.wire.push({ eventType: "turn_end" });
+  }
+
+  /** Flush pending setTimeout(0) callbacks. */
+  async flush(): Promise<void> {
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    // Two extra ticks in case any callback re-queues.
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  }
+}
+
+describe("Bridge drained-followup chat-order invariant", () => {
+  it("user message_start for drained follow-up lands AFTER preceding assistant message_end", async () => {
+    const sim = new BridgeSim();
+
+    // Pi's sync emit order at agent_end with a queued follow-up:
+    //   1. assistant message_end (the weather report)
+    //   2. agent_end
+    //   3. user message_start ("asd" — the drained follow-up)
+    //   4. user message_end ("asd")
+    sim.onMessageEnd("assistant", "weather report");
+    sim.onAgentEnd();
+    sim.onMessageStart("user", "asd");
+    sim.onMessageEnd("user", "asd");
+
+    await sim.flush();
+
+    const types = sim.wire.map((e) => `${e.eventType}:${e.role ?? "-"}`);
+    // Expected wire order after the fix:
+    //   1. agent_end                 (sync, fires first)
+    //   2. assistant message_end     (deferred, FIFO #1)
+    //   3. user message_start        (deferred, FIFO #2 — after the fix)
+    //   4. user message_end          (deferred, FIFO #3)
+    expect(types).toEqual([
+      "agent_end:-",
+      "message_end:assistant",
+      "message_start:user",
+      "message_end:user",
+    ]);
+
+    // Critical invariant: the drained user message_start MUST NOT come
+    // before the preceding assistant message_end.
+    const userStartIdx = sim.wire.findIndex(
+      (e) => e.eventType === "message_start" && e.role === "user"
+    );
+    const assistantEndIdx = sim.wire.findIndex(
+      (e) => e.eventType === "message_end" && e.role === "assistant"
+    );
+    expect(assistantEndIdx).toBeGreaterThanOrEqual(0);
+    expect(userStartIdx).toBeGreaterThan(assistantEndIdx);
+  });
+
+  it("assistant message_start stays SYNC (message_update relies on reducer seeing it first)", () => {
+    const sim = new BridgeSim();
+    sim.onMessageStart("assistant", "hello");
+    // No flush — the event must already be on the wire.
+    expect(sim.wire).toEqual([
+      { eventType: "message_start", role: "assistant", content: "hello" },
+    ]);
+  });
+
+  it("multiple drained follow-ups preserve their relative pi emit order", async () => {
+    const sim = new BridgeSim();
+
+    // Pi delivers two queued follow-ups in order ["a", "b"].
+    sim.onMessageEnd("assistant", "final");
+    sim.onAgentEnd();
+    sim.onMessageStart("user", "a");
+    sim.onMessageEnd("user", "a");
+    sim.onMessageStart("user", "b");
+    sim.onMessageEnd("user", "b");
+
+    await sim.flush();
+
+    const summary = sim.wire.map((e) =>
+      e.eventType === "agent_end"
+        ? "agent_end"
+        : `${e.eventType}:${e.role}:${e.content}`
+    );
+    expect(summary).toEqual([
+      "agent_end",
+      "message_end:assistant:final",
+      "message_start:user:a",
+      "message_end:user:a",
+      "message_start:user:b",
+      "message_end:user:b",
+    ]);
+  });
+
+  it("drained STEER at turn_end lands AFTER preceding assistant message_end (same bug, different drain boundary)", async () => {
+    const sim = new BridgeSim();
+
+    // Pi's sync emit order at turn_end with a queued steer:
+    //   1. assistant message_end (the weather report)
+    //   2. turn_end
+    //   3. user message_start ("asd" — the drained steer)
+    //   4. user message_end ("asd")
+    // (Identical to the follow-up case but the drain boundary is turn_end
+    // instead of agent_end. The fix is uniform: defer USER message_start.)
+    sim.onMessageEnd("assistant", "weather report");
+    sim.onTurnEnd();
+    sim.onMessageStart("user", "asd");
+    sim.onMessageEnd("user", "asd");
+
+    await sim.flush();
+
+    const types = sim.wire.map((e) => `${e.eventType}:${e.role ?? "-"}`);
+    expect(types).toEqual([
+      "turn_end:-",
+      "message_end:assistant",
+      "message_start:user",
+      "message_end:user",
+    ]);
+
+    const userStartIdx = sim.wire.findIndex(
+      (e) => e.eventType === "message_start" && e.role === "user"
+    );
+    const assistantEndIdx = sim.wire.findIndex(
+      (e) => e.eventType === "message_end" && e.role === "assistant"
+    );
+    expect(userStartIdx).toBeGreaterThan(assistantEndIdx);
+  });
+
+  it("idle user send (no preceding deferred message_end) still arrives intact", async () => {
+    const sim = new BridgeSim();
+
+    // No pending deferrals in flight — a fresh user prompt.
+    sim.onMessageStart("user", "hi");
+    sim.onMessageEnd("user", "hi");
+
+    await sim.flush();
+
+    expect(sim.wire.map((e) => `${e.eventType}:${e.role}`)).toEqual([
+      "message_start:user",
+      "message_end:user",
+    ]);
+  });
+});

package/packages/extension/src/__tests__/bridge-followup-multi-entry.test.ts

@@ -0,0 +1,202 @@
+/**
+ * v2 bridge behavior tests for the multi-entry follow-up queue.
+ *
+ * Encodes the contract of the bridge's `rewriteFollowupQueue` helper and the
+ * three new browser-message handlers (promote / remove / edit_entry). Tests
+ * use a pure-helper reproduction (same shape as the production code) so the
+ * contract is verifiable without instantiating the full bridge.
+ *
+ * See change: add-followup-edit-and-steer-cancel (tasks 13.6, 13.7, 13.13).
+ */
+import { describe, it, expect, vi } from "vitest";
+
+const FOLLOWUP_QUEUE_CAP = 20;
+
+/** Pure reproduction of the bridge's follow-up shadow + rewrite logic. */
+function makeShadow() {
+  const calls: Array<{ kind: "clear" } | { kind: "send"; text: string }> = [];
+  let bridgeFollowUp: string[] = [];
+  const fakePiClearFollowUpQueue = () => { calls.push({ kind: "clear" }); };
+  const fakePiSendUserMessage = (text: string, opts: { deliverAs: string }) => {
+    calls.push({ kind: "send", text });
+    expect(opts).toEqual({ deliverAs: "followUp" });
+  };
+
+  function rewriteFollowupQueue(newEntries: string[]) {
+    const capped = newEntries.slice(0, FOLLOWUP_QUEUE_CAP);
+    fakePiClearFollowUpQueue();
+    for (const t of capped) fakePiSendUserMessage(t, { deliverAs: "followUp" });
+    bridgeFollowUp = [...capped];
+  }
+
+  function recordFollowupSent(text: string, isStreaming: boolean) {
+    if (!isStreaming) return;
+    if (bridgeFollowUp.length >= FOLLOWUP_QUEUE_CAP) return;
+    bridgeFollowUp.push(text);
+  }
+
+  // Browser-message handlers (mirror bridge.ts shape)
+  function handlePromoteEntry(index: number) {
+    if (index < 0 || index >= bridgeFollowUp.length) return;
+    const head = bridgeFollowUp[index];
+    const rest = bridgeFollowUp.filter((_, i) => i !== index);
+    rewriteFollowupQueue([head, ...rest]);
+  }
+  function handleRemoveEntry(index: number) {
+    if (index < 0 || index >= bridgeFollowUp.length) return;
+    const surviving = bridgeFollowUp.filter((_, i) => i !== index);
+    rewriteFollowupQueue(surviving);
+  }
+  function handleEditEntry(index: number, text: string) {
+    if (index < 0 || index >= bridgeFollowUp.length) return;
+    const next = bridgeFollowUp.map((t, i) => (i === index ? text : t));
+    rewriteFollowupQueue(next);
+  }
+  function handleEditFollowupSlotV1Compat(text: string) {
+    rewriteFollowupQueue([text]);
+  }
+
+  return {
+    snapshot: () => [...bridgeFollowUp],
+    calls,
+    rewriteFollowupQueue,
+    recordFollowupSent,
+    handlePromoteEntry,
+    handleRemoveEntry,
+    handleEditEntry,
+    handleEditFollowupSlotV1Compat,
+  };
+}
+
+describe("bridge follow-up multi-entry queue: rewrite helper", () => {
+  it("clears pi + sends each entry in new order", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["a", "b", "c"]);
+    expect(s.calls).toEqual([
+      { kind: "clear" },
+      { kind: "send", text: "a" },
+      { kind: "send", text: "b" },
+      { kind: "send", text: "c" },
+    ]);
+    expect(s.snapshot()).toEqual(["a", "b", "c"]);
+  });
+
+  it("clears + sends nothing for empty rewrite (queue drained)", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue([]);
+    expect(s.calls).toEqual([{ kind: "clear" }]);
+    expect(s.snapshot()).toEqual([]);
+  });
+
+  it("caps at FOLLOWUP_QUEUE_CAP (20)", () => {
+    const s = makeShadow();
+    const big = Array.from({ length: 25 }, (_, i) => `entry-${i}`);
+    s.rewriteFollowupQueue(big);
+    const sends = s.calls.filter((c) => c.kind === "send");
+    expect(sends).toHaveLength(20);
+    expect(s.snapshot()).toHaveLength(20);
+    expect(s.snapshot()[0]).toBe("entry-0");
+    expect(s.snapshot()[19]).toBe("entry-19");
+  });
+});
+
+describe("bridge follow-up multi-entry queue: recordFollowupSent (append)", () => {
+  it("appends when streaming", () => {
+    const s = makeShadow();
+    s.recordFollowupSent("a", true);
+    s.recordFollowupSent("b", true);
+    expect(s.snapshot()).toEqual(["a", "b"]);
+  });
+
+  it("does NOT append when idle (race fix)", () => {
+    const s = makeShadow();
+    s.recordFollowupSent("a", false);
+    expect(s.snapshot()).toEqual([]);
+  });
+
+  it("drops silently at soft cap", () => {
+    const s = makeShadow();
+    for (let i = 0; i < FOLLOWUP_QUEUE_CAP; i++) {
+      s.recordFollowupSent(`e${i}`, true);
+    }
+    expect(s.snapshot()).toHaveLength(FOLLOWUP_QUEUE_CAP);
+    s.recordFollowupSent("over-cap", true);
+    expect(s.snapshot()).toHaveLength(FOLLOWUP_QUEUE_CAP);
+    expect(s.snapshot()).not.toContain("over-cap");
+  });
+});
+
+describe("bridge follow-up multi-entry queue: promote handler", () => {
+  it("moves entry at index N to position 0", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["a", "b", "c"]);
+    s.handlePromoteEntry(2); // promote "c" to head
+    expect(s.snapshot()).toEqual(["c", "a", "b"]);
+  });
+
+  it("promoting index 0 is a no-op (already at head)", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["a", "b", "c"]);
+    s.handlePromoteEntry(0);
+    expect(s.snapshot()).toEqual(["a", "b", "c"]);
+  });
+
+  it("out-of-bounds index is ignored", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["a"]);
+    const before = s.snapshot();
+    s.handlePromoteEntry(5);
+    s.handlePromoteEntry(-1);
+    expect(s.snapshot()).toEqual(before);
+  });
+});
+
+describe("bridge follow-up multi-entry queue: remove handler", () => {
+  it("removes entry at index N", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["a", "b", "c"]);
+    s.handleRemoveEntry(1);
+    expect(s.snapshot()).toEqual(["a", "c"]);
+  });
+
+  it("removes last entry to leave empty queue", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["only"]);
+    s.handleRemoveEntry(0);
+    expect(s.snapshot()).toEqual([]);
+  });
+
+  it("out-of-bounds index is ignored", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["a", "b"]);
+    const before = s.snapshot();
+    s.handleRemoveEntry(99);
+    expect(s.snapshot()).toEqual(before);
+  });
+});
+
+describe("bridge follow-up multi-entry queue: edit handler", () => {
+  it("replaces entry at index N with new text", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["a", "b", "c"]);
+    s.handleEditEntry(1, "b-revised");
+    expect(s.snapshot()).toEqual(["a", "b-revised", "c"]);
+  });
+
+  it("out-of-bounds index is ignored", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["only"]);
+    const before = s.snapshot();
+    s.handleEditEntry(99, "nope");
+    expect(s.snapshot()).toEqual(before);
+  });
+});
+
+describe("bridge follow-up multi-entry queue: v1 edit_followup_slot back-compat", () => {
+  it("replaces the ENTIRE queue with a single entry (v1 semantic)", () => {
+    const s = makeShadow();
+    s.rewriteFollowupQueue(["a", "b", "c"]);
+    s.handleEditFollowupSlotV1Compat("replacement");
+    expect(s.snapshot()).toEqual(["replacement"]);
+  });
+});

package/packages/extension/src/__tests__/bridge-queue-update-forward.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Tests that the bridge forwards pi's `queue_update` event as a typed
+ * QueueUpdateToServerMessage. Also covers idempotent listener registration
+ * via pi.on("queue_update", ...).
+ *
+ * See change: add-followup-edit-and-steer-cancel.
+ */
+import { describe, it, expect, vi } from "vitest";
+
+// We don't test the full bridge here (too much wiring) — we drive the
+// listener-registration-and-forward shape directly with a fake pi.
+
+describe("bridge queue_update forwarding (shape contract)", () => {
+  it("registered queue_update listener emits a typed QueueUpdateToServerMessage on event", () => {
+    // Simulate the listener registration the bridge performs.
+    const listeners: Record<string, (event: any) => void> = {};
+    const fakePi = {
+      on: vi.fn((eventType: string, handler: any) => { listeners[eventType] = handler; }),
+    };
+    const sent: any[] = [];
+    const fakeConnection = { send: (m: any) => sent.push(m) };
+    const sessionId = "S1";
+
+    // Equivalent of the bridge's pi.on("queue_update", ...) registration.
+    fakePi.on("queue_update", (event: any) => {
+      const steering = Array.isArray(event?.steering) ? Array.from(event.steering as readonly string[]) : [];
+      const followUp = Array.isArray(event?.followUp) ? Array.from(event.followUp as readonly string[]) : [];
+      fakeConnection.send({ type: "queue_update", sessionId, steering, followUp });
+    });
+
+    // Fire pi's queue_update event.
+    listeners["queue_update"]({ type: "queue_update", steering: ["a", "b"], followUp: ["c"] });
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toEqual({
+      type: "queue_update",
+      sessionId: "S1",
+      steering: ["a", "b"],
+      followUp: ["c"],
+    });
+  });
+
+  it("forwards empty arrays when pi reports empty queues", () => {
+    const listeners: Record<string, (event: any) => void> = {};
+    const fakePi = { on: vi.fn((t: string, h: any) => { listeners[t] = h; }) };
+    const sent: any[] = [];
+    const sessionId = "S2";
+
+    fakePi.on("queue_update", (event: any) => {
+      const steering = Array.isArray(event?.steering) ? Array.from(event.steering as readonly string[]) : [];
+      const followUp = Array.isArray(event?.followUp) ? Array.from(event.followUp as readonly string[]) : [];
+      sent.push({ type: "queue_update", sessionId, steering, followUp });
+    });
+
+    listeners["queue_update"]({ type: "queue_update", steering: [], followUp: [] });
+
+    expect(sent).toEqual([{ type: "queue_update", sessionId: "S2", steering: [], followUp: [] }]);
+  });
+
+  it("defends against malformed event payloads (missing arrays)", () => {
+    const listeners: Record<string, (event: any) => void> = {};
+    const fakePi = { on: vi.fn((t: string, h: any) => { listeners[t] = h; }) };
+    const sent: any[] = [];
+    const sessionId = "S3";
+
+    fakePi.on("queue_update", (event: any) => {
+      const steering = Array.isArray(event?.steering) ? Array.from(event.steering as readonly string[]) : [];
+      const followUp = Array.isArray(event?.followUp) ? Array.from(event.followUp as readonly string[]) : [];
+      sent.push({ type: "queue_update", sessionId, steering, followUp });
+    });
+
+    // Pi returns object missing the expected fields.
+    listeners["queue_update"]({ type: "queue_update" });
+
+    expect(sent).toEqual([{ type: "queue_update", sessionId: "S3", steering: [], followUp: [] }]);
+  });
+});

package/packages/extension/src/__tests__/bridge-retry-ordering.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Bridge wire-ordering invariant for synthesized retry events.
+ *
+ * Verifies that the bridge updates `RetryTracker` + `UsageLimitOrderer` state
+ * SYNCHRONOUSLY when handling `message_end`, so that a back-to-back `agent_end`
+ * (fired in the same event-loop tick by pi-coding-agent) observes the
+ * up-to-date state.
+ *
+ * Pre-fix bug: the synthesizer state lived inside `setTimeout(0)` (intended
+ * for entryId capture per `fix-per-message-fork`), so `agent_end` was
+ * processed BEFORE the trackers had been updated, the orderer's pending
+ * flag was never set, and `auto_retry_start` shipped on the wire AFTER
+ * `agent_end` — leaving the dashboard's `retryState` stuck (yellow + red
+ * banners both visible).
+ *
+ * See change: fix-retry-banner-stuck-on-limit-exceeded.
+ */
+
+import { describe, it, expect } from "vitest";
+import { RetryTracker } from "../retry-tracker.js";
+import { UsageLimitOrderer } from "../usage-limit-orderer.js";
+
+interface WireEvent {
+  eventType: string;
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Simulates the bridge's synthesizer pipeline as it runs synchronously
+ * inside the message_end / agent_end handlers, capturing all wire sends
+ * in order.
+ */
+class BridgeSim {
+  readonly wire: WireEvent[] = [];
+  private tracker = new RetryTracker();
+  private orderer = new UsageLimitOrderer();
+
+  /** Mirrors bridge.ts message_end handler synthesizer block. */
+  onMessageEnd(sessionId: string, message: { role: string; stopReason?: string; errorMessage?: string }): void {
+    const synthetic = this.tracker.observeMessageEnd(sessionId, message);
+    if (synthetic) {
+      if (synthetic.eventType === "auto_retry_start") {
+        this.orderer.noteRetryStart(sessionId);
+      } else {
+        this.orderer.noteRetryEnd(sessionId);
+      }
+      this.wire.push({ eventType: synthetic.eventType, data: synthetic.data });
+    }
+    // The actual message_end body send is deferred via setTimeout(0) in the
+    // real bridge for entryId capture; for ordering tests we only care about
+    // the synthetic events relative to agent_end.
+    this.wire.push({ eventType: "message_end" });
+  }
+
+  /** Mirrors bridge.ts agent_end handler synthesizer block. */
+  onAgentEnd(sessionId: string, agentEnd: { messages?: Array<Record<string, unknown>> }): void {
+    const orderedSynth = this.orderer.maybeSynthesize(sessionId, agentEnd);
+    if (orderedSynth) {
+      this.wire.push({ eventType: orderedSynth.eventType, data: orderedSynth.data });
+      this.tracker.noteAbort(sessionId);
+    } else {
+      const trackerSynth = this.tracker.observeAgentEnd(sessionId, agentEnd);
+      if (trackerSynth) {
+        this.wire.push({ eventType: trackerSynth.eventType, data: trackerSynth.data });
+      }
+    }
+    this.wire.push({ eventType: "agent_end" });
+  }
+}
+
+describe("Bridge retry-event wire ordering", () => {
+  it("agent_end fired back-to-back after retryable message_end observes pending retry", () => {
+    const sim = new BridgeSim();
+    const sessionId = "s1";
+    const errorMsg = "429 too many requests";
+
+    // Pi fires both events synchronously back-to-back.
+    sim.onMessageEnd(sessionId, { role: "assistant", stopReason: "error", errorMessage: errorMsg });
+    sim.onAgentEnd(sessionId, {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: errorMsg }],
+    });
+
+    const types = sim.wire.map((e) => e.eventType);
+    // auto_retry_start must precede message_end, which must precede the
+    // agent_end-side synthesis. Since the same retryable error is the
+    // terminal message, retryTracker.observeAgentEnd surfaces a final
+    // auto_retry_end{success:false, finalError:errorMsg} BEFORE agent_end.
+    expect(types).toEqual([
+      "auto_retry_start",
+      "message_end",
+      "auto_retry_end",
+      "agent_end",
+    ]);
+    // auto_retry_start MUST come before agent_end on the wire.
+    const startIdx = types.indexOf("auto_retry_start");
+    const agentEndIdx = types.indexOf("agent_end");
+    expect(startIdx).toBeLessThan(agentEndIdx);
+  });
+
+  it("Gemini monthly-spending-cap error orders auto_retry_end before agent_end", () => {
+    const sim = new BridgeSim();
+    const sessionId = "s2";
+    // Real fixture from ~/.pi/agent/sessions/...BME-szakdoga.../*.jsonl line 363
+    const errorMsg = JSON.stringify({
+      error: {
+        message:
+          "Your project has exceeded its monthly spending cap. Please go to AI Studio at https://ai.studio/spend to manage your project spend cap.",
+        status: "RESOURCE_EXHAUSTED",
+      },
+      code: 429,
+      status: "Too Many Requests",
+    });
+
+    sim.onMessageEnd(sessionId, { role: "assistant", stopReason: "error", errorMessage: errorMsg });
+    sim.onAgentEnd(sessionId, {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: errorMsg }],
+    });
+
+    const types = sim.wire.map((e) => e.eventType);
+    expect(types).toEqual([
+      "auto_retry_start",
+      "message_end",
+      "auto_retry_end",
+      "agent_end",
+    ]);
+    // The synthetic auto_retry_end MUST come from the usage-limit orderer
+    // (not the retry-tracker fallback) because the broadened
+    // USAGE_LIMIT_PATTERN matches "monthly spending cap" / RESOURCE_EXHAUSTED.
+    const retryEnd = sim.wire.find((e) => e.eventType === "auto_retry_end")!;
+    expect(retryEnd.data).toMatchObject({ success: false, finalError: errorMsg });
+  });
+
+  it("non-retryable message_end produces no synthesis (only message_end on wire)", () => {
+    const sim = new BridgeSim();
+    sim.onMessageEnd("s3", {
+      role: "assistant",
+      stopReason: "error",
+      errorMessage: "prompt is too long: 300000 tokens > 200000 maximum",
+    });
+    expect(sim.wire.map((e) => e.eventType)).toEqual(["message_end"]);
+  });
+
+  it("successful message_end with no prior retry produces no synthesis", () => {
+    const sim = new BridgeSim();
+    sim.onMessageEnd("s4", { role: "assistant", stopReason: "end_turn" });
+    expect(sim.wire.map((e) => e.eventType)).toEqual(["message_end"]);
+  });
+});