>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588781. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Sessions that start with <code>agent-browser</code> CLI for Phases 0&ndash;4 and then switch to <code>mcp__chrome-devtools__*</code> for visual comparison cause browser-system conflicts: wrong pages appearing in screenshots, Chrome DevTools connection failures, and 195 sleep-based retry calls in a single session. The fix is a strict phase-based browser protocol enforced by the skill.</p> <p>In a recorded session, after a midpoint transition both <code>agent-browser</code> CLI (via Bash) and <code>mcp__chrome-devtools__*</code> MCP tools were in simultaneous use. Background subagents continued navigating the shared <code>agent-browser</code> daemon while the orchestrator was using Chrome DevTools MCP &mdash; meaning screenshots randomly showed the wrong page depending on which system last navigated. One specific subagent navigated the shared daemon to the source site, causing subsequent screenshots to show wrong pages. This was explicitly noted in the session's compaction summary.</p> <p>The 195 sleep-based retry calls (<code>sleep N &amp;amp;&amp;amp; agent-browser screenshot</code>) are a direct CLAUDE.md violation ("Avoid unnecessary sleep commands") and the visual fixes those screenshots were used to evaluate may have been verified against the wrong page state.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Run a migrate-site session through Phases 0&ndash;4 using <code>agent-browser</code> CLI (the default for site-analyzer, Storybook capture, and upload verification).</li> <li>Enter a Phase 5+ visual-comparison phase that uses <code>mcp__chrome-devtools__*</code>.</li> <li>While Phase 5 runs, observe that any background subagent dispatched in Phase 0&ndash;4 may still be issuing <code>agent-browser</code> navigations against the shared Chrome process.</li> <li>Inspect Phase 5 screenshots: page state may not match the URL the orchestrator last requested.</li> <li>Search the session transcript for <code>sleep</code> followed by <code>agent-browser</code>: count instances (recorded session: 195).</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Add a mandatory "Browser Tool Transition" block to <code>.claude/skills/migrate-site/SKILL.md</code>:</p> <pre>BROWSER TOOL PROTOCOL: - Phase 0&ndash;4 (site analysis, Storybook, upload): use agent-browser CLI ONLY - Phase 5+ (visual comparison, Ralph Loop): use mcp__chrome-devtools__* ONLY At the Phase 4&rarr;5 boundary: 1. Confirm all Phase 0-4 background subagents have COMPLETED (not just dispatched) 2. Do NOT start any Phase 5 visual comparison until all agent-browser subagents are done 3. After Phase 4 is complete, never invoke agent-browser in the same session again</pre><p>Replace <code>sleep N &amp;amp;&amp;amp; agent-browser screenshot</code> patterns with <code>mcp__chrome-devtools__wait_for</code> followed by <code>mcp__chrome-devtools__take_screenshot</code>. Search the session codebase for the pattern and replace each instance.</p> <p>Add to instructions for any Phase 5+ subagent: "Do NOT use agent-browser CLI. Use <code>mcp__chrome-devtools__*</code> exclusively. If you need to navigate to a URL, use <code>mcp__chrome-devtools__navigate_page</code>."</p> <p>Document the Phase 4&rarr;5 transition as a hard sync point in SKILL.md: all Phase 0&ndash;4 agents must be confirmed complete before any Phase 5 agent starts. Concurrent <code>agent-browser</code> + <code>chrome-devtools</code> will corrupt screenshots.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the BROWSER TOOL PROTOCOL block to SKILL.md at the Phase 4/5 boundary.</li> <li>Update <code>.claude/agents/visual-verifier.md</code> &mdash; confirm "Use <code>mcp__chrome-devtools__*</code> for all visual comparison" is present; add note "If any background subagent is still using agent-browser, wait for it to complete before starting visual comparison."</li> <li>Update Ralph Loop configuration (<code>.claude/ralph-loop.local.md</code> or equivalent): "All browser operations in this loop use <code>mcp__chrome-devtools__*</code> exclusively. Never invoke agent-browser CLI during the Ralph Loop."</li> <li>Search agent files for <code>sleep N &amp;amp;&amp;amp; agent-browser</code> patterns; replace with <code>wait_for</code>-based conditions.</li> <li>Verify on a fresh run: no <code>sleep N &amp;amp;&amp;amp; agent-browser</code> patterns appear in the session transcript after Phase 4; only <code>mcp__chrome-devtools__*</code> calls appear in browser-related tool uses post-Phase-5.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None. Both <code>agent-browser</code> CLI and <code>mcp__chrome-devtools__*</code> already exist; this is a usage-protocol change, not a tooling change.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-4-Cost-and-Context/01-two-browser-systems-in-simultaneous-use.md</code> (id: P2-5)</li> <li>Dual-browser evidence: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/issues-found.md</code> (A2 &mdash; 195 sleep calls; A3 &mdash; dual browser system)</li> <li>Wrong-page evidence: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/findings.md</code> (F10)</li> <li>Recommended verbatim text: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> (visual-verifier.md section)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/what-actually-works.md</code> &sect; P2 (getComputedStyle Measurement)</li> <li>Consolidated root cause: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> (P2-5)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Do <code>agent-browser</code> and <code>mcp__chrome-devtools__*</code> actually share the same Chrome process, or do they use separate binaries/profiles? Verify by checking <code>.mcp.json</code> for the Chrome DevTools server configuration and comparing with the <code>agent-browser</code> daemon. If profiles are fully separate, the fix becomes a clarity-only rule rather than a race-condition fix.</li> <li>Are there any Phase 5+ agents that legitimately need <code>agent-browser</code> (e.g., menu-builder for form submission)? The protocol may need to permit <code>agent-browser</code> in specific Phase 6 use cases while reserving <code>chrome-devtools</code> for visual comparison only.</li> </ul>