fix(mcp): keep Playwright MCP handshake nonblocking

Author: skulidropek

.github/pr-screenshots/issue-319/implementation.png

@@ -102,9 +102,12 @@ Container runtime env (set via .orch/env/project.env):
   MCP_PLAYWRIGHT_ISOLATED=1|0           Isolated browser contexts; default 0 shares the VNC session
   MCP_PLAYWRIGHT_CDP_GUARD=1|0          Guard CDP so MCP cannot close/crash shared Chromium (default: 1)
   MCP_PLAYWRIGHT_BLOCK_BROWSER_CLOSE=1|0  Block destructive Browser.close/crash CDP methods (default: 1)
-  MCP_PLAYWRIGHT_CDP_ENDPOINT=http://...  Override CDP endpoint (default: http://dg-<repo>-browser:9223)
-  MCP_PLAYWRIGHT_RETRY_ATTEMPTS=<n>     Retry attempts for nested browser startup wait (default: 10)
-  MCP_PLAYWRIGHT_RETRY_DELAY=<seconds>  Delay between retry attempts (default: 2)
+  MCP_PLAYWRIGHT_CDP_ENDPOINT=http://...  Override CDP endpoint (default: http://127.0.0.1:9223)
+  MCP_PLAYWRIGHT_CDP_TIMEOUT=<ms>        CDP connect timeout passed to Playwright MCP (default: 60000)
+  MCP_PLAYWRIGHT_READY_ATTEMPTS=<n>      Startup readiness attempts before disabling broken MCP (default: 60)
+  MCP_PLAYWRIGHT_READY_DELAY=<seconds>   Delay between startup readiness attempts (default: 1)
+  MCP_PLAYWRIGHT_RETRY_ATTEMPTS=<n>     Legacy CDP preflight attempts when CDP guard is disabled (default: 10)
+  MCP_PLAYWRIGHT_RETRY_DELAY=<seconds>  Delay between legacy preflight attempts (default: 2)
 
 Auth providers:
   github, gh         GitHub CLI auth (tokens saved to env file)

.github/pr-screenshots/issue-319/verification.png

@@ -27,6 +27,7 @@ import { renderEntrypointGitConfig, renderEntrypointGitHooks } from "./templates
 import { renderEntrypointGrokConfig } from "./templates-entrypoint/grok.js"
 import { renderEntrypointDockerGitBootstrap } from "./templates-entrypoint/nested-docker-git.js"
 import { renderEntrypointOpenCodeConfig } from "./templates-entrypoint/opencode.js"
+import { renderEntrypointPlaywrightBrowserRuntime } from "./templates-entrypoint/playwright-browser.js"
 import { renderEntrypointProjectAgentRules } from "./templates-entrypoint/project-rules.js"
 import { renderEntrypointRtkConfig } from "./templates-entrypoint/rtk.js"
 import { renderEntrypointBackgroundTasks } from "./templates-entrypoint/tasks.js"
@@ -47,7 +48,6 @@ export const renderEntrypoint = (config: TemplateConfig): string =>
     renderEntrypointCodexHome(config),
     renderEntrypointCodexSharedAuth(config),
     renderEntrypointOpenCodeConfig(config),
-    renderEntrypointMcpPlaywright(config),
     renderEntrypointZshShell(config),
     renderEntrypointZshUserRc(config),
     renderEntrypointPrompt(),
@@ -60,6 +60,8 @@ export const renderEntrypoint = (config: TemplateConfig): string =>
     renderEntrypointProjectAgentRules(),
     renderEntrypointAgentsNotice(config),
     renderEntrypointDockerSocket(config),
+    renderEntrypointPlaywrightBrowserRuntime(config),
+    renderEntrypointMcpPlaywright(config),
     renderEntrypointGitConfig(config),
     renderEntrypointClaudeConfig(config),
     renderEntrypointGeminiConfig(config),

packages/app/src/docker-git/cli/usage.ts

@@ -99,7 +99,7 @@ EOF
   fi
 
   if [[ -z "$MCP_PLAYWRIGHT_CDP_ENDPOINT" ]]; then
-    MCP_PLAYWRIGHT_CDP_ENDPOINT="http://__SERVICE_NAME__-browser:9223"
+    MCP_PLAYWRIGHT_CDP_ENDPOINT="http://127.0.0.1:9223"
   fi
 
   # Replace the docker-git Playwright block to allow upgrades via --force without manual edits.

packages/app/src/lib/core/templates-entrypoint.ts

@@ -160,13 +160,6 @@ const geminiSettingsJsonTemplate = `{
       "selectedType": "oauth-personal"
     },
     "disableYoloMode": false
-  },
-  "mcpServers": {
-    "playwright": {
-      "command": "docker-git-playwright-mcp",
-      "args": [],
-      "trust": true
-    }
   }
 }`
 
@@ -204,10 +197,40 @@ if [[ -d /etc/sudoers.d ]]; then
   chmod 0440 /etc/sudoers.d/gemini-agent
 fi`
 
-const renderGeminiMcpPlaywrightConfig = (_config: TemplateConfig): string =>
-  String.raw`# Gemini CLI: keep Playwright MCP config in sync (TODO: Gemini CLI MCP integration format)
-# For now, Gemini CLI uses MCP via ~/.gemini/settings.json or command line.
-# We'll ensure it has the same Playwright capability as Claude/Codex once format is confirmed.`
+const renderGeminiMcpPlaywrightConfig = (): string =>
+  String.raw`# Gemini CLI: keep Playwright MCP config in sync with container settings
+docker_git_sync_gemini_playwright_mcp() {
+  GEMINI_CONFIG_SETTINGS_FILE="$GEMINI_CONFIG_SETTINGS_FILE" MCP_PLAYWRIGHT_ENABLE="$MCP_PLAYWRIGHT_ENABLE" node - <<'NODE'
+const fs = require("node:fs")
+const path = require("node:path")
+const settingsPath = process.env.GEMINI_CONFIG_SETTINGS_FILE
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+if (typeof settingsPath !== "string" || settingsPath.length === 0) process.exit(0)
+
+let settings = {}
+try {
+  const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"))
+  if (isRecord(parsed)) settings = parsed
+} catch {}
+
+const nextServers = { ...(isRecord(settings.mcpServers) ? settings.mcpServers : {}) }
+if (process.env.MCP_PLAYWRIGHT_ENABLE === "1") {
+  nextServers.playwright = { command: "docker-git-playwright-mcp", args: [], trust: true }
+} else {
+  delete nextServers.playwright
+}
+
+const nextSettings = { ...settings }
+Object.keys(nextServers).length > 0 ? nextSettings.mcpServers = nextServers : delete nextSettings.mcpServers
+
+if (JSON.stringify(settings) === JSON.stringify(nextSettings)) process.exit(0)
+
+fs.mkdirSync(path.dirname(settingsPath), { recursive: true })
+fs.writeFileSync(settingsPath, JSON.stringify(nextSettings, null, 2) + "\n", { mode: 0o600 })
+NODE
+}
+
+docker_git_sync_gemini_playwright_mcp`
 
 const renderGeminiProfileSetup = (config: TemplateConfig): string =>
   String.raw`GEMINI_PROFILE="/etc/profile.d/gemini-config.sh"
@@ -311,7 +334,7 @@ export const renderEntrypointGeminiConfig = (config: TemplateConfig): string =>
   [
     renderGeminiAuthConfig(config),
     renderGeminiPermissionSettingsConfig(config),
-    renderGeminiMcpPlaywrightConfig(config),
+    renderGeminiMcpPlaywrightConfig(),
     renderGeminiSudoConfig(config),
     renderGeminiProfileSetup(config),
     renderEntrypointGeminiNotice(config)

packages/app/src/lib/core/templates-entrypoint/codex.ts

@@ -151,14 +151,7 @@ const renderGrokAuthConfig = (config: TemplateConfig): string =>
 
 const grokSettingsJsonTemplate = `{
   "sandboxMode": "off",
-  "confirmBeforeToolUse": false,
-  "mcpServers": {
-    "playwright": {
-      "command": "docker-git-playwright-mcp",
-      "args": [],
-      "trust": true
-    }
-  }
+  "confirmBeforeToolUse": false
 }`
 
 const grokUserSettingsJsonTemplate = `{
@@ -189,6 +182,41 @@ GROK_SETTINGS_OWNER_GID="$(id -g "${config.sshUser}" 2>/dev/null || id -g)"
 chown -R "$GROK_SETTINGS_OWNER_UID:$GROK_SETTINGS_OWNER_GID" "$GROK_SETTINGS_DIR" || true
 chmod 0600 "$GROK_CONFIG_SETTINGS_FILE" "$GROK_USER_SETTINGS_FILE" 2>/dev/null || true`
 
+const renderGrokMcpPlaywrightConfig = (): string =>
+  String.raw`# Grok CLI: keep Playwright MCP config in sync with container settings
+docker_git_sync_grok_playwright_mcp() {
+  GROK_CONFIG_SETTINGS_FILE="$GROK_CONFIG_SETTINGS_FILE" MCP_PLAYWRIGHT_ENABLE="$MCP_PLAYWRIGHT_ENABLE" node - <<'NODE'
+const fs = require("node:fs")
+const path = require("node:path")
+const settingsPath = process.env.GROK_CONFIG_SETTINGS_FILE
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+if (typeof settingsPath !== "string" || settingsPath.length === 0) process.exit(0)
+
+let settings = {}
+try {
+  const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"))
+  if (isRecord(parsed)) settings = parsed
+} catch {}
+
+const nextServers = { ...(isRecord(settings.mcpServers) ? settings.mcpServers : {}) }
+if (process.env.MCP_PLAYWRIGHT_ENABLE === "1") {
+  nextServers.playwright = { command: "docker-git-playwright-mcp", args: [], trust: true }
+} else {
+  delete nextServers.playwright
+}
+
+const nextSettings = { ...settings }
+Object.keys(nextServers).length > 0 ? nextSettings.mcpServers = nextServers : delete nextSettings.mcpServers
+
+if (JSON.stringify(settings) === JSON.stringify(nextSettings)) process.exit(0)
+
+fs.mkdirSync(path.dirname(settingsPath), { recursive: true })
+fs.writeFileSync(settingsPath, JSON.stringify(nextSettings, null, 2) + "\n", { mode: 0o600 })
+NODE
+}
+
+docker_git_sync_grok_playwright_mcp`
+
 const renderGrokSudoConfig = (config: TemplateConfig): string =>
   String.raw`# Grok CLI: allow passwordless sudo for agent tasks
 # Risk rationale: Grok runs inside an isolated per-project container. The sshUser
@@ -308,6 +336,7 @@ export const renderEntrypointGrokConfig = (config: TemplateConfig): string =>
   [
     renderGrokAuthConfig(config),
     renderGrokPermissionSettingsConfig(config),
+    renderGrokMcpPlaywrightConfig(),
     renderGrokSudoConfig(config),
     renderGrokProfileSetup(config),
     renderEntrypointGrokNotice(config)

packages/app/src/lib/core/templates-entrypoint/gemini.ts

@@ -0,0 +1,28 @@
+import type { TemplateConfig } from "../domain.js"
+
+// CHANGE: source and start the nested browser runtime from the main project entrypoint.
+// WHY: issue #306 follow-up requires dg-*-browser to be owned by dg-* lifecycle, not a host-compose sibling.
+// QUOTE(ТЗ): "раз это браузер контейнер от нашего контейнера то хотелось бы что бы он внутри нашего контейрнера и поднимался бы"
+// REF: issue-306-browser-nested-runtime
+// SOURCE: n/a
+// FORMAT THEOREM: enable_mcp_playwright(project) -> entrypoint(project) attempts nested_browser_start(project)
+// PURITY: SHELL
+// EFFECT: sourced shell functions may call Docker when enabled
+// INVARIANT: stop function is always defined before sshd lifecycle traps are installed
+// COMPLEXITY: O(1)
+export const renderEntrypointPlaywrightBrowserRuntime = (_config: TemplateConfig): string =>
+  String.raw`# Nested Playwright browser runtime. Defaults are no-ops so sshd cleanup can call them unconditionally.
+docker_git_start_playwright_browser() { return 0; }
+docker_git_stop_playwright_browser() { return 0; }
+
+DOCKER_GIT_BROWSER_RUNTIME="/opt/docker-git/browser/docker-git-browser-runtime.sh"
+if [[ -f "$DOCKER_GIT_BROWSER_RUNTIME" ]]; then
+  # shellcheck disable=SC1090
+  source "$DOCKER_GIT_BROWSER_RUNTIME"
+fi
+
+if [[ "$MCP_PLAYWRIGHT_ENABLE" == "1" ]]; then
+  docker_git_start_playwright_browser || true
+else
+  docker_git_stop_playwright_browser || true
+fi`

packages/app/src/lib/core/templates-entrypoint/grok.ts

@@ -155,12 +155,12 @@ const dockerGitSessionSyncPackage = "@prover-coder-ai/docker-git-session-sync@la
 
 const dockerfilePlaywrightMcpBlock = String.raw`RUN npm install -g @playwright/mcp@latest
 
-# docker-git: wrapper that waits for the guarded CDP endpoint before launching Playwright MCP.
+# docker-git: wrapper that launches the MCP stdio server without blocking initialize on CDP readiness.
 RUN cat <<'EOF' > /usr/local/bin/docker-git-playwright-mcp
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Fast-path for help/version (avoid waiting for the browser sidecar).
+# Fast-path for help/version (avoid waiting for nested browser startup).
 for arg in "$@"; do
   case "$arg" in
     -h|--help|-V|--version)
@@ -171,22 +171,36 @@ done
 
 CDP_ENDPOINT="\${MCP_PLAYWRIGHT_CDP_ENDPOINT:-}"
 if [[ -z "$CDP_ENDPOINT" ]]; then
-  CDP_ENDPOINT="http://__SERVICE_NAME__-browser:9223"
+  CDP_ENDPOINT="http://127.0.0.1:9223"
 fi
 
-# CHANGE: add retry logic for browser sidecar startup wait
-# WHY: the browser container may take time to initialize, causing MCP server to fail on first attempt
-# QUOTE(issue-123): "Почему MCP сервер лежит с ошибкой?"
-# REF: issue-123
-# SOURCE: n/a
-# FORMAT THEOREM: forall t in [1..max_attempts]: retry(t) -> eventually(cdp_ready) OR timeout_error
+# CHANGE: keep MCP initialize independent from nested browser readiness
+# WHY: Codex starts MCP servers during boot; blocking here closes stdio before initialize when CDP is slow.
+# QUOTE(issue-319): "handshaking with MCP server failed: connection closed: initialize response"
+# REF: issue-319
+# SOURCE: https://playwright.dev/mcp/configuration/options
+# FORMAT THEOREM: guarded_cdp(endpoint) -> mcp_stdio_ready_before_browser_connection
 # PURITY: SHELL
-# INVARIANT: script exits only after cdp_ready OR all retries exhausted
-# COMPLEXITY: O(max_attempts * timeout_per_attempt)
+# INVARIANT: guarded mode never exits before handing stdio to playwright-mcp
+# COMPLEXITY: O(1)
 MCP_PLAYWRIGHT_RETRY_ATTEMPTS="\${MCP_PLAYWRIGHT_RETRY_ATTEMPTS:-10}"
 MCP_PLAYWRIGHT_RETRY_DELAY="\${MCP_PLAYWRIGHT_RETRY_DELAY:-2}"
 MCP_PLAYWRIGHT_CDP_GUARD="\${MCP_PLAYWRIGHT_CDP_GUARD:-1}"
+MCP_PLAYWRIGHT_CDP_TIMEOUT="\${MCP_PLAYWRIGHT_CDP_TIMEOUT:-60000}"
 
+EXTRA_ARGS=()
+if [[ "\${MCP_PLAYWRIGHT_ISOLATED:-0}" == "1" ]]; then
+  EXTRA_ARGS+=(--isolated)
+fi
+
+# Guarded endpoints are stable HTTP CDP endpoints. Passing the HTTP URL lets Playwright MCP
+# re-resolve /json/version instead of pinning itself to one stale /devtools/browser/<id>.
+if [[ "$MCP_PLAYWRIGHT_CDP_GUARD" == "1" ]]; then
+  exec playwright-mcp --cdp-endpoint "$CDP_ENDPOINT" --cdp-timeout "$MCP_PLAYWRIGHT_CDP_TIMEOUT" "\${EXTRA_ARGS[@]}" "$@"
+fi
+
+# kechangdev/browser-vnc binds Chromium CDP on 127.0.0.1:9222; it also host-checks HTTP requests.
+# When the guard is disabled, preserve the old behavior by converting the HTTP endpoint to WS.
 fetch_cdp_version() {
   curl -sSf --connect-timeout 3 --max-time 10 -H 'Host: 127.0.0.1:9222' "\${CDP_ENDPOINT%/}/json/version" 2>/dev/null
 }
@@ -197,7 +211,7 @@ for attempt in $(seq 1 "$MCP_PLAYWRIGHT_RETRY_ATTEMPTS"); do
     break
   fi
   if [[ "$attempt" -lt "$MCP_PLAYWRIGHT_RETRY_ATTEMPTS" ]]; then
-    echo "docker-git-playwright-mcp: waiting for browser sidecar (attempt $attempt/$MCP_PLAYWRIGHT_RETRY_ATTEMPTS)..." >&2
+    echo "docker-git-playwright-mcp: waiting for nested browser runtime (attempt $attempt/$MCP_PLAYWRIGHT_RETRY_ATTEMPTS)..." >&2
     sleep "$MCP_PLAYWRIGHT_RETRY_DELAY"
   fi
 done
@@ -207,19 +221,6 @@ if [[ -z "$JSON" ]]; then
   exit 1
 fi
 
-EXTRA_ARGS=()
-if [[ "\${MCP_PLAYWRIGHT_ISOLATED:-0}" == "1" ]]; then
-  EXTRA_ARGS+=(--isolated)
-fi
-
-# Guarded endpoints are stable HTTP CDP endpoints. Passing the HTTP URL lets Playwright MCP
-# re-resolve /json/version instead of pinning itself to one stale /devtools/browser/<id>.
-if [[ "$MCP_PLAYWRIGHT_CDP_GUARD" == "1" ]]; then
-  exec playwright-mcp --cdp-endpoint "$CDP_ENDPOINT" "\${EXTRA_ARGS[@]}" "$@"
-fi
-
-# kechangdev/browser-vnc binds Chromium CDP on 127.0.0.1:9222; it also host-checks HTTP requests.
-# When the guard is disabled, preserve the old behavior by converting the HTTP endpoint to WS.
 WS_URL="$(printf "%s" "$JSON" | node -e 'const fs=require("fs"); const j=JSON.parse(fs.readFileSync(0,"utf8")); process.stdout.write(j.webSocketDebuggerUrl || "")')"
 if [[ -z "$WS_URL" ]]; then
   echo "docker-git-playwright-mcp: webSocketDebuggerUrl missing" >&2
@@ -230,10 +231,17 @@ fi
 BASE_WS="$(CDP_ENDPOINT="$CDP_ENDPOINT" node -e 'const { URL } = require("url"); const u=new URL(process.env.CDP_ENDPOINT); const proto=u.protocol==="https:"?"wss:":"ws:"; process.stdout.write(proto + "//" + u.host)')"
 WS_REWRITTEN="$(BASE_WS="$BASE_WS" WS_URL="$WS_URL" node -e 'const { URL } = require("url"); const base=new URL(process.env.BASE_WS); const ws=new URL(process.env.WS_URL); ws.protocol=base.protocol; ws.host=base.host; process.stdout.write(ws.toString())')"
 
-exec playwright-mcp --cdp-endpoint "$WS_REWRITTEN" "\${EXTRA_ARGS[@]}" "$@"
+exec playwright-mcp --cdp-endpoint "$WS_REWRITTEN" --cdp-timeout "$MCP_PLAYWRIGHT_CDP_TIMEOUT" "\${EXTRA_ARGS[@]}" "$@"
 EOF
 RUN chmod +x /usr/local/bin/docker-git-playwright-mcp`
 
+const renderDockerfilePlaywrightRuntime = (config: TemplateConfig): string =>
+  config.enableMcpPlaywright
+    ? `# docker-git nested Playwright browser runtime context
+COPY Dockerfile.browser mcp-playwright-start-extra.sh docker-git-browser-runtime.sh /opt/docker-git/browser/
+RUN chmod +x /opt/docker-git/browser/mcp-playwright-start-extra.sh /opt/docker-git/browser/docker-git-browser-runtime.sh`
+    : ""
+
 /**
  * Renders /etc/profile.d/bun.sh with a runtime-relative PATH extension.
  *
@@ -391,6 +399,7 @@ export const renderDockerfile = (config: TemplateConfig): string =>
     renderDockerfilePrompt(),
     renderDockerfileNode(),
     renderDockerfileBun(config),
+    renderDockerfilePlaywrightRuntime(config),
     renderDockerfileRtk(),
     renderDockerfileOpenCode(),
     renderDockerfileGitleaks(),