fix(claude-swe-agent): stop a fast turn from racing the Remote Control session URL (#183)

[k5s-bot]

Summary

Fixes #183 — the "🤖 Starting work on this now. Watch live or take over the session here…" comment is posted for most runs but dropped intermittently on the ai-review flow. The maintainer's note nails it: "most of the time it does. Sometimes it fails to … This should be deterministic logic." It is a timing race, and this makes it deterministic.

Root cause

In runClaudeTurnRemoteControlled (apps/claude-code-swe-agent/src/claude-runner.ts), the poll loop:

• emits the session URL the instant the transcript's bridgeSessionId line appears (remote-control-url progress event → gateway posts the comment), and
• returns the instant it sees a turn_duration entry (turn finished).

The bridgeSessionId line is written when the Remote Control bridge's async registration handshake with claude.ai completes — which is not guaranteed to happen before the turn does. A long triage turn registers the bridge many polls before it finishes, so the URL is always emitted first. A fast, read-only review can finish in the same poll window the bridge is still registering in — and returning the moment turn_duration lands drops the link. Which of the two the transcript flushed first is a race, so the link appears "most of the time" and vanishes on the quick review turns. (ai-review runs use claude-code-swe-agent with Remote Control; e.g. AgentRun fc9f0896 referenced in the code.)

Everything downstream (agent-runtime → orchestrator remoteControlUrlListener → gateway onRemoteControlUrl) is already deterministic and ordered — the URL is only ever dropped because it was never emitted in this race.

Fix

When a turn completes and the URL has not been reported yet, hold the finished turn open for a bounded grace (REMOTE_CONTROL_URL_GRACE_MS, 15s, overridable via urlGraceMs) and keep re-reading the transcript so a just-registered bridge still surfaces its link before returning.

• Zero cost on the happy path — skipped entirely whenever the bridge registered mid-turn and the URL was already emitted (every long/triage turn, and any review where registration won the race).
• Bounded — a bridge that never registers (genuine failure) can't hang a completed review; the grace exits and the result is returned regardless.
• The interactive child stays resident until the finally kill, so registration keeps progressing throughout the wait.

Tests

Adds a latebridge fake-script mode (writes turn_duration first, then appends the bridgeSessionId line ~60ms later) and a regression test asserting the URL is still reported when the bridge line lands after completion. Verified the test fails against the old return-on-completion behavior and passes with the fix; tsc --noEmit is clean.

Two pre-existing tests in this file (went silent as a stall, never gives up on a session reporting busy) flake under parallel load on the ARM CI box used here — they pass in isolation and exercise the running/busy modes, which never reach the turnComplete branch this PR touches.

---

Maintainer: apply the ai-review label to this PR to request an automated code review, or the ai-triage label to have that review feedback addressed and the branch brought back in sync with its base. (The automation can't label its own PR, so this needs a human.)

🤖 Generated with Claude Code

https://claude.ai/code/session_01FLZRLE1mqh9ajMYyKyaWSr