fix(apodex): offload per-turn session persist off the event loop

[Ray0907]

Summary

• TerminalSession._on_turn fires after every agent turn (run_agent_loop awaits on_turn_complete directly) and called _persist() inline — a synchronous open() + json.dump() over the full history, display_history, and workflow_turns.
• As a session grows, this write grows with it, and being awaited directly on the hot per-turn path it stalls the event loop every single turn — no other coroutine (TUI redraw, streaming, etc.) gets to run during the write.
• Moved it to asyncio.to_thread, still awaited so writes stay ordered turn-to-turn (no risk of an out-of-order write corrupting the --resume checkpoint).

Benchmark

2000-message history, 10 persists, with a concurrent heartbeat coroutine standing in for other async work:

sync (current)         elapsed=139.1ms  heartbeat_ticks=   0  max_stall=0.00ms
asyncio.to_thread      elapsed=195.4ms  heartbeat_ticks=4558  max_stall=0.85ms

Sync blocks the loop completely (0 heartbeat ticks in 139ms). to_thread costs a bit more wall time (thread dispatch + GIL handoff) but lets everything else keep running concurrently — the actual user-visible win, since the write itself isn't the bottleneck, the freeze is.

Test plan

• uv run pytest apodex/tests/test_changes.py apodex/tests/test_features.py — 136 passed
• uv run ruff check apodex/session.py — clean

[Copilot]

Copilot review overview

🟡 Changes recommended

Persistence must remain serialized and safe during cancellation.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Cancellation allows concurrent checkpoint writes · New

What changed in this PR

Moves per-turn session persistence off the asyncio event loop to keep the TUI and streaming responsive.

Changes:

• Runs _persist() via asyncio.to_thread.
• Keeps persistence awaited between turns.

File	Summary
apodex/​session.py	Offloads checkpoint writes; cancellation can allow concurrent persistence and risk checkpoint corruption.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[zhanghanduo]

Fixed in c61ff52.

The write lock and atomic replacement prevented interleaved JSON writes, but the payload was still built before acquiring the lock. Cancelling _on_turn leaves the asyncio.to_thread worker running, so that worker could capture old state, let a subsequent save finish, then overwrite it with the stale payload.

The lock now covers the full checkpoint operation: TUI snapshot, session/path and payload capture, temporary-file write, and atomic replacement. A waiting writer therefore captures current state only after acquiring the lock; an in-progress snapshot finishes writing before a newer save can proceed. Per-turn persistence remains off the event loop. The comment on _on_turn now also makes the cancellation behavior explicit.

Added a deterministic regression test that pauses the old snapshot, cancels _on_turn, updates history and renames the session, then lets the background worker finish. It verifies that the newest name and both histories remain on disk. This test fails on the previous PR head and passes with the fix.

Validation: 137 tests passed in apodex/tests/test_changes.py and apodex/tests/test_features.py; Ruff passed for both changed files.