fix(voice): bound the redirect-wait loop instead of looping forever

[michaela-band]

What

Reported directly by the voice platform team (AJ): the server exposes /callbacks/voice/continue/{call_id}, and when Bandwidth POSTs to it with no BXML queued yet, the server replies with <Redirect redirectUrl=/callbacks/voice/continue/{call_id}/> — a redirect back to itself, unconditionally. If the agent driving the call is slow, crashed, or never shows up at all, this loops indefinitely: Bandwidth keeps POSTing, the server keeps redirecting to the same URL, forever.

Why

Same underlying mechanism the internal PoC already flagged as a race condition — an LLM agent's tool-call latency vs. Bandwidth's callback retry window. This is the failure mode when the agent loses that race and never recovers (crashes, hangs, or the session just ends), rather than losing it once and getting a clean silent hangup. Left unbounded, it's a real production risk, not just a PoC annoyance — any call where the driving agent disappears mid-session loops forever instead of terminating.

What changed

• src/event_store.py — CallState now tracks waiting_since (when the current redirect-wait period started) via start_waiting_if_unset(), reset back to None in try_set_bxml() once an agent's response actually lands.
• src/callbacks.py — new _wait_or_give_up() replaces the three separate unconditional _redirect_bxml() calls in the /answer, /gather, and /continue handlers. Once BW_MCP_REDIRECT_TIMEOUT_SECONDS (default 12, configurable — the real number Bandwidth itself tolerates before giving up on its own side is unmeasured, flagged in the accompanying conversational-voice spike proposal) elapses with nothing queued, the server returns a terminal response (a short spoken apology + Hangup) instead of another redirect.
• src/specs/AGENTS.md, README.md — documented the timeout, the env var, and that this is the server's own patience bound, not a measured Bandwidth-side limit.
• test/test_callbacks.py — four new tests: timeout fires correctly from /answer, /gather, and /continue, and waiting_since resets once BXML actually lands (so a later, unrelated stall gets a fresh window instead of inheriting an old one).

Testing

Full suite: 121 passed (117 existing + 4 new), no regressions. Also manually verified the timeout path directly against _wait_or_give_up with a fast simulated timeout — confirmed it returns a <Redirect> before the bound and a terminal <Hangup> response after, rather than looping.

Based on main, independent of #14 (respondToGather) — different bug, same callback surface, easier to review separately.

[bwappsec]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.