fix: refresh stale cached user-tail repair

[ai-ag2026]

Summary

• Refreshes fix: drop stale cached user tail after saved assistant #2733 on current master without the changelog conflict.
• Drops inactive in-memory cached sessions that still end on a duplicated unsaved user tail when the persisted sidecar already ends on an assistant message.
• Preserves active streams, pending user messages, and genuinely new concurrent user edits.
• Adds focused regression coverage for /api/session?messages=1 returning the saved assistant tail.

Supersedes #2733.
Relates to the state-consistency umbrella #2361.

Patch-reality audit

• fix: drop stale cached user tail after saved assistant #2733 is still unique vs current origin/master (git cherry returned + 0a023a8...).
• Dry cherry-pick onto current origin/master only conflicted in CHANGELOG.md; code and test hunks applied cleanly.
• This PR is the same behavior refreshed from origin/master, with the current changelog preserved and an extra guard added after CI exposed a legitimate concurrent-edit case.

Test plan

• python3 -m pytest tests/test_webui_state_db_reconciliation.py::test_api_session_reload_drops_stale_cached_user_tail_after_saved_assistant tests/test_sprint46.py::test_session_compress_async_reports_stale_session_guard -q -o addopts= -> 2 passed
• python3 -m pytest tests/test_webui_state_db_reconciliation.py tests/test_sprint46.py::test_session_compress_async_reports_stale_session_guard -q -o addopts= -> 15 passed
• python3 -m py_compile api/models.py
• added-line hygiene scans: private marker 0, secret-like 0
• independent blocker re-review after CI fix: passed; no security or logic blockers
• GitHub Actions: test 3.11 / 3.12 / 3.13 all passing at head 8f9e82f606f5892ead9a804094290179425ad4ca

[nesquena-hermes]

Summary

Reading the diff at cron-pr-2802 against origin/master: this is a refresh of #2733 with two material differences. (1) The CHANGELOG conflict is resolved against current master. (2) A new content-equality guard at api/models.py:1804-1811 prevents the cache-tail drop from clobbering a genuinely new concurrent user edit.

Pulled both branches to diff directly. The added guard is exactly the missing piece that the #2733 review needed: the original gate only checked role-sequence shape (cached ends user, disk ends assistant), which is necessary but not sufficient. A concurrent edit racing the saved assistant tail has the same role shape, but the cached tail's text differs from the previous disk user message. The new check encodes that distinction.

Code reference

The added guard at api/models.py:1804-1811:

cached_tail = _last_non_tool_message(cached_messages)
previous_disk_user = None
for message in reversed(disk_messages):
    if _message_role(message) == 'user':
        previous_disk_user = message
        break
if previous_disk_user is None:
    return False

# Only drop tails that look like a duplicated optimistic/recovered user row.
return _message_content_text(cached_tail) == _message_content_text(previous_disk_user)

This is the right framing. The failure mode #2733 was originally fixing — cached [user_A, assistant_B, user_A_dup] vs disk [user_A, assistant_B] — produces cached_tail text == previous_disk_user text, so the cache is replaced. The new concurrent-edit case — cached [user_A, assistant_B, user_NEW_EDIT] vs disk [user_A, assistant_B] — produces cached_tail text != previous_disk_user text, so the cache is preserved and the stale-session guard downstream can report the genuine edit.

The helpers backing it (_last_non_tool_role, _last_non_tool_message, _message_content_text) all live in the same module above get_session() at api/models.py:1726-1761. The content extractor handles both string content and OpenAI-style content-parts arrays ({"text": "..."} part dicts), which matches how Session.load() materializes messages from the sidecar.

The trip-wire pre-check _inactive_cache_tail_needs_disk_check() at api/models.py:1766-1772 keeps the Session.load() overhead bounded: only fire when the cache is inactive (no active stream, no pending), and only when the cached tail ends on a user role. Reasonable performance profile — most get_session() calls won't trigger a disk reload.

Diagnosis

The _cache_has_stale_unsaved_user_tail predicate at api/models.py:1779-1814 orders its checks correctly:

1. Both objects non-None ✓
2. Inactive cache (no active stream, no pending) — overlap with the trip-wire ✓
3. Cached message count > disk message count (cheap length compare) ✓
4. Role-sequence shape (cached ends user, disk ends assistant) ✓
5. Content equality vs previous disk user (the NEW guard) ✓

That ordering means the expensive content comparison only runs when all cheaper checks pass. Good.

The mutation at api/models.py:1820-1830 (in get_session()) takes the LOCK before swapping, which is consistent with the surrounding move_to_end / journal-retry code paths. The except Exception catch-all with logger.debug(..., exc_info=True) is appropriate for a read path — a failed disk reconciliation should fall through to serving the cached session rather than 500'ing.

Test plan

tests/test_webui_state_db_reconciliation.py::test_api_session_reload_drops_stale_cached_user_tail_after_saved_assistant (45 added lines) exercises the exact reproduction described in the PR body. The patch-reality audit in the PR description (git cherry confirming uniqueness, CI 3.11/3.12/3.13 green at 8f9e82f6) suggests the rebase landed cleanly.

The only test I'd add for full coverage of the new guard: a test_does_not_drop_genuinely_new_concurrent_edit case that builds the same shape but with cached_tail text differing from the previous disk user, asserts _cache_has_stale_unsaved_user_tail returns False, and verifies the cached session survives the get_session() call. The current PR has one positive case but no negative case proving the new guard's exit branch. That's the regression I'd most want to pin.

Verdict

LGTM. The refresh resolves the CHANGELOG conflict cleanly and the new content-equality guard is exactly the missing piece. Worth adding the negative-case test before merge, but not a blocker. The deeper review I did on #2733 carries over — the helpers are cleanly factored, the trip-wire pre-check keeps the perf cost bounded, and the LOCK / cache swap shape matches the existing reconciliation surface.

#2733 can be closed in favor of this once #2802 merges.

[nesquena-hermes]

Shipped in v0.51.122 via release/stage-batch4 (#2815). The tightened guard with len(cached) <= len(disk) filter resolves the prior async-compression interaction. Closes umbrella #2361 partially. Thanks for the refresh!