fix(browser): port upstream existing-session readiness and profile targeting [AI-assisted]

[artemgetmann]

Summary

• Problem: our main fork was missing recent upstream browser fixes for existing-session readiness, non-default Chromium profile targeting, and launch behavior.
• Why it matters: Chrome MCP attach was still more fragile than upstream, existing-session could not cleanly target Brave/Edge/non-default Chrome profiles, and managed browser launch still forced an extra blank tab.
• What changed: cherry-picked upstream commits 71bd0f2b6d (beadd4c553), 49478686c3 (7deb543624), and 88bf26bf25 (72d775e069), then added small follow-up compatibility/type fixes plus switched the worktree helper default from .claude to .codex.
• What did NOT change (scope boundary): no consumer-branch work, no browser relay resurrection, no Docker stdio fix, and no broad upstream sync.

AI-assisted: yes. Built with Codex, with local verification and follow-up fixes for merge compatibility.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #

User-visible / Behavior Changes

• Existing-session browser attach now waits for Chrome MCP tabs to become ready instead of treating first attach as fully ready.
• Existing-session profiles can now target explicit Chromium userDataDir paths for Brave, Edge, Chromium, or non-default Chrome profiles.
• Managed browser launch no longer forces an extra about:blank tab.
• scripts/new-worktree.sh now defaults to .codex/worktrees/<feature> and codex/<feature>.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 / pnpm workspace
• Model/provider: n/a
• Integration/channel (if any): browser / Chrome MCP existing-session
• Relevant config (redacted): default browser config plus explicit existing-session userDataDir paths in tests

Steps

1. Cherry-pick upstream browser commits for attach readiness, userDataDir, and launch args into a fresh branch from main.
2. Run targeted browser tests covering Chrome MCP, config, profile creation, doctor/CLI/browser routes, and existing-session server context.
3. Run pnpm build, bash -n scripts/new-worktree.sh, and scoped format checks on touched files.

Expected

• Existing-session attach waits for usable tabs.
• Non-default Chromium profiles work through userDataDir.
• Launch args do not open a forced blank tab.
• Worktree helper suggests .codex paths/branches.

Actual

• Matched expected behavior in targeted tests and local validation.
• pnpm check still fails on unrelated pre-existing formatting issues in consumer docs (docs/consumer/openclaw-consumer-*.md).
• pnpm build exits 0 but still prints unrelated existing TypeScript errors in src/agents/pi-embedded-runner/run/attempt.ts about skipWaitForIdle.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • pnpm test -- src/browser/chrome.launch-args.test.ts src/browser/chrome-mcp.test.ts src/browser/config.test.ts src/browser/profiles-service.test.ts src/browser/server-context.existing-session.test.ts src/browser/routes/basic.existing-session.test.ts src/browser/server.post-tabs-open-profile-unknown-returns-404.test.ts src/cli/browser-cli-manage.test.ts src/commands/doctor-browser.test.ts
  • pnpm build
  • bash -n scripts/new-worktree.sh
  • pnpm exec oxfmt --check src/browser/chrome-mcp.ts src/browser/config.test.ts src/browser/profiles-service.test.ts src/browser/server-context.existing-session.test.ts src/browser/server-context.tab-ops.ts scripts/telegram-e2e/README.md
• Edge cases checked:
  • legacy Chrome MCP timeout call shapes still work after adding userDataDir
  • built-in cloned user profile expectations remain intact
  • existing-session tab selection still works after readiness polling
• What you did not verify:
  • live browser attach against a real Chrome/Brave/Edge session
  • full pnpm check due unrelated pre-existing doc formatting failures
  • full pnpm test suite

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert the follow-up commits and/or drop the cherry-picked browser commits from this branch.
• Files/config to restore: src/browser/*, src/commands/doctor-browser.ts, and scripts/new-worktree.sh for helper default behavior.
• Known bad symptoms reviewers should watch for: existing-session attach timing out too early, wrong Chromium profile attaching, or a managed browser opening an extra blank tab again.

Risks and Mitigations

• Risk: existing-session attach semantics differ slightly because readiness now waits for tabs after attach.
  • Mitigation: preserved local timeout plumbing and added/updated targeted tests around the Chrome MCP flow.
• Risk: userDataDir support could break older callers that passed timeout options in the second argument position.
  • Mitigation: added backward-compatible argument parsing plus tests for legacy timeout call shapes.