e2e flake: tutor persistence assert can read messages before the turn's rows land (tutor.spec.ts:83)

[AndresL230]

Hit once during PR #475's pre-merge cycles (2026-07-30), on a run whose only delta from a fully-green prior cycle was a one-line selector comment in an unrelated spec — so not a product regression from that PR.

Symptom: tutor.spec.ts:44 "tutor turn renders a reply and persists encrypted to messages" failed at line 83: expect(rows).toHaveLength(SEEDED_MESSAGE_COUNT + 2) — expected 6, received exactly the 4 seeded rows. The UI reply had rendered (earlier assertions passed), but the one-shot queryRaw read the messages table before the turn's user+assistant rows were committed. Passed on the immediately preceding and following full cycles (zero-flake otherwise).

Rate: 1 failure in ~6 full local cycles today (each cycle runs the spec once) plus every recent green main run — rare.

Root-cause candidates: the persistence contract writes both rows before the SSE done event; if the client renders the final bubble off the last token rather than done, a fast function-mode turn can expose a window where the spec's DB read beats the commit. Either await done explicitly before the DB assert, or make line 83 an expect.poll (the pattern gradebook.spec.ts uses for its mutation assert).

Evidence preserved (screenshot / video / trace.zip / error-context.md) at:
/tmp/claude-1000/-home-andresl-Projects-sapling/428d9f6f-5046-455f-a4b7-b17d5bc2e619/scratchpad/tutor-flake-evidence/ — copy out before that tmpdir is cleaned if needed.

Per the #388 zero-flake policy this should be fixed at the root (poll or done-gate), not retried.

[AndresL230]

Fixed in #500 (749c76e).

Root cause

Not a product bug, and worth stating explicitly since the alternative reading pointed at one. The server contract is sound: stream_agent_turn calls on_complete — which is _persist, a synchronous save_message — at services/chat_stream.py:372, and only then yields done at :393. So the rows really are committed before the turn ends.

The gap is that the composer renders off the streamed tokens, not off done. So both UI assertions (toContainText(STUDENT_MESSAGE) / TUTOR_REPLY) can pass while done is still in flight — and the one-shot queryRaw then reads a messages table that has only the 4 seeded rows. That is exactly the reported failure: expected 6, received 4, with the earlier UI assertions green.

So the spec was gating on the wrong signal. A rendered reply is not a persistence signal; the rows are.

Fix

Bounded expect.poll on the row count — the idiom events.spec.ts already uses for its fire-and-forget rollup. Root fix rather than a retry, per the #388 zero-flake policy.

Code review caught a second-order problem in the first cut: polling the count and then re-querying for the content assertions decoupled two checks the original single read had joined, so a duplicate-persistence regression could land a row in the gap and still slice two valid-looking rows off the end. The rows are now captured inside the poll predicate, so the count assertion and the content assertions are the same read.

Honest limitation

A ~1-in-6 race is not reproducible on demand, so this is not backed by a watched-red test, and I am not claiming the observed flake was reproduced and eliminated empirically. What is deterministic: the assert can no longer fail because it read too early — it waits for the condition it depends on, or fails after 5s. The failure mode described in this issue is structurally gone.

Verified: full local cycle green (Playwright 37/37, oracles 0 findings) across three runs today, CI green including the Workers build.

Closing on that basis — reopen if it ever recurs, since a recurrence would mean the cause is something other than the read-too-early window.