fix(clarify): unblock wait_for_response on thread-scoped interrupt (salvages #25506)

[ayushnangia]

Summary

Salvage of #25506 (@liuhao1024, May 14 — conflicting, author inactive, sweeper verdict keep_open/salvageability=high): the clarify wait_for_response loop never observes the thread-scoped interrupt flag, so /stop or an interrupt-mode message cannot unblock an agent waiting on a clarify prompt. The agent thread wedges for the full clarify timeout (600s default) — or forever when timeout <= 0 (unlimited mode). RC1 of #83889; anchor of family E in the stall triage #84047.

Root cause

The deadlock is a cycle. AIAgent.interrupt() propagates the thread-scoped signal to tool workers (run_agent.py:2696-2703, per the sweeper's review of #25506), but wait_for_response (tools/clarify_gateway.py) polls only its resolution event and the inactivity heartbeat. The clear_session cleanup that cancels pending clarify entries runs at end-of-run (gateway/run.py) — which is unreachable while the thread is blocked in this wait. Flag set, never observed; cleanup ready, never reached.

Changes

• tools/clarify_gateway.py: wait_for_response checks tools.interrupt.is_interrupted() once per slice, before the slice, so an already-interrupted thread never waits at all. Mechanism is @liuhao1024's from fix(clarify): check interrupt flag in gateway wait_for_response loop #25506; defensive import/try so a broken probe can never re-wedge the wait. A response that races the interrupt and resolves first still wins.
• gateway/run.py (_clarify_callback_sync): an interrupted wait now returns [interrupted by user] instead of the misleading [user did not respond within Nm] — @yflmq001's gap from the fix(gateway): unblock clarify wait on /stop or interrupt-mode messages #84119 review, folded as suggested.

Validation

• scripts/run_tests.sh tests/tools/test_clarify_interrupt_wait.py tests/tools/test_clarify_tool.py tests/tools/test_clarify_gateway.py → 48 passed, 0 failed.
• Red proof: with the fix stashed, both interrupt tests fail on main (pytest --timeout=25 guard — on unfixed code the unlimited-wait case blocks forever, which is the bug).
• Six regressions: bounded-wait unblock, unlimited-wait unblock, resolve-wins race, timeout-without-interrupt preserved, no leaked entry rows after an interrupted wait, heartbeat untouched.
• Pre-existing failures in test_clarify_active_session_bypass / photon poll / thread-followup reproduce identically on clean main — unrelated.

Scope notes

• Addresses RC1 of [Bug] clarify deadlock + silent queue on multiplexed Feishu groups (follow-up to #25482, with code refs) #83889. RC2 (multiplex session-key mismatch) is fix(gateway): route multiplex clarify replies by profile #83346 (@Burningiron) — the two compose.
• fix(clarify): check interrupt flag in gateway wait_for_response loop #25506 can be closed as superseded if this lands; @liuhao1024, if you'd rather rebase yours, I'll close this one instead (offer also posted on your PR).
• A compatible belt-and-suspenders follow-up exists (call clear_session inside _interrupt_and_clear_session), but it only covers gateway-driven interrupts; the in-loop check covers all interrupt sources, so it ships first.

[Enough1122]

AI code review — automated review for reference, author can ignore or act on any point.

fix(clarify): unblock wait_for_response on thread-scoped interrupt (salvages #25506)

Good salvage — checking is_interrupted() per slice in tools/clarify_gateway.py:wait_for_response correctly unblocks the bounded and the unlimited wait, and the cleanup test covers the entry leak. Two things to verify:

1. Stale interrupt flag after the abort: wait_for_response breaks when is_interrupted() is true, but the thread's entry in tools.interrupt._interrupted_threads is only cleared by an explicit set_interrupt(False, thread_id=...) from the agent loop — this code path never clears it. If the same worker thread is reused (gateway executor threads are reused across turns) before the flag is cleared, the next wait_for_response on that thread would abort instantly. The interrupt lifecycle is presumably "cleared by AIAgent after the turn ends," but with the wait now exiting mid-turn, confirm who clears it and consider clearing here when the wait exits due to interrupt.
2. Interrupt-vs-resolve race is untested: the docstring claims "a response that raced the interrupt and resolved first still wins," but there is no test where resolve and interrupt are genuinely concurrent — the current tests exercise each in isolation. The outcome depends on loop iteration order (interrupt check at loop top, resolve checked after the slice wait). A deterministic concurrent test would pin the contract.
3. Minor: gateway/run.py:_clarify_callback_sync distinguishes interrupt from timeout by checking is_interrupted() after wait_for_response returns None; a near-simultaneous timeout+interrupt reports "[interrupted by user]" — cosmetic, acceptable.