Fix/post v0.7 review

[synacktraa]

Post-v0.7 review pass. Three Codex findings + a template rename that became too coupled to split cleanly.

Summary

• P1 — completion race on operator arrival. Detection listeners (framenavigated, DOM mutations) only fire on new events. Any transition into the completion state between session registration and first-connect was lost — the handoff would sit waiting for a future event that never came and time out on completion_timeout. Fires in practice on redirect chains (OAuth /callback, meta-refresh) or any autonomous navigation during the operator-arrival window. Re-probe on connect (LLM included now that the wrapper is loaded) and short-circuit if the state is already reached.

• P2 — viewer keeps live focus after completion. In passthrough, the substrate iframe kept accepting keystrokes for as long as focus stayed there, even after the completion card appeared. In screencast mode the last frame lingered as a stale reference. Fix: defocus the iframe immediately so pending keystrokes stop hitting the substrate, hold the underlying frame for the ~300ms overlay fade-in so the page fades under the card instead of snapping to black, then blank the iframe (about:blank) or drop the last frame (revoke object URL, clear has-frame). Applied symmetrically to both templates.

• Template rename by mode + move under server/. intervention.html and proxy_intervention.html are now screencast-mode.html and passthrough-mode.html under browser_handoff/server/templates/. "Intervention" was a generic verb; "proxy" was misleading (passthrough iframes a substrate viewer, it doesn't proxy). Naming by mode makes the two-mode design visible in the tree. Terminology swept across handoff.py, session.py, streaming.py, the templates' internal cross-references, tests, README, and example smoke tests. StreamingServer and server/streaming.py keep their names — the server hosts both modes.

• P3 — remove the get_stream_url deprecated shim. Its docstring said "Removed in v0.7" while its warning said "Will be removed in v0.7" — self-contradictory in v0.7.x. Resolving toward the docstring. Callers were migrated to get_operator_url before v0.7.

Test plan

• Local pytest — all suites green.
• Manual smoke: passthrough shopping demo, confirm the fade-in reads as a smooth handoff-complete and the substrate iframe stops accepting input the moment the card appears.
• Manual smoke: screencast-mode Heroku login, confirm the last frame drops after the completion card fades in (no broken-image flash).
• Watch for the race fix in a real OAuth flow — pause with a /callback-URL completion condition, delay opening the operator link until after the redirect chain settles, confirm the handoff closes on connect instead of timing out.

🤖 Generated with Claude Code