---
name: focus_cdp_tab_window
id: focus_cdp_tab_window_bash_infra
kind: function
lang: bash
domain: infra
version: "1.0.0"
purity: impure
signature: "focus_cdp_tab_window(port: int, [target_id: string]) -> void"
description: "Handoff humano de captcha: trae al frente la pestaña (via CDP /json/activate) y la ventana del SO de un Chrome con CDP, para que el humano resuelva el captcha a mano. Promocion del patron inline que acompaña a detect_captcha_go_browser."
tags: [browser, captcha, handoff, cdp, wmctrl, xdotool, infra, navegator]
params:
  - name: "port"
    desc: "Puerto CDP del Chrome (ej. 9333 = Chrome aislado del browser_mcp; 9222 = navegador diario). Obligatorio."
  - name: "target_id"
    desc: "Opcional. Target/tab id CDP de la pestaña del captcha. Si se pasa, se activa esa pestaña dentro del browser antes de levantar la ventana del SO. Si se omite, solo se levanta la ventana."
output: "Stdout una linea legible y JSON-parseable simple: 'focus_cdp_tab_window: focused win=<wid> pid=<pid> port=<port> tab=<target_id_o_->'. Exit 0 en exito; 2 sin puerto, 3 sin DISPLAY, 4 falta wmctrl/xdotool, 5 no hay chromium en el puerto, 6 sin ventana top-level."
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/infra/focus_cdp_tab_window.sh"
---

## Ejemplo

```bash
# Activar la pestaña del captcha (por su target id CDP) y levantar la ventana del Chrome aislado
focus_cdp_tab_window 9333 20EF6E28AA792C53AF0D260F34A768B3
# -> focus_cdp_tab_window: focused win=0x03a00007 pid=48213 port=9333 tab=20EF6E28AA792C53AF0D260F34A768B3

# Solo levantar la ventana del Chrome (sin activar tab concreta)
focus_cdp_tab_window 9333
# -> focus_cdp_tab_window: focused win=0x03a00007 pid=48213 port=9333 tab=-
```

Invocacion canonica via el CLI del registry (despacho bash automatico):

```bash
./fn run focus_cdp_tab_window 9333 20EF6E28AA792C53AF0D260F34A768B3
```

## Cuando usarla

En el handoff humano de captcha: cuando el `browser_mcp` marca `⚠️ CAPTCHA-DETECTED`
(via `detect_captcha_go_browser`), usa esta funcion para traer la pestaña del captcha y la
ventana del Chrome al frente para que el humano lo resuelva a mano; luego se le notifica y se
para la automatizacion. Pasa el `target_id` de la tab donde se detecto el captcha para activar
esa pestaña exacta; omitelo si solo necesitas levantar la ventana del navegador.

## Gotchas

- **Impura, requiere X11**: necesita un entorno grafico (`$DISPLAY` no vacio) + `wmctrl` + `xdotool`
  instalados. No sirve headless ni por SSH sin X forwarding — sale con error y exit != 0.
- **Match pid->ventana fragil**: resuelve la ventana cruzando el PID del browser principal con la
  columna PID de `wmctrl -lp`. Puede fallar si el window manager agrupa ventanas o si chromium no
  expone `_NET_WM_PID` en el main; de ahi el fallback a `xdotool search --pid <pid> --onlyvisible`.
- **No reposiciona entre monitores**: solo activa/levanta la ventana donde ya esta; no la mueve a
  otra pantalla.
- **Varias ventanas del mismo Chrome**: si el browser tiene varias ventanas top-level, coge la
  primera que matchea el PID.
- **Activate CDP best-effort**: `curl /json/activate/<target_id>` puede dar 404 si el `target_id`
  caduco (la tab cambio de id o se cerro). La funcion NO aborta: sigue con el raise de la ventana
  igualmente.
- **Reintento por XFCE**: xfwm pisa el primer `windowactivate`/`windowraise`, por eso se hace el
  activate+raise dos veces con una espera corta entre medias.
- **Identifica el browser process por ausencia de `--type=`**: las lineas de `pgrep` con
  `--type=renderer/gpu/utility/zygote` son procesos hijos; se descartan para quedarse con el main.
