agent/engine: add idle-message timeout to receive_response loop

[alex-fedotyev]

Summary

Fixes chat sessions that stall indefinitely with is_running=true and no progress. Root cause: the Claude CLI subprocess can hang on socket I/O (stuck Anthropic API call, broken stdio pipe, etc.) and client.receive_response()'s async generator blocks forever. The engine has no other signal that the CLI is dead, the per-session lock stays held, queued user messages back up, and /stop has no effect because the asyncio task is sitting in an uncancellable await.

The synthetic-done backstop from #64 covers three other "no terminal event" shapes (post-stream DB exception, lost WS, streaming-state asymmetry) but can't help when the loop never exits in the first place.

Fix

Wrap each __anext__ of receive_response() in asyncio.wait_for. If no SDK message of any kind arrives within agent.cli_idle_timeout_seconds (default 900s = 15 min), close the iterator and raise TimeoutError. That falls through to the existing CLI-crash retry path in _run_inner, which discards the client, reconnects, and either retries (if no content yet) or surfaces the error (if content already streamed).

The timeout is per-message, not per-turn. A Bash with timeout=600000ms streams tool_use/tool_result chunks that reset the idle timer, so legitimate long tool calls don't trip it. Set agent.cli_idle_timeout_seconds: 0 in config.local.yaml to disable.

Adjacent fixes shipped in the same patch

Both are triggered by the same family of stalls and are too small to split:

1. plans.py:254 — POST /api/plans/{id}/approve scheduled _run_impl via asyncio.create_task without engine.register_task, so /stop couldn't cancel a stuck impl session. The asyncio task was invisible to the stop registry. Now registered.

2. sessions.pyregister_task — the previous done-callback popped the session_id unconditionally. A racing register_task call (or, now, the plan-approve register layered with engine.run's implicit register) could leave the new task without a stop-registry entry when the old task finished. The callback now identity-checks the task before popping, and emits a warning when register_task replaces a still-live task.

Tests

New tests pass; full suite has one pre-existing unrelated capitalization mismatch in test_cli_upgrade.py not touched here.

• test_engine.py::test_iter_response_yields_messages_normally
• test_engine.py::test_iter_response_raises_on_idle_timeout
• test_engine.py::test_iter_response_disabled_when_timeout_zero
• test_engine.py::test_iter_response_handles_empty_stream
• test_sessions.py::test_register_task_replacement_does_not_clobber_new_entry

Live repro before this patch

Session eb740973 hung 15+ minutes after the user sent a follow-up message:

• is_running=true since 02:33:05; no DB activity for 15 min
• queued user message at 02:47:04 sitting behind the per-session asyncio lock
• CLI subprocess (PID 24391) alive in S state, blocked in __arm64_sys_epoll_pwait2
• kill -9 24391 immediately unblocked the lock; the existing exception handler retried and the user message processed on retry

This patch makes that recovery automatic after cli_idle_timeout_seconds.

Test plan

• Unit tests for the new helper and the register_task race
• Full suite green except one pre-existing unrelated failure (test_cli_upgrade.py::test_docker_mode_bails_out — capitalization)
• Apply locally on claude/engine-sdk-resume-guard (this PR cherry-picked on top) and observe a new stall: confirm cli_idle_timeout_seconds fires and the error path runs cleanly

[alex-fedotyev]

Bumping for review. This is one of five small reliability fixes (#63, #64, #65, #66, #67) that compound: each closes one cause of chats that wedge mid-turn, lose context after restart, or get routed into the wrong session. Happy to split, rebase, or land any of them in any order; they don't depend on each other.

In daily use the chat surface is the single biggest friction right now, so any of these merging would help. Let me know if you want changes.