fix(chatgpt-review): unify timeout budget, native insertion, clipboard retry, heartbeat, stall recovery

[BorisTyshkevich]

Summary

Investigated why chatgpt-review's Playwright interactions sometimes failed/stalled during issue #630's long /ship run, by reading the actual code, mining 55 real SessionStore records and dozens of real raw CLI output files from $TMPDIR across the whole run, and running live experiments against real ChatGPT tabs. Found and fixed 5 distinct, evidence-backed root causes:

1. Unified timeout budget — timeoutMs previously bounded only waitForCompletion; setup phases (assertReady/upload/fillAndSend/waitForPermanentConversationUrl) were each independently uncounted against it, so real worst-case wall time was timeoutMs + ~300s. Confirmed live: 6 real invocations across Epic: extract the Fetch-native ClickHouse client into a reusable package #630 were killed with zero output ever flushed. Now one deadline covers the whole call.
2. Fast native prompt insertion — fillAndSend now inserts via execCommand('insertText') in-page first (measured live: 80KB in ~50ms regardless of size), falling back to Playwright's own .fill() only if that fails. Confirmed live that .fill() can still genuinely time out at 120s×2 under real load even after the existing headroom fix (Epic: extract the Fetch-native ClickHouse client into a reusable package #630: 246.9s elapsed, both attempts exhausted).
3. Clipboard-copy retry for plan-author mode — a single failed clipboard read used to fall back to innerText, which can never contain the literal # parsePlanAuthorResponse's heading check requires. Confirmed live: this exact invalid_response recurred 6 times across real Epic: extract the Fetch-native ClickHouse client into a reusable package #630/ADR-0005: adopt @clickhouse/client-web behind the SQL Browser transport adapter #585 invocations. Now retries up to 2 more times before falling back, for that mode specifically.
4. Heartbeat persistence — a periodic progress snapshot is now written alongside the session record, so a process killed externally with zero stdout still leaves something recoverable.
5. Automatic stall recovery — one automatic stop+nudge attempt when generation shows zero text growth for an extended period while still "generating" (a live tool call stuck mid-turn) — previously only recoverable by a human manually intervening, now documented as the last-resort manual fallback in skills/ship/references/review-loops.md.

Test plan

• node --test tests/*.test.mjs — 57/57 pass (11 new tests, one per fix plus the unified-deadline composition specifically)
• node scripts/chatgpt-review.mjs doctor against the real connected Chrome — passes
• One full real end-to-end review() call against a fresh conversation: native insertion used (no .fill() fallback needed), completed in 14.7s, heartbeat fired with the expected shape, response captured correctly (disposable test conversation closed afterward, no real conversations touched)
• Investigated and ruled out a scare during live testing: repeated failures against pre-existing tabs turned out to be caused by my own test scripts leaving stale/dangling CDP connections behind across many rapid successive experiments — not a defect in the fix. Confirmed by cleanly connecting/disconnecting (proper try/finally) against a fresh page, which worked immediately.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LwFPT465eDJqYcRa8HGNLz