feat(captacion_clientes): scraping freelance en perfil headless dedicado, no chromium-personal

El monitor de captación scrapeaba Workana sobre el navegador personal del
usuario (chromium-personal, CDP 9222), interfiriendo con su navegación. El
scraping CDP debe correr siempre en un perfil headless dedicado.

- Nuevo pipeline monitor_freelance_projects_headless: levanta un Chromium
  headless aislado con perfil dedicado (~/.config/fn_scrape_chrome, CDP 9334)
  vía systemd-run, ejecuta monitor_freelance_projects contra ese puerto y
  cierra la instancia al terminar (finally). Reutiliza el patrón de lifecycle
  de ingest_market_trends_headless. Reutiliza un CDP vivo si el puerto ya
  responde (no cierra lo ajeno).
- scrape_workana_projects y monitor_freelance_projects: default de `port`
  cambiado de 9222 (chromium-personal) a 9334 (perfil dedicado). Default seguro:
  correr a pelo sin Chrome en 9334 falla limpio, no contamina el 9222 personal.

Verificado: el wrapper arranca headless en 9334, scrapea 8 proyectos reales de
Workana, cierra la instancia (9334 muerto, sin proceso colgado) y deja el 9222
personal intacto.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.claude/commands/orquestador.md

@@ -75,36 +75,46 @@ siendo grande para un agente, pásala por el **splitter** (ver `.claude/rules/or
 ### 2. Lanzar cada secundario
 
 **Regla dura: cada secundario se lanza SIEMPRE como terminal visible — window de la flota tmux si
-hay perfil fleet (`$FLEET_SOCKET`, lo normal), o kitty fuera de él. NUNCA como sub-agente del Agent
-tool (ver paso 8).** Empieza por el bloque de flota tmux cuando estás en un perfil fleet; kitty es
-el fallback para secundarios que deban vivir fuera de la flota.
+estás dentro de tmux/una flota, o kitty SOLO cuando de verdad no hay tmux. NUNCA como sub-agente del
+Agent tool (ver paso 8).** La detección de "estoy en una flota" se hace por **`$TMUX`** (señal
+fiable, vía `detect_fleet_context`), **NO por `$FLEET_SOCKET`** (a veces viene vacía en un claude
+resumido/relanzado pese a vivir en la flota → te haría caer a kitty por error). El hook
+`hook_fleet_state_inject.sh` te inyecta cada turno una línea `CONTEXTO FLEET: … socket=<X>` cuando
+estás dentro de la flota; úsala. Empieza por el bloque de flota tmux; kitty es el fallback solo fuera
+de tmux.
 
 Siempre con `--dangerously-skip-permissions` (memoria `lanzar-agentes-skip-permissions`): los
 secundarios trabajan autónomos y desatendidos; los prompts de permiso en cada Bash los atascarían.
 
-#### En la flota tmux (PREFERIDO en perfil fleet)
+#### En la flota tmux (PREFERIDO siempre que estés en tmux)
 
-Si estás dentro de un perfil FleetView (`$FLEET_SOCKET` seteada), **NO lances kitties sueltas**:
-lanza cada ejecutor como una **window de la flota tmux** con `spawn_fleet_agent`, para que viva en
-la flota, se vea en la TUI `fleetview` y sea conmutable con `/fleet focus`:
+Si estás dentro de tmux/una flota (`$TMUX` seteada — compruébalo con `detect_fleet_context`, **no**
+con `$FLEET_SOCKET`), **NO lances kitties sueltas**: lanza cada ejecutor como una **window de la
+flota tmux** con `spawn_fleet_agent`, para que viva en la flota, se vea en la TUI `fleetview` y sea
+conmutable con `/fleet focus`:
 
 ```bash
-./fn run spawn_fleet_agent --socket "$FLEET_SOCKET" --session "$FLEET_SESSION" \
+# spawn_fleet_agent auto-detecta el socket/session de $TMUX — NO hace falta pasar --socket/--session:
+./fn run spawn_fleet_agent \
   --cwd <dir-aislado> --prompt-file /tmp/orq_<slug>.md --title "<subtarea>" \
   --parent "$MI_SESSION_ID"
 # devuelve el window_id; despues escribe el DoD-contrato del ejecutor:
 ./fn run set_dod_contract <sessionId-del-ejecutor> "<DoD golden+edge+error>" pending
 ```
 
-- `spawn_fleet_agent_bash_infra` crea la window tmux + arranca claude con el prompt autocontenido
-  (o `--skill <name>`), y con `--role executor|orchestrator` marca su `goal.json`. El aislamiento
-  git (sub-repo / worktree / scope) sigue imponiéndose en el prompt.
+- `spawn_fleet_agent_bash_infra` **auto-detecta** socket/session del contexto tmux (`$TMUX`) vía
+  `detect_fleet_context`; pásalos explícitos solo si quieres otra flota (los explícitos priman).
+  Crea la window tmux + arranca claude con el prompt autocontenido (o `--skill <name>`), y con
+  `--role executor|orchestrator` marca su `goal.json`. El aislamiento git (sub-repo / worktree /
+  scope) sigue imponiéndose en el prompt.
 - **`--parent <mi-sessionId>` (recomendado):** escribe `parent_orchestrator` en el `goal.json` del
   ejecutor atribuyéndotelo a ti. Es lo que habilita el **push activo** del watcher (te avisa en TU
   pane cuando ese ejecutor termina). Sin `--parent` el aviso no se rutea. Opcional y
   retro-compatible. Ver `.claude/rules/orchestration.md`.
 
-#### Fuera de la flota (kitty fallback)
+#### Fuera de tmux (kitty fallback)
+
+Solo cuando `detect_fleet_context` reporta `in_tmux=false` (de verdad no hay tmux):
 
 ```bash
 ./fn run launch_claude_agent_kitty "<PROYECTO> · <subtarea>" <dir-aislado> /tmp/orq_<slug>.md
@@ -113,7 +123,8 @@ la flota, se vea en la TUI `fleetview` y sea conmutable con `/fleet focus`:
 - `launch_claude_agent_kitty_bash_infra(title, directory, prompt_file)` lanza el secundario con el
   comando canónico (`setsid nohup kitty … zsh -ic 'claude --dangerously-skip-permissions … ; exec
   zsh'`) que sobrevive al cierre de la terminal padre y deja una shell viva al terminar el claude;
-  devuelve el log de arranque (`/tmp/orq_<slug>_kitty.log`). Usa kitty solo fuera de un perfil fleet.
+  devuelve el log de arranque (`/tmp/orq_<slug>_kitty.log`). Usa kitty solo cuando NO estás en tmux
+  (`$TMUX` vacía); estando en una flota, kitty fragmenta la flota — usa `spawn_fleet_agent`.
 
 ### 3. Aislamiento git obligatorio por secundario (regla de oro)
 
@@ -204,8 +215,8 @@ Cuando un secundario termina (rama pusheada + report verde):
 
 **Todo agente de trabajo va como terminal visible del fleet, NUNCA como sub-agente headless del Agent tool.** Un sub-agente headless corre invisible: no sale en `fleetview`, no es conmutable con `/fleet focus` ni se puede retomar. Jerarquía al lanzar un agente:
 
-1. **En perfil fleet** (`$FLEET_SOCKET`, lo normal) → `spawn_fleet_agent` (window de la flota tmux).
-2. **Fuera de un perfil fleet** → kitty con `launch_claude_agent_kitty`.
+1. **Dentro de tmux/flota** (`$TMUX` seteada — comprueba con `detect_fleet_context`, NO con `$FLEET_SOCKET`) → `spawn_fleet_agent` (auto-detecta el socket; window de la flota tmux).
+2. **Fuera de tmux** (`in_tmux=false`) → kitty con `launch_claude_agent_kitty`.
 3. **Agent tool (sub-agente headless)** → **PROHIBIDO para lanzar un agente de trabajo.** SOLO para
    utilidades internas read-only tuyas que devuelven un resultado y mueren: el **verificador**
    adversarial de un cierre, el **splitter** (`Plan`), o una búsqueda puntual (`Explore`).
@@ -268,10 +279,10 @@ git -C ~/fn_registry worktree add /tmp/orq_capdoc -b orq/cap-deploy master
 #    /tmp/orq_health.md  → trabaja en apps/kanban (sub-repo propio), rama issue/health, push, report.
 #    /tmp/orq_capdoc.md  → trabaja SOLO en /tmp/orq_capdoc (worktree), rama orq/cap-deploy, push, report.
 
-# 4. Lanzar ambos (window de la flota si hay $FLEET_SOCKET; aquí kitty fallback). Tras conocer su
-#    sessionId, escribe su DoD-contrato con set_dod_contract.
-./fn run launch_claude_agent_kitty "kanban · health endpoint" ~/fn_registry/apps/kanban /tmp/orq_health.md
-./fn run launch_claude_agent_kitty "fn_registry · doc deploy" /tmp/orq_capdoc /tmp/orq_capdoc.md
+# 4. Lanzar ambos como windows de la flota (estás en tmux → spawn_fleet_agent auto-detecta el socket
+#    de $TMUX; kitty SOLO si in_tmux=false). Tras conocer su sessionId, escribe su DoD-contrato.
+./fn run spawn_fleet_agent --cwd ~/fn_registry/apps/kanban --prompt-file /tmp/orq_health.md --title "kanban · health endpoint" --parent "$MI_SESSION_ID"
+./fn run spawn_fleet_agent --cwd /tmp/orq_capdoc --prompt-file /tmp/orq_capdoc.md --title "fn_registry · doc deploy" --parent "$MI_SESSION_ID"
 
 # 5. Seguir cada turno: drena FLEET-STATE, verifica DICE_TERMINADO, nudge a ESTANCADO, lee reports/ (maquinaria en orchestration.md).
 

.claude/rules/orchestration.md

@@ -123,6 +123,21 @@ existe, degrada limpio sin romper el turno (la línea de rol se sigue emitiendo)
 clasificación sigues drenando (abajo). El resumen lo produce `summarize_fleet_transitions_py_infra`
 sobre el feed del watcher.
 
+Además, el mismo hook inyecta una línea **`CONTEXTO FLEET`** cuando detecta (vía
+`detect_fleet_context_bash_infra`, leyendo **`$TMUX`**, no `$FLEET_SOCKET`) que el orquestador vive
+dentro de una flota tmux:
+
+```
+CONTEXTO FLEET: estás dentro de la fleet tmux socket=<X> session=<Y>. Lanza ejecutores con spawn_fleet_agent (auto-detecta el socket) — NUNCA kitty/launch_claude_agent_kitty estando aquí.
+```
+
+Es el recordatorio que evita el bug de caer a kitty cuando `$FLEET_SOCKET` viene vacía pese a estar
+en la flota: la detección de contexto se hace por `$TMUX` (señal fiable que todo proceso dentro de
+tmux tiene siempre), no por `$FLEET_SOCKET` (a veces ausente en un claude resumido/relanzado). Esta
+parte del hook no necesita venv ni python (solo bash + tmux) y se emite antes del bloque
+`FLEET-STATE`; si el detector falta o `$TMUX` está vacía, simplemente no se emite la línea (turno
+intacto).
+
 Gotcha conocido: el bloque `FLEET-STATE` (peek pasivo) lista transiciones de TODA la flota, incluidas
 las de otros orquestadores y sus ejecutores. Si hay más de un orquestador activo, filtra por tu propia
 familia de agentes (los que tú lanzaste) — igual que en "No te vigiles a ti mismo" más abajo. El **push
@@ -302,7 +317,8 @@ en lote.
 | `summarize_fleet_transitions_py_infra` | Resumir las transiciones del feed en una línea (`terminados/reclaman/estancados`); alimenta el bloque `FLEET-STATE` que el hook `UserPromptSubmit` inyecta cada turno |
 | `classify_fleet_termination_go_infra` | Clasificar el estado de terminación de un agente (RECLAMA/MAL_LANZADO/DICE_TERMINADO/ESTANCADO/TRABAJANDO) — lo usa el watcher |
 | `list_claude_fleet_go_infra` | Fleet tipado con goal/phase/`role` + `dod_contract`/`dod_status` + `tmux_window` (alimenta `/fleet`, el watcher y el tool `fleet_list`). **Invócala por el tool `mcp__orchestrator__fleet_list` (preferido) o el binario `apps/fleetview/fleetview list --json`**, NUNCA por `./fn run` (la despacha como `go test`). El JSON del CLI **ya expone** `role`/`dod_contract`/`dod_status` (`""` si el `goal.json` no los declara); el tool MCP además rellena los vacíos desde `~/.claude/goals/<session_id>.json` |
-| `spawn_fleet_agent_bash_infra` | Lanzar un ejecutor (o el orquestador) como window de la flota tmux — preferido sobre kitty cuando hay perfil fleet. `--parent <tu-sessionId>` atribuye el ejecutor a ti y habilita el push activo del watcher |
+| `detect_fleet_context_bash_infra` | Detectar si estás en una flota tmux derivando socket/session de `$TMUX` (señal fiable), con fallback a `$FLEET_SOCKET`. Devuelve JSON `{in_fleet,in_tmux,socket,session,source}`. Lo usan `spawn_fleet_agent` (auto-detección de socket) y el hook (línea `CONTEXTO FLEET`) para no caer a kitty estando en la flota |
+| `spawn_fleet_agent_bash_infra` | Lanzar un ejecutor (o el orquestador) como window de la flota tmux — preferido sobre kitty siempre que estés en tmux. **Auto-detecta socket/session de `$TMUX`** (vía `detect_fleet_context`) si no se pasan `--socket`/`--session` (los explícitos priman). `--parent <tu-sessionId>` atribuye el ejecutor a ti y habilita el push activo del watcher |
 | `mark_claude_role_py_infra` | Marcar `role` (orchestrator/executor) en el goal.json de un Claude resolviendo PID→sessionId |
 | `mark_claude_parent_py_infra` | Marcar `parent_orchestrator` (sessionId del orquestador que lo lanzó) en el goal.json de un ejecutor resolviendo PID→sessionId. Lo invoca `spawn_fleet_agent --parent`; habilita el routing del watcher al pane del orquestador padre |
 | `kill_fleet_agent_bash_infra` | Cierre dirigido de UN ejecutor: SIGTERM al claude + kill-window de su window tmux. Guards anti-orquestador y anti-self. Lo usa el orquestador para liberar el slot idle tras verificar `met` (auto-kill) |
@@ -311,7 +327,7 @@ en lote.
 **Cómo invocarlas.** Las Bash y Python del grupo se lanzan con `./fn run <id> [args]` (verificado:
 `list_claude_agents`, `drain_fleet_events`, `reboot_all_claudes`, `set_dod_contract`,
 `mark_claude_role`, `mark_claude_parent`, `kill_fleet_agent`, `launch_claude_agent_kitty`,
-`spawn_fleet_agent`). Las **Go con tests** NO: `./fn run` las despacha como `go test`. Por eso
+`spawn_fleet_agent`, `detect_fleet_context`). Las **Go con tests** NO: `./fn run` las despacha como `go test`. Por eso
 `list_claude_fleet_go_infra` se usa por el binario `apps/fleetview/fleetview list --json`, y
 `classify_fleet_termination_go_infra` la consume el watcher embebido en fleetview (no se invoca a
 mano).

.claude/scripts/hook_fleet_state_inject.sh

@@ -46,6 +46,24 @@ ROLE=""
 printf '%s\n' "MODO ORQUESTADOR activo (role=orchestrator)."
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$HOME/fn_registry}"
+
+# Contexto de flota: recordarle al orquestador en que socket/sesion tmux vive,
+# para que lance ejecutores con spawn_fleet_agent (auto-detecta el socket) y
+# NUNCA caiga a kitty estando dentro de la flota. La deteccion va por $TMUX
+# (senal fiable), no por $FLEET_SOCKET (a veces vacia en un claude resumido/
+# relanzado). No necesita venv ni python: solo bash + tmux. Degrada limpio: si
+# el detector falta o falla, simplemente no se emite la linea (turno intacto).
+DETECTOR="$PROJECT_DIR/bash/functions/infra/detect_fleet_context.sh"
+if [ -f "$DETECTOR" ]; then
+    CTX=$(bash "$DETECTOR" 2>/dev/null || true)
+    IN_FLEET=$(printf '%s' "$CTX" | sed -n 's/.*"in_fleet":\(true\|false\).*/\1/p')
+    F_SOCKET=$(printf '%s' "$CTX" | sed -n 's/.*"socket":"\([^"]*\)".*/\1/p')
+    F_SESSION=$(printf '%s' "$CTX" | sed -n 's/.*"session":"\([^"]*\)".*/\1/p')
+    if [ "$IN_FLEET" = "true" ]; then
+        printf 'CONTEXTO FLEET: estas dentro de la fleet tmux socket=%s session=%s. Lanza ejecutores con spawn_fleet_agent (auto-detecta el socket) — NUNCA kitty/launch_claude_agent_kitty estando aqui.\n' "$F_SOCKET" "$F_SESSION"
+    fi
+fi
+
 PY="$PROJECT_DIR/python/.venv/bin/python3"
 { [ -x "$PY" ] && [ -d "$PROJECT_DIR/python/functions" ]; } || exit 0
 

bash/functions/infra/detect_fleet_context.md

@@ -0,0 +1,98 @@
+---
+name: detect_fleet_context
+kind: function
+lang: bash
+domain: infra
+version: 1.0.0
+purity: impure
+signature: "detect_fleet_context() -> JSON {in_fleet,in_tmux,socket,session,source}"
+description: "Detecta de forma robusta si el proceso corre dentro de una flota tmux FleetView, derivando socket y sesion de $TMUX (senal fiable) en vez de $FLEET_SOCKET (fragil, a veces vacia en un claude resumido/relanzado). Salida JSON con in_fleet/in_tmux/socket/session/source."
+tags: [orchestration, fleet, tmux, infra]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: error_go_core
+imports: []
+tested: false
+file_path: "bash/functions/infra/detect_fleet_context.sh"
+params:
+  - name: "(ninguno)"
+    desc: "No recibe argumentos. Lee el entorno ($TMUX, con fallback a $FLEET_SOCKET/$FLEET_SESSION) y consulta el servidor tmux."
+output: "JSON en stdout: {\"in_fleet\":bool, \"in_tmux\":bool, \"socket\":str, \"session\":str, \"source\":\"tmux|fleet_socket|none\"}. in_tmux=true basta para lanzar una window; in_fleet es la senal semantica de 'estoy en una flota'."
+---
+
+# detect_fleet_context
+
+Detecta el contexto de flota del proceso actual sin depender de `$FLEET_SOCKET`.
+
+## Por que existe
+
+La deteccion de "estoy en una flota FleetView" dependia de la variable de
+entorno `$FLEET_SOCKET`, que `launch_fleetclaude` exporta con
+`tmux set-environment -g`. Esa variable solo llega a los procesos que tmux
+arranca **despues** de setearla: un `claude` relanzado o resumido a mano puede
+no heredarla y `$FLEET_SOCKET` queda vacia, aunque ese claude SI viva en una
+window de la flota. Cuando eso pasa, el modo orquestador cae al fallback kitty
+(`launch_claude_agent_kitty`) y lanza ejecutores en terminales sueltas en vez de
+como windows de la flota.
+
+La senal **fiable** es `$TMUX`: todo proceso dentro de tmux la tiene SIEMPRE, con
+el formato `/tmp/tmux-<uid>/<socket>,<server_pid>,<client_id>`. De ahi se extrae
+el socket (basename del path antes de la primera coma) y, con
+`tmux -L <socket> display-message -p '#{session_name}'`, la sesion actual.
+
+## Salida
+
+```json
+{"in_fleet":true,"in_tmux":true,"socket":"fleet3","session":"fleet3","source":"tmux"}
+```
+
+| Campo | Significado |
+|---|---|
+| `in_fleet` | Heuristica de "estoy en una flota". `true` si en tmux Y (socket/sesion casan `fleet`, O hay window `fleetview`, O la sesion tiene >= 2 windows). |
+| `in_tmux` | `true` si el proceso esta dentro de tmux. Basta para lanzar una window (mejor que caer a kitty). |
+| `socket` | Socket tmux derivado de `$TMUX` (o de `$FLEET_SOCKET` en fallback). |
+| `session` | Sesion tmux actual resuelta con `display-message` (fallback a `$FLEET_SESSION` o al socket). |
+| `source` | `tmux` (derivado de `$TMUX`), `fleet_socket` (fallback), o `none`. |
+
+## Ejemplo
+
+```bash
+# Dentro de una window de la flota fleet3:
+bash bash/functions/infra/detect_fleet_context.sh
+# {"in_fleet":true,"in_tmux":true,"socket":"fleet3","session":"fleet3","source":"tmux"}
+
+# Fuera de tmux, sin FLEET_SOCKET:
+env -u TMUX -u FLEET_SOCKET bash bash/functions/infra/detect_fleet_context.sh
+# {"in_fleet":false,"in_tmux":false,"socket":"","session":"","source":"none"}
+
+# Parsear el socket con jq para pasarlo a spawn_fleet_agent:
+ctx=$(bash bash/functions/infra/detect_fleet_context.sh)
+sock=$(printf '%s' "$ctx" | jq -r .socket)
+```
+
+## Cuando usarla
+
+Antes de lanzar un ejecutor de la flota: llama a esta funcion para saber si
+estas dentro de una flota tmux. Si `in_tmux=true`, lanza con `spawn_fleet_agent`
+(que ya la usa para auto-detectar el socket); NUNCA caigas a kitty. Tambien la
+usa el hook `hook_fleet_state_inject.sh` para recordarle al orquestador el socket
+de su flota cada turno.
+
+## Gotchas
+
+- Es **impura**: consulta el servidor tmux (`display-message`, `list-windows`).
+  No modifica estado.
+- `in_fleet` es **heuristico** a proposito. Para LANZAR basta `in_tmux=true`
+  (lanzar una window en cualquier tmux supera a una kitty suelta). `in_fleet` es
+  solo la senal semantica que consume el hook y la doctrina.
+- Fallback `source=fleet_socket`: si `$TMUX` no esta pero `$FLEET_SOCKET` si,
+  devuelve `socket`/`session` de esas vars con `in_tmux=false`. Un
+  `tmux -L <socket> new-window` puede seguir funcionando si el servidor existe,
+  aunque el caller no este attached.
+- No requiere `jq` ni python: emite el JSON con `printf`, para poder ser el
+  detector base que invocan hooks y otras funciones bash.
+- Si `tmux` no esta instalado y `$TMUX` esta seteada (raro), `socket` se deriva
+  igual de `$TMUX` pero `session` cae al fallback y `in_fleet` no se puede afinar
+  por windows.

bash/functions/infra/detect_fleet_context.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# detect_fleet_context — detecta de forma robusta si el proceso actual corre
+# dentro de una sesion tmux de una flota FleetView, derivando el socket y la
+# sesion de la variable de entorno $TMUX (senal fiable) en vez de depender de
+# $FLEET_SOCKET (que a veces viene vacia en el entorno de un claude resumido o
+# relanzado, aunque ese claude SI viva en una window de la flota).
+#
+# Por que $TMUX y no $FLEET_SOCKET:
+#   launch_fleetclaude exporta FLEET_SOCKET/FLEET_SESSION con `tmux
+#   set-environment -g`. Esa variable solo llega a los procesos que tmux arranca
+#   DESPUES de setearla; un claude relanzado o resumido a mano puede no heredarla
+#   y entonces $FLEET_SOCKET queda vacia. En cambio, todo proceso que corre
+#   dentro de tmux tiene SIEMPRE $TMUX seteada, con el formato:
+#       /tmp/tmux-<uid>/<socket>,<server_pid>,<client_id>
+#   De ahi se extrae el socket (basename del path antes de la primera coma) y,
+#   con `tmux -L <socket> display-message -p '#{session_name}'`, la sesion
+#   actual. Eso identifica el contexto fleet sin depender de $FLEET_SOCKET.
+#
+# Salida: JSON en stdout con los campos:
+#   in_fleet : true|false — heuristica de "estoy en una flota" (ver criterio).
+#   in_tmux  : true|false — estoy dentro de tmux (basta para lanzar una window).
+#   socket   : nombre del socket tmux derivado ("" si no hay).
+#   session  : nombre de la sesion tmux actual ("" si no se resuelve).
+#   source   : "tmux" | "fleet_socket" | "none" — de donde se derivo el contexto.
+#
+# Criterio de "flota reconocible" (in_fleet): estar en tmux (in_tmux) Y que se
+# cumpla al menos uno, de mas fiable a menos:
+#   1. el socket o la sesion casan el patron de flota (contienen "fleet"), o
+#   2. existe una window llamada "fleetview" (la TUI de la flota), o
+#   3. la sesion tiene >= 2 windows (una flota agrupa varios agentes en windows).
+# Es heuristico a proposito: para LANZAR un ejecutor basta con in_tmux (lanzar
+# una window en cualquier tmux es mejor que caer a una kitty suelta); in_fleet es
+# la senal semantica que consume el hook del orquestador y la doctrina.
+#
+# Funcion IMPURA: lee el entorno y consulta el servidor tmux (display-message,
+# list-windows). No modifica estado. Degrada limpio: si tmux no esta o falla
+# cualquier consulta, devuelve los campos que pueda y nunca aborta con error.
+set -euo pipefail
+IFS=$' \t\n'
+
+detect_fleet_context() {
+    local socket="" session="" source="none"
+    local in_tmux="false" in_fleet="false"
+
+    if [[ -n "${TMUX:-}" ]]; then
+        in_tmux="true"
+        source="tmux"
+        # $TMUX = /tmp/tmux-<uid>/<socket>,<server_pid>,<client_id>
+        # Socket = basename del path antes de la primera coma.
+        local tmux_path="${TMUX%%,*}"
+        socket="$(basename "$tmux_path" 2>/dev/null || true)"
+        # Sesion actual: tmux resuelve el cliente via $TMUX. -L fija el socket.
+        if command -v tmux >/dev/null 2>&1 && [[ -n "$socket" ]]; then
+            session="$(tmux -L "$socket" display-message -p '#{session_name}' 2>/dev/null || true)"
+        fi
+        # Fallback de sesion si display-message no resolvio nada.
+        [[ -z "$session" ]] && session="${FLEET_SESSION:-$socket}"
+    elif [[ -n "${FLEET_SOCKET:-}" ]]; then
+        # No estamos en tmux pero hay FLEET_SOCKET exportada: usarla como ultimo
+        # recurso (un claude que perdio $TMUX pero conserva la env del perfil).
+        in_tmux="false"
+        source="fleet_socket"
+        socket="${FLEET_SOCKET}"
+        session="${FLEET_SESSION:-$socket}"
+    fi
+
+    # Heuristica in_fleet: solo tiene sentido si estamos en tmux.
+    if [[ "$in_tmux" == "true" && -n "$socket" ]]; then
+        local sl="${socket,,}" sesl="${session,,}"
+        if [[ "$sl" == *fleet* || "$sesl" == *fleet* ]]; then
+            in_fleet="true"
+        elif command -v tmux >/dev/null 2>&1; then
+            # Construir el target de sesion sin trucos de expansion fragiles.
+            local -a tgt=()
+            [[ -n "$session" ]] && tgt=(-t "$session")
+            # window "fleetview" presente => flota.
+            if tmux -L "$socket" list-windows "${tgt[@]}" \
+                 -F '#{window_name}' 2>/dev/null | grep -qx 'fleetview'; then
+                in_fleet="true"
+            else
+                # >= 2 windows => agrupacion tipo flota.
+                local nwin
+                nwin="$(tmux -L "$socket" list-windows "${tgt[@]}" \
+                          -F x 2>/dev/null | wc -l | tr -d ' ')"
+                [[ "${nwin:-0}" -ge 2 ]] && in_fleet="true"
+            fi
+        fi
+    fi
+
+    # JSON sin dependencias (jq/python no requeridos: este es el detector base).
+    printf '{"in_fleet":%s,"in_tmux":%s,"socket":"%s","session":"%s","source":"%s"}\n' \
+        "$in_fleet" "$in_tmux" "$socket" "$session" "$source"
+    return 0
+}
+
+# Permitir ejecutar el archivo directamente (no solo como funcion sourced).
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    detect_fleet_context "$@"
+fi

bash/functions/infra/spawn_fleet_agent.md

@@ -3,23 +3,24 @@ name: spawn_fleet_agent
 kind: function
 lang: bash
 domain: infra
-version: 1.1.0
+version: 1.2.0
 purity: impure
-signature: "spawn_fleet_agent --socket <s> --session <s> --cwd <dir> [--prompt-file <f> | --skill <name>] [--role orchestrator|executor] [--parent <sid>] [--title <t>]"
-description: "Lanza un Claude como window nueva dentro de la sesion tmux de un perfil FleetView (socket aislado), opcionalmente en modo orquestador (skill embebida como primer prompt), marcado con un role en su goal.json y atribuido a su orquestador padre. Es la forma de que un ejecutor o el propio orquestador VIVAN en la flota tmux (visibles en la TUI fleetview, conmutables con /fleet focus) en vez de en kitties sueltas. Reemplaza a launch_claude_agent_kitty cuando se opera dentro de un perfil fleet ya montado. Con --parent <sid> escribe parent_orchestrator en el goal.json del nuevo Claude (via mark_claude_parent) para que el watcher de fleetview rutee sus avisos al orquestador que lo lanzo. Imprime el window_id creado."
+signature: "spawn_fleet_agent [--socket <s>] [--session <s>] [--cwd <dir>] [--prompt-file <f> | --skill <name>] [--role orchestrator|executor] [--parent <sid>] [--title <t>]"
+description: "Lanza un Claude como window nueva dentro de la sesion tmux de un perfil FleetView (socket aislado), opcionalmente en modo orquestador (skill embebida como primer prompt), marcado con un role en su goal.json y atribuido a su orquestador padre. --socket/--session son opcionales: si no se pasan se auto-detectan del contexto tmux ($TMUX) via detect_fleet_context (los explicitos tienen prioridad), evitando caer a kitty cuando $FLEET_SOCKET viene vacia. Es la forma de que un ejecutor o el propio orquestador VIVAN en la flota tmux (visibles en la TUI fleetview, conmutables con /fleet focus) en vez de en kitties sueltas. Reemplaza a launch_claude_agent_kitty cuando se opera dentro de un perfil fleet ya montado. Con --parent <sid> escribe parent_orchestrator en el goal.json del nuevo Claude (via mark_claude_parent) para que el watcher de fleetview rutee sus avisos al orquestador que lo lanzo. Imprime el window_id creado."
 tags: [fleet, claude-fleet, orchestration, tmux, infra]
 uses_functions:
   - mark_claude_role_py_infra
   - mark_claude_parent_py_infra
+  - detect_fleet_context_bash_infra
 uses_types: []
 error_type: error_go_core
 file_path: "bash/functions/infra/spawn_fleet_agent.sh"
 tested: false
 params:
   - name: --socket
-    desc: "Socket tmux del perfil FleetView (ej. fleet, fleet2). El perfil debe estar ya montado (sesion viva)."
+    desc: "Socket tmux del perfil FleetView (ej. fleet, fleet2). Opcional: se auto-detecta de $TMUX via detect_fleet_context si no se pasa. El perfil debe estar ya montado (sesion viva)."
   - name: --session
-    desc: "Nombre de la sesion tmux dentro del socket (normalmente igual al socket)."
+    desc: "Nombre de la sesion tmux dentro del socket (normalmente igual al socket). Opcional: se auto-detecta de $TMUX si no se pasa."
   - name: --cwd
     desc: "Directorio de trabajo del nuevo Claude. Default: PWD."
   - name: --prompt-file
@@ -54,6 +55,11 @@ Lanza un Claude dentro de un perfil FleetView (sesion tmux de un socket aislado)
 ./fn run spawn_fleet_agent --socket fleet2 --session fleet2 --cwd "$HOME/fn_registry" \
   --prompt-file /tmp/orq_health.md --title "kanban-health" \
   --parent 32945650-a4e1-472b-90c9-5b38ef60a463
+
+# Sin --socket/--session: auto-detecta el socket de la flota actual ($TMUX).
+# Forma preferida desde dentro de la flota — no hace falta saber el socket:
+./fn run spawn_fleet_agent --cwd "$HOME/fn_registry" \
+  --prompt-file /tmp/orq_health.md --title "kanban-health"
 ```
 
 ## Cuando usarla
@@ -62,9 +68,14 @@ Cuando el orquestador (o el launcher) necesita arrancar un Claude que debe vivir
 
 ## Gotchas
 
+- **Auto-deteccion de socket/session**: si no pasas `--socket`/`--session`, se derivan de `$TMUX` via `detect_fleet_context`. Los explicitos tienen prioridad. Solo aborta (exit 2) si tras auto-detectar siguen vacios (de verdad no hay tmux). No dependas de `$FLEET_SOCKET`: a veces viene vacia en un claude resumido/relanzado aunque viva en la flota — `$TMUX` es la senal fiable.
 - El perfil (socket+session) debe estar **ya montado** (`launch_fleetclaude` primero); si la sesion no existe, falla con exit 1.
 - El `--role` se aplica en **background**: el `sessionId` del nuevo Claude no existe hasta que Claude escribe `~/.claude/sessions/<PID>.json` (unos segundos). `mark_claude_role` espera ese archivo. Si el arranque es muy lento, el role puede tardar en aparecer; es no-fatal (el agente simplemente no se pinea/identifica hasta entonces).
 - El `--parent` se aplica igual en **background** via `mark_claude_parent` (misma espera del `sessions/<PID>.json`). Cuando se pasan `--role` y `--parent` juntos se encadenan **secuencialmente** en el mismo subshell (primero role, luego parent) para que la segunda escritura lea el goal ya con la primera clave puesta — sin carrera de lectura-modificacion-escritura. Es no-fatal: si el sessions JSON no aparece a tiempo, el `parent_orchestrator` simplemente no se escribe.
 - `--skill` envia `/<name>` como primer prompt: depende de que Claude Code interprete el primer argumento como invocacion de slash command (verificado con `/orquestador`).
 - El nuevo Claude hereda `FLEET_SOCKET`/`FLEET_SESSION` del entorno del server tmux (que `launch_fleetclaude` fija con `set-environment`), asi apunta al perfil correcto.
 - `--dangerously-skip-permissions` siempre (los agentes de la flota trabajan desatendidos); riesgo asumido como en el resto del modo orquestador.
+
+## Capability growth log
+
+- v1.2.0 (2026-06-21) — `--socket`/`--session` ahora son opcionales: se auto-detectan del contexto tmux (`$TMUX`) via `detect_fleet_context` cuando no se pasan. Elimina el gotcha de caer a kitty cuando `$FLEET_SOCKET` viene vacia pese a estar en la flota. Los valores explicitos siguen primando.

bash/functions/infra/spawn_fleet_agent.sh

@@ -29,11 +29,15 @@ spawn_fleet_agent() {
             --title)       shift; title="${1:-claude}" ;;
             -h|--help)
                 cat <<'USAGE'
-Uso: spawn_fleet_agent --socket <s> --session <s> --cwd <dir> [opciones]
+Uso: spawn_fleet_agent [--socket <s>] [--session <s>] [--cwd <dir>] [opciones]
 
 Lanza un Claude como window nueva en la sesion tmux <session> del socket <socket>
 (un perfil FleetView ya montado). Imprime el window_id creado.
 
+--socket/--session son OPCIONALES: si no se pasan, se auto-detectan del contexto
+tmux actual ($TMUX) via detect_fleet_context. Los valores explicitos tienen
+prioridad. Aborta solo si tras auto-detectar siguen vacios (no hay tmux).
+
 Opciones:
   --prompt-file <f>  Primer prompt del Claude = contenido del archivo (prompt
                      autocontenido del ejecutor). El cat lo hace el shell del
@@ -66,8 +70,25 @@ USAGE
         shift
     done
 
+    # Auto-detectar socket/session del contexto tmux ($TMUX) cuando no se pasan
+    # explicitos. Los --socket/--session explicitos SIEMPRE tienen prioridad.
+    # Esto evita el bug de caer a kitty cuando $FLEET_SOCKET viene vacia pese a
+    # estar dentro de una window de la flota (ver detect_fleet_context).
+    if [[ -z "$socket" || -z "$session" ]]; then
+        local _detector ctx det_socket="" det_session=""
+        _detector="$(dirname "${BASH_SOURCE[0]}")/detect_fleet_context.sh"
+        if [[ -f "$_detector" ]]; then
+            ctx="$(bash "$_detector" 2>/dev/null || true)"
+            # Parseo minimo sin depender de jq: extraer "socket":"..." / "session":"...".
+            det_socket="$(printf '%s' "$ctx" | sed -n 's/.*"socket":"\([^"]*\)".*/\1/p')"
+            det_session="$(printf '%s' "$ctx" | sed -n 's/.*"session":"\([^"]*\)".*/\1/p')"
+            [[ -z "$socket" ]]  && socket="$det_socket"
+            [[ -z "$session" ]] && session="$det_session"
+        fi
+    fi
+
     [[ -z "$socket" || -z "$session" ]] && {
-        echo "spawn_fleet_agent: --socket y --session son obligatorios" >&2
+        echo "spawn_fleet_agent: no se detecto contexto tmux (\$TMUX vacia) y no se pasaron --socket/--session. Lanza desde dentro de la flota o pasa el socket/session explicito." >&2
         return 2
     }
     [[ -z "$cwd" ]] && cwd="$PWD"

docs/capabilities/INDEX.md

@@ -42,7 +42,7 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu
 | [sink](sink.md) | 11 | Funciones que escriben datos a destino externo (BD, dashboard, alerta, email). Nodos output |
 | [validator](validator.md) | 6 | Funciones que verifican datos/config contra reglas. Pre-flight de sinks y gates en DAGs |
 | [navegator](navegator.md) | 4 | Automatización de browser via CDP + AX tree + LLM: obtener, limpiar, chunkear AX tree y llamar a Claude CLI |
-| [img-to-3d](img-to-3d.md) | 3 | Imagen 2D -> modelo 3D: profundidad monocular (Depth-Anything-V2) + malla de relieve texturizada exportada a .glb, con pipeline one-shot. Produce el glb que mesh-3d consume/renderiza |
+| [img-to-3d](img-to-3d.md) | 4 | Imagen 2D -> modelo 3D: recorte de fondo (rembg/GrabCut/umbral) + profundidad monocular (Depth-Anything-V2) + malla de relieve texturizada exportada a .glb, con pipeline one-shot. Produce el glb que mesh-3d consume/renderiza |
 | [whatsapp](whatsapp.md) | 3 | Operar WhatsApp Web por CDP sobre la pestaña existente (sin ventana ni foco): buscar/abrir chat, leer conversacion, enviar texto. Compone 4 primitivas CDP-Python (cdp_eval/type_chars/press_key/click_xy). No HTTP: WhatsApp usa WebSocket + cifrado E2E |
 | [cpp-dashboard-viz](cpp-dashboard-viz.md) | 10 | Primitivas C++ ImGui para dashboards: kpi_card, sparkline, line/bar/scatter/pie/heatmap/histogram, panel containers |
 | [agents](agents.md) | 3 | Orquestar agentes Claude headless en git worktrees: launch, cleanup, DoD evidence schema audit |

docs/capabilities/img-to-3d.md

@@ -10,24 +10,27 @@ partir de una sola foto se estima un mapa de profundidad monocular con un modelo
 reconstruye una malla de relieve (heightmap) texturizada con la imagen original, exportada como
 `.glb` cargable por cualquier visor glTF (three.js `useGLTF`/`GLTFLoader`, Babylon, model-viewer).
 
-Promovido desde la app `img_to_3d_webapp` (su backend incrustaba estas dos funciones; ver su
-`backend/depth.py`). El flujo canonico es de **dos pasos encadenados**:
+Promovido desde la app `img_to_3d_webapp` (su backend incrustaba estas funciones; ver
+`backend/depth.py` y `backend/bg_removal.py`). El flujo canonico encadena un pre-proceso opcional
+de fondo con los dos pasos de reconstruccion:
 
 ```
-estimate_image_depth (imagen -> depth+image) -> depth_to_relief_glb (depth+image -> .glb)
+[remove_background (imagen -> rgb+mask)] -> estimate_image_depth (imagen -> depth+image) -> depth_to_relief_glb (depth+image[+mask] -> .glb)
 ```
 
 ## Funciones
 
 | ID | Firma corta | Que hace |
 |---|---|---|
+| `remove_background_py_datascience` | `remove_background(image_path, engine?) -> dict` | **Pre-proceso (paso 0).** Elimina el fondo en cascada rembg -> GrabCut -> umbral y compone el objeto sobre gris neutro. Devuelve `image` PIL + `mask` ndarray. La `mask` se pasa a `depth_to_relief_glb` para recortar la malla al objeto. |
 | `estimate_image_depth_py_datascience` | `estimate_image_depth(image_path, model_name?, device?, use_cache?) -> dict` | Estima profundidad monocular con Depth-Anything-V2 (GPU/CPU). Devuelve `depth` ndarray [0,1] + `image` PIL. Paso 1. |
-| `depth_to_relief_glb_py_datascience` | `depth_to_relief_glb(image, depth, out_glb_path, z_scale?, max_dim?) -> dict` | Convierte `depth`+`image` en una malla de relieve texturizada y la exporta a `.glb`. Paso 2. |
-| `build_relief_glb_from_image_py_pipelines` | `build_relief_glb_from_image(image_path, out_glb_path, model_name?, device?, z_scale?, max_dim?) -> dict` | **Pipeline one-shot**: compone los dos pasos en una sola llamada (imagen -> .glb). Salida JSON-serializable, apta para `fn run`. |
+| `depth_to_relief_glb_py_datascience` | `depth_to_relief_glb(image, depth, out_glb_path, z_scale?, max_dim?, mask?) -> dict` | Convierte `depth`+`image` en una malla de relieve texturizada y la exporta a `.glb`. Con `mask` opcional recorta las caras del fondo. Paso 2. |
+| `build_relief_glb_from_image_py_pipelines` | `build_relief_glb_from_image(image_path, out_glb_path, model_name?, device?, z_scale?, max_dim?) -> dict` | **Pipeline one-shot**: compone estimacion + relieve en una sola llamada (imagen -> .glb). Salida JSON-serializable, apta para `fn run`. |
 
-Las tres son **impuras** (cargan modelo / GPU / escriben archivo), devuelven `dict` con `status`
+Las cuatro son **impuras** (cargan modelo / GPU / escriben archivo), devuelven `dict` con `status`
 (`ok`/`error`) y **nunca lanzan**: los fallos vuelven como `{status:'error', error:str}`. El
-pipeline ademas marca `stage` (`estimate`/`relief`) en el error.
+pipeline ademas marca `stage` (`estimate`/`relief`) en el error. `remove_background` en
+`engine="auto"` nunca falla (cae al umbral NumPy puro sin deps externas).
 
 ## Ejemplo canonico (end-to-end imagen → glb)
 
@@ -37,17 +40,24 @@ pipeline ademas marca `stage` (`estimate`/`relief`) en el error.
 # ausentes en el venv de vision. Ver "Fronteras / gotchas".
 import sys
 sys.path.insert(0, "python/functions/datascience")
+from remove_background import remove_background
 from estimate_image_depth import estimate_image_depth
 from depth_to_relief_glb import depth_to_relief_glb
 
 IMG = "apps/img_to_3d_webapp/samples/cats.jpg"
 OUT = "/tmp/cats_relief.glb"
 
+# Paso 0 (opcional pero recomendado): aislar el objeto del fondo. La mask recorta la malla.
+cut = remove_background(IMG)                   # engine='auto' -> rembg -> grabcut -> umbral
+assert cut["status"] == "ok"
+print(cut["engine"], cut["fg_fraction"])       # p.ej. rembg:u2net 0.42
+
 est = estimate_image_depth(IMG)               # device='auto' -> GPU si hay
 assert est["status"] == "ok"
 # est["depth"]: ndarray HxW float32 [0,1] (1=mas cerca)  |  est["image"]: PIL.Image RGB
 
-res = depth_to_relief_glb(est["image"], est["depth"], OUT, z_scale=0.35, max_dim=220)
+# Pasando la mask del paso 0, las caras del fondo se descartan: malla solo del objeto.
+res = depth_to_relief_glb(est["image"], est["depth"], OUT, z_scale=0.35, max_dim=220, mask=cut["mask"])
 assert res["status"] == "ok"
 print(res["glb_path"], res["vertices"], res["faces"])   # /tmp/cats_relief.glb 36300 71832
 # OUT es un glTF binario valido: trimesh.load(OUT) devuelve una Scene texturizada.
@@ -70,15 +80,19 @@ O en una sola llamada con el pipeline (recomendado para fn run / Launcher TUI):
 - **No cubre el render/visualizacion.** Producir el `.glb` es el limite del grupo. Cargarlo y
   subirlo a GPU (OpenGL) en una app C++/ImGui es el grupo **`mesh-3d`** (`gltf_load_mesh_cpp_gfx`
   carga justamente este tipo de `.glb`). img-to-3d **produce**; mesh-3d **consume/renderiza**.
-- **Deps pesadas y de dos mundos.** Requiere `torch`+`transformers` (vision) y `trimesh` (mesh),
-  que hoy viven en el venv de `img_to_3d_webapp`, NO en el venv del registry. Ademas el
-  `datascience.__init__` arrastra deps de scrapers (`bs4`...) que no estan en el venv de vision,
-  por eso el import es **plano** (al modulo) y no via el paquete. `fn run` de estas funciones
-  exige un venv que combine ambos mundos (torch + transformers + trimesh + las deps del dominio
-  datascience). Ver gotchas en cada `.md`.
+- **Deps pesadas y de dos mundos.** Requiere `torch`+`transformers` (vision), `trimesh` (mesh) y,
+  para `remove_background`, `rembg`+`onnxruntime` (segmentacion) y `opencv-python` (GrabCut) —
+  todas opcionales: el umbral de `remove_background` es NumPy puro. Hoy viven en el venv de
+  `img_to_3d_webapp`, NO en el venv del registry. Ademas el `datascience.__init__` arrastra deps
+  de scrapers (`bs4`...) que no estan en el venv de vision, por eso el import es **plano** (al
+  modulo) y no via el paquete. `fn run` de estas funciones exige un venv que combine ambos mundos
+  (torch + transformers + trimesh + rembg/opencv + las deps del dominio datascience). Ver gotchas
+  en cada `.md`.
 
 ## Prerequisitos
 
 - GPU NVIDIA + CUDA recomendada (corre en CPU pero lento). Primera ejecucion descarga los pesos
-  del modelo a `~/.cache/huggingface/` (cientos de MB segun la variante).
-- Paquetes: `torch`, `transformers`, `trimesh`, `pillow`, `numpy`.
+  del modelo de profundidad a `~/.cache/huggingface/` y el de `rembg` (U2Net ~170 MB) a su cache.
+- Paquetes: `torch`, `transformers`, `trimesh`, `pillow`, `numpy`. Para el recorte de fondo de
+  mayor calidad: `rembg` (+`onnxruntime`) y `opencv-python` (ambos opcionales; sin ellos
+  `remove_background` cae al umbral NumPy).

python/functions/browser/scrape_workana_projects.md

@@ -5,7 +5,7 @@ lang: py
 domain: browser
 version: "1.0.0"
 purity: impure
-signature: "def scrape_workana_projects(category: str = 'it-programming', language: str = 'es', extra_query: str = '', pages: int = 1, port: int = 9222, timeout_s: float = 20.0) -> dict"
+signature: "def scrape_workana_projects(category: str = 'it-programming', language: str = 'es', extra_query: str = '', pages: int = 1, port: int = 9334, timeout_s: float = 20.0) -> dict"
 description: "Scraper de proyectos freelance de Workana (https://www.workana.com/jobs) via Chrome DevTools Protocol (CDP). Workana es una SPA Vue: el GET HTTP NO trae los proyectos (0 cards en el HTML inicial), hay que renderizar con JS. Navega con un Chrome remoto, espera a que los cards monten async y extrae cada proyecto con un evaluador JS validado. Pieza 1 de un monitor de captacion de clientes: detecta proyectos freelance nuevos sin abrir el navegador a mano. Shape unificado con el scraper hermano de Upwork. Devuelve un dict con count + lista de proyectos; nunca lanza ni inventa datos."
 tags: [market-intel, recon, flow-replay, browser, cdp, workana, scraper, freelance, spa, vue, captacion]
 uses_functions: ["cdp_open_url_and_wait_py_pipelines", "cdp_eval_py_browser"]
@@ -24,7 +24,7 @@ params:
   - name: pages
     desc: "Numero de paginas de listado a recorrer. Default 1. Cada pagina adicional se navega con &page=N."
   - name: port
-    desc: "Puerto de remote debugging del Chrome a usar. Default 9222 (chromium-personal de produccion). Para un Chrome aislado (smoke / recon sin mezclar sesion personal) apuntar a 9333 (el del browser_mcp)."
+    desc: "Puerto de remote debugging del Chrome a usar. Default 9334 (perfil headless dedicado del scraping, ~/.config/fn_scrape_chrome, que levanta y cierra el wrapper monitor_freelance_projects_headless). NUNCA 9222 por defecto: ese es el chromium-personal del usuario y el scraping no debe abrir pestanas ahi. Para un Chrome aislado interactivo (smoke/recon) tambien sirve 9333 (browser_mcp)."
   - name: timeout_s
     desc: "Timeout (segundos) por pagina, tanto para la navegacion como para el polling de aparicion de cards. Default 20.0."
 output: "dict siempre (nunca lanza). En exito: {status:'ok', source:'workana', count:N, projects:[{...}]}. Cada project_dict con claves EXACTAS: source ('workana'), job_id (slug), url (absoluta), title, budget (str|None), posted (str ej 'Hace 4 horas'), bids (str|None nº propuestas), skills (list[str]), snippet (str), country (str|None), scraped_at (ISO8601 UTC). En error (sin cards tras timeout, Chrome muerto, DOM cambiado): {status:'error', error:<mensaje claro>, source:'workana', projects:[]}. NUNCA devuelve filas falsas."
@@ -40,17 +40,17 @@ file_path: "python/functions/browser/scrape_workana_projects.py"
 # fn run mapea args POSICIONALMENTE a la firma (category language extra_query pages port timeout_s).
 # NO uses flags --category/--language con fn run: el runner los toma como valores posicionales.
 
-# Smoke contra el Chrome aislado del browser_mcp (port 9333, sin login):
-fn run scrape_workana_projects it-programming es "" 1 9333 25
+# Perfil headless dedicado (port 9334, lo levanta el wrapper monitor_freelance_projects_headless):
+fn run scrape_workana_projects it-programming es "" 1 9334 25
 
-# Produccion (chromium-personal, port 9222 por defecto):
-fn run scrape_workana_projects it-programming es "" 1 9222 20
+# Smoke contra el Chrome aislado interactivo del browser_mcp (port 9333, sin login):
+fn run scrape_workana_projects it-programming es "" 1 9333 25
 ```
 
 ```bash
 # Ejecucion directa del modulo SI acepta flags --... (argparse del __main__):
 python/.venv/bin/python3 python/functions/browser/scrape_workana_projects.py \
-  --category it-programming --language es --port 9222
+  --category it-programming --language es --port 9334
 ```
 
 ```python
@@ -78,9 +78,12 @@ porque la pagina es una SPA Vue que monta los cards en runtime.
 
 ## Gotchas
 
-- **Requiere un Chrome con remote debugging vivo en `port`**: 9222 (chromium-personal
-  de produccion, ya activado global) o 9333 (Chrome aislado del browser_mcp). Sin
-  Chrome escuchando devuelve `{status:'error', error:'no hay Chrome en el puerto N...'}` — no lanza.
+- **Requiere un Chrome con remote debugging vivo en `port`**: por defecto 9334 (el
+  perfil headless dedicado del scraping, que levanta/cierra el wrapper
+  `monitor_freelance_projects_headless`). NO usa 9222 (chromium-personal del usuario)
+  por defecto: el scraping no abre pestanas en el navegador diario. 9333 (browser_mcp)
+  sirve para smoke interactivo. Sin Chrome escuchando devuelve
+  `{status:'error', error:'no hay Chrome en el puerto N...'}` — no lanza.
 - **Workana es una SPA Vue: los cards montan ASYNC** tras la hidratacion. El load
   event NO garantiza que esten en el DOM, por eso la funcion hace polling de
   `document.querySelectorAll('div.project-item.js-project').length` hasta >0 o timeout.

python/functions/browser/scrape_workana_projects.py

@@ -198,7 +198,7 @@ def scrape_workana_projects(
     language: str = "es",
     extra_query: str = "",
     pages: int = 1,
-    port: int = 9222,
+    port: int = 9334,
     timeout_s: float = 20.0,
 ) -> dict:
     """Scrapea proyectos freelance de Workana renderizando la SPA via CDP.
@@ -217,9 +217,12 @@ def scrape_workana_projects(
             filtrar por palabra clave (ej. "python", "scraping").
         pages: Numero de paginas de listado a recorrer (1 por defecto). Cada pagina
             adicional se navega con &page=N.
-        port: Puerto de remote debugging del Chrome a usar. Default 9222 (el
-            chromium-personal de produccion). Para un Chrome aislado (smoke / recon
-            sin mezclar sesion personal) apunta a 9333 (el del browser_mcp).
+        port: Puerto de remote debugging del Chrome a usar. Default 9334 (el
+            perfil headless dedicado del scraping, ~/.config/fn_scrape_chrome, que
+            levanta y cierra el wrapper monitor_freelance_projects_headless). NUNCA
+            9222 por defecto: ese es el chromium-personal del usuario y el scraping
+            no debe abrir pestanas ahi. Para un Chrome aislado interactivo (smoke /
+            recon) tambien sirve 9333 (el del browser_mcp).
         timeout_s: Timeout (segundos) por pagina, tanto para la navegacion como para
             el polling de aparicion de cards. Default 20.0.
 
@@ -293,7 +296,7 @@ if __name__ == "__main__":
     parser.add_argument("--language", default="es")
     parser.add_argument("--extra-query", default="")
     parser.add_argument("--pages", type=int, default=1)
-    parser.add_argument("--port", type=int, default=9222)
+    parser.add_argument("--port", type=int, default=9334)
     parser.add_argument("--timeout-s", type=float, default=20.0)
     args = parser.parse_args()
 

python/functions/datascience/depth_to_relief_glb.md

@@ -3,10 +3,10 @@ name: depth_to_relief_glb
 kind: function
 lang: py
 domain: datascience
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
-signature: "def depth_to_relief_glb(image: Image.Image, depth: np.ndarray, out_glb_path: str, z_scale: float = 0.35, max_dim: int = 220) -> dict"
-description: "Construye una malla de relieve (heightmap) texturizada a partir de un mapa de profundidad + la imagen original y la exporta como glTF binario (.glb). El depth se vuelve el eje Z de un grid regular de vertices y la imagen se mapea como textura UV. Paso 2 del flujo img->3D (grupo img-to-3d): consume la salida de estimate_image_depth."
+signature: "def depth_to_relief_glb(image: Image.Image, depth: np.ndarray, out_glb_path: str, z_scale: float = 0.35, max_dim: int = 220, mask: np.ndarray | None = None) -> dict"
+description: "Construye una malla de relieve (heightmap) texturizada a partir de un mapa de profundidad + la imagen original y la exporta como glTF binario (.glb). El depth se vuelve el eje Z de un grid regular de vertices y la imagen se mapea como textura UV. Con mask opcional recorta la malla al objeto (descarta las caras del fondo). Paso 2 del flujo img->3D (grupo img-to-3d): consume la salida de estimate_image_depth y, opcionalmente, la mask de remove_background."
 tags: [img-to-3d, datascience, mesh, glb, gltf, relief, heightmap, trimesh, 3d, texture]
 uses_functions: []
 uses_types: []
@@ -25,7 +25,9 @@ params:
     desc: "Amplitud del relieve como fraccion del lado de la malla (default 0.35). Mayor = relieve mas pronunciado/exagerado."
   - name: max_dim
     desc: "Lado maximo del grid tras downsample bilineal (default 220, ~48k vertices / ~96k caras). Controla resolucion de la malla vs tamano del .glb. Imagenes mayores se reducen; menores se dejan igual."
-output: "dict. Exito: {status:'ok', glb_path:str, vertices:int, faces:int, height:int, width:int}. Error: {status:'error', error:str} (depth con forma invalida, directorio de salida inexistente, fallo de trimesh.export). No lanza."
+  - name: mask
+    desc: "Mascara opcional HxW (0..255, 255=objeto), tipicamente la 'mask' de remove_background. Si se pasa, se reescala al grid (NEAREST), el fondo se aplana a Z=0 y las caras cuyos tres vertices caen en el fondo se descartan: la malla queda recortada al objeto. None (default) = malla del frame completo (relieve incluido el fondo)."
+output: "dict. Exito: {status:'ok', glb_path:str, vertices:int, faces:int, height:int, width:int}. Con mask, 'faces' es menor (solo caras del objeto); 'vertices' no cambia (el grid completo se conserva). Error: {status:'error', error:str} (depth con forma invalida, directorio de salida inexistente, fallo de trimesh.export). No lanza."
 tested: false
 tests: []
 test_file_path: ""
@@ -81,3 +83,14 @@ suavizar el relieve.
 - **Import plano**: importa el modulo directo, NO `from datascience import ...` (el `__init__` del
   paquete arrastra deps de otros dominios ausentes en el venv de vision). Ver misma gotcha en
   `estimate_image_depth`.
+- **mask opcional (v1.1.0)**: pasa la `mask` de `remove_background` para recortar la malla al
+  objeto. Se reescala con NEAREST (sin interpolar, preserva el borde binario), el fondo se aplana
+  a Z=0 y sus caras se eliminan. El nº de `vertices` no baja (el grid completo se conserva para no
+  romper el mapeo UV 1:1); solo baja `faces`. Una mask degenerada (todo objeto) deja la malla
+  intacta; una mask vacia (todo fondo) deja la malla sin caras (glb valido pero vacio).
+
+## Capability growth log
+
+- v1.1.0 (2026-06-21) — anade parametro opcional `mask` para recortar la malla al objeto
+  (descarta las caras del fondo), cerrando la cadena con `remove_background` del grupo img-to-3d.
+  Aditivo: `mask=None` mantiene el comportamiento previo. Fiel al original de `backend/depth.py`.

python/functions/datascience/depth_to_relief_glb.py

@@ -22,6 +22,7 @@ def depth_to_relief_glb(
     out_glb_path: str,
     z_scale: float = 0.35,
     max_dim: int = 220,
+    mask: "np.ndarray | None" = None,
 ) -> dict:
     """
     Construye una malla de relieve texturizada y la exporta como .glb.
@@ -33,6 +34,9 @@ def depth_to_relief_glb(
         z_scale: amplitud del relieve (fracción del lado de la malla). Default 0.35.
         max_dim: lado máximo del grid tras downsample (controla nº de vértices/caras).
             Default 220 (~48k vértices, ~96k caras).
+        mask: máscara opcional HxW (0..255, 255 = objeto), típicamente la "mask" devuelta por
+            remove_background. Si se pasa, el fondo se aplana y las caras cuyos vértices caigan
+            en el fondo se descartan: la malla contiene solo el objeto, sin el plano de fondo.
 
     Devuelve (dict, nunca lanza):
         Éxito: {"status": "ok", "glb_path": out_glb_path, "vertices": int, "faces": int,
@@ -58,6 +62,14 @@ def depth_to_relief_glb(
             depth = np.asarray(depth_img, dtype=np.float32) / 255.0
             H, W = depth.shape
 
+        # Si se pasó máscara (objeto vs fondo), reescalarla al grid ya downsampleado: el fondo
+        # no aporta relieve (se aplana a 0) y luego sus caras se descartan, dejando solo el objeto.
+        fg = None
+        if mask is not None:
+            mask_img = Image.fromarray(np.asarray(mask).astype(np.uint8)).resize((W, H), Image.NEAREST)
+            fg = np.asarray(mask_img) >= 128
+            depth = np.where(fg, depth, 0.0).astype(np.float32)
+
         # Coordenadas del grid: X corrige aspect ratio, Y hacia abajo, Z = profundidad.
         aspect = W / float(H)
         xs = np.linspace(-aspect / 2.0, aspect / 2.0, W, dtype=np.float32)
@@ -79,6 +91,12 @@ def depth_to_relief_glb(
             ]
         )
 
+        # Con máscara: conservar solo las caras cuyos tres vértices son objeto. La malla queda
+        # recortada al objeto, sin el plano de fondo que deformaría el relieve.
+        if fg is not None:
+            keep = fg.ravel()[faces].all(axis=1)
+            faces = faces[keep]
+
         # UV mapeando cada vértice al pixel de la imagen (V invertido para convención glTF).
         u = np.linspace(0.0, 1.0, W, dtype=np.float32)
         v = np.linspace(0.0, 1.0, H, dtype=np.float32)

python/functions/datascience/remove_background.md

@@ -0,0 +1,89 @@
+---
+name: remove_background
+kind: function
+lang: py
+domain: datascience
+version: "1.0.0"
+purity: impure
+signature: "def remove_background(image_path: str, engine: str = 'auto') -> dict"
+description: "Elimina el fondo de una imagen con cascada de motores (rembg/U2Net -> OpenCV GrabCut -> umbral NumPy), compone el objeto sobre fondo gris neutro y devuelve image+mask+engine. Paso de pre-proceso del flujo img->3D (grupo img-to-3d): su mask alimenta depth_to_relief_glb para recortar la malla de relieve al objeto."
+tags: [img-to-3d, datascience, background-removal, segmentation, rembg, grabcut, opencv, computer-vision, mask]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: image_path
+    desc: "Ruta a la imagen de entrada. Cualquier formato que PIL.Image.open abra (jpg, png, webp, RGBA...). Si no existe o no es imagen valida, se devuelve status error. Un PNG RGBA ya recortado se reaprovecha en modo auto (passthrough:alpha)."
+  - name: engine
+    desc: "Motor de segmentacion. 'auto' (default) prueba en cascada rembg:u2net -> opencv:grabcut -> threshold:border y NUNCA falla (cae al umbral NumPy puro sin deps externas). Forzar uno: 'rembg' (red neuronal U2Net, mejor calidad, deps pesadas), 'grabcut' (OpenCV, rectangulo central), 'threshold' (distancia al color medio de los bordes, NumPy puro, objeto centrado). Si se fuerza un motor y no esta disponible/falla o produce mascara degenerada -> status error."
+output: "dict. Exito: {status:'ok', image: PIL.Image RGB del objeto compuesto sobre fondo gris neutro (127,127,127), mask: ndarray HxW uint8 (0..255, 255=objeto), engine: str del motor usado ('rembg:u2net' | 'opencv:grabcut' | 'threshold:border' | 'passthrough:alpha'), height:int, width:int, fg_fraction: float (fraccion de pixeles objeto, redondeada a 4 decimales)}. Error: {status:'error', error:str} (ruta invalida, motor desconocido, motor forzado no disponible/fallido, o ningun motor produjo una mascara valida). No lanza nunca. El demo CLI (__main__) imprime un resumen JSON sin el ndarray ni la imagen y, si se pasa out_dir, guarda rgb.png + mask.png."
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/datascience/remove_background.py"
+source_file: "apps/img_to_3d_webapp/backend/bg_removal.py"
+---
+
+## Ejemplo
+
+```python
+# Requiere un venv con pillow + numpy (rembg/opencv solo si fuerzas esos motores; el umbral es NumPy puro).
+# Import PLANO al modulo: el paquete datascience.__init__ arrastra deps de otros dominios
+# (bs4, duckdb...) que no estan en ese venv. Ver Gotchas.
+import sys
+sys.path.insert(0, "python/functions/datascience")
+from remove_background import remove_background
+
+res = remove_background("apps/img_to_3d_webapp/samples/cats.jpg", engine="auto")
+assert res["status"] == "ok"
+print(res["engine"])                 # p.ej. "rembg:u2net" (o "opencv:grabcut" / "threshold:border")
+print(res["height"], res["width"])   # p.ej. 1024 768
+print(res["mask"].shape, res["mask"].dtype)   # (1024, 768) uint8 (255=objeto)
+assert 0.0 < res["fg_fraction"] < 1.0
+# res["mask"] (ndarray HxW uint8) alimenta depth_to_relief_glb para recortar la malla al objeto.
+# res["image"] es el objeto compuesto sobre gris neutro, listo para estimar profundidad.
+```
+
+Lanzable como demo (imprime resumen JSON, sin serializar el ndarray; guarda PNGs si das out_dir):
+
+```bash
+./fn run remove_background_py_datascience apps/img_to_3d_webapp/samples/cats.jpg auto /tmp/cut
+# {"status": "ok", "engine": "rembg:u2net", "height": 1024, "width": 768,
+#  "fg_fraction": 0.4123, "rgb_path": "/tmp/cut/rgb.png", "mask_path": "/tmp/cut/mask.png"}
+```
+
+## Cuando usarla
+
+Como pre-proceso ANTES de estimar profundidad en el flujo img->3D: aislar el objeto evita que el
+modelo de profundidad estire el fondo plano, y la `mask` permite recortar la malla de relieve al
+objeto (se pasa a `depth_to_relief_glb`). Tambien para segmentacion de primer plano generica
+cuando necesitas separar un objeto de su fondo y componerlo sobre un color neutro (recortes para
+catalogos, datasets, miniaturas).
+
+## Gotchas
+
+- **Impura**: segun el motor carga modelos neuronales y lee disco. `rembg`/`onnxruntime` (~170MB)
+  DESCARGA el modelo U2Net la primera vez a su cache (`~/.u2net/`), requiere red en esa primera
+  carga; `opencv-python` para GrabCut; el umbral (`threshold:border`) es NumPy puro sin deps externas.
+- **Estado de proceso**: `_REMBG_SESSION` cachea la sesion rembg a nivel de modulo para no recargar
+  los pesos en cada llamada. Es estado mutable compartido del proceso y ocupa RAM hasta que el
+  interprete muere.
+- **engine='auto' nunca lanza**: prueba rembg -> grabcut -> threshold y siempre cae al umbral NumPy
+  puro si los anteriores no estan disponibles o fallan. Forzar un motor concreto SI puede devolver
+  status error (motor no instalado, fallo, o mascara degenerada).
+- **Mascara degenerada**: si la fraccion de objeto resulta `< 0.01` o `> 0.995` la mascara se
+  descarta (casi todo fondo o casi todo objeto) y en modo auto se prueba el siguiente motor.
+- **threshold:border es de baja calidad**: asume objeto centrado con los bordes de la imagen siendo
+  fondo (calcula la distancia al color medio de los bordes). Es el fallback de ultimo recurso.
+- **passthrough:alpha**: si la imagen ya viene recortada (PNG RGBA con alfa por debajo de 128) se
+  reutiliza su canal alfa como mascara, SOLO en modo auto. Si fuerzas un motor concreto se respeta
+  esa eleccion e ignora el alfa existente.
+- **Import plano**: importa el modulo directo (`sys.path` a `python/functions/datascience` +
+  `from remove_background import remove_background`), NO `from datascience import ...`. El
+  `datascience.__init__` carga todo el dominio (scrapers con bs4, duckdb...) con deps ajenas a esta
+  funcion que romperian el import del paquete en el venv de vision.
+- Nunca lanza: errores (ruta invalida, motor forzado no disponible, OOM) vuelven como
+  `{status:'error', error:str}`.

python/functions/datascience/remove_background.py

@@ -0,0 +1,213 @@
+"""
+Eliminación de fondo de una imagen con cascada de motores (rembg -> GrabCut -> umbral).
+
+Función del registry (grupo de capacidad `img-to-3d`, dominio `datascience`). Promovida desde
+la app `img_to_3d_webapp` (backend/bg_removal.py) para que cualquier artefacto pueda aislar el
+objeto de primer plano sin reimplementar la cascada de segmentación ni la composición sobre fondo
+neutro.
+
+Impura: carga modelos neuronales (rembg/U2Net), usa GPU/CPU vía onnxruntime, lee disco y mantiene
+una caché de sesión rembg a nivel de proceso para no recargar los pesos en cada llamada. Las deps
+pesadas (rembg, opencv) se importan dentro de los helpers (lazy) para que el módulo se pueda
+importar sin ellas; el motor de umbral es NumPy puro sin deps externas.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image
+
+# Fondo gris neutro sobre el que se compone el objeto recortado.
+NEUTRAL_BG = (127, 127, 127)
+# Umbral de alfa para considerar un PNG RGBA "ya recortado" (passthrough).
+_ALPHA_THRESH = 128
+# Sesión rembg cacheada a nivel de proceso (estado mutable: ver .md "Gotchas").
+_REMBG_SESSION = None
+
+
+def _existing_alpha_mask(image):
+    """Devuelve el canal alfa como máscara HxW uint8 si la imagen ya viene recortada, si no None."""
+    if image.mode in ("RGBA", "LA") or (image.mode == "P" and "transparency" in image.info):
+        alpha = np.asarray(image.convert("RGBA"))[:, :, 3]
+        if alpha.min() < _ALPHA_THRESH:
+            return alpha
+    return None
+
+
+def _composite_over_neutral(image_rgb, mask):
+    """Compone la imagen RGB sobre el fondo gris neutro usando la máscara como alfa."""
+    rgb = np.asarray(image_rgb.convert("RGB"), dtype=np.float32)
+    alpha = (mask.astype(np.float32) / 255.0)[:, :, None]
+    bg = np.empty_like(rgb)
+    bg[:] = NEUTRAL_BG
+    out = rgb * alpha + bg * (1.0 - alpha)
+    return Image.fromarray(out.clip(0, 255).astype(np.uint8), mode="RGB")
+
+
+def _remove_with_rembg(image):
+    """Segmenta con rembg (modelo U2Net). Devuelve (mask HxW uint8, engine_str)."""
+    global _REMBG_SESSION
+    from rembg import new_session, remove
+
+    if _REMBG_SESSION is None:
+        _REMBG_SESSION = new_session("u2net")
+    cut = remove(image.convert("RGB"), session=_REMBG_SESSION)
+    mask = np.asarray(cut.convert("RGBA"))[:, :, 3]
+    return mask, "rembg:u2net"
+
+
+def _remove_with_grabcut(image):
+    """Segmenta con OpenCV GrabCut (rectángulo central). Devuelve (mask HxW uint8, engine_str)."""
+    import cv2
+
+    rgb = np.asarray(image.convert("RGB"))
+    h, w = rgb.shape[:2]
+    bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
+    gc_mask = np.zeros((h, w), np.uint8)
+    bgd_model = np.zeros((1, 65), np.float64)
+    fgd_model = np.zeros((1, 65), np.float64)
+    margin_x, margin_y = int(0.08 * w), int(0.08 * h)
+    rect = (margin_x, margin_y, max(1, w - 2 * margin_x), max(1, h - 2 * margin_y))
+    cv2.grabCut(bgr, gc_mask, rect, bgd_model, fgd_model, 5, cv2.GC_INIT_WITH_RECT)
+    fg = np.where((gc_mask == cv2.GC_FGD) | (gc_mask == cv2.GC_PR_FGD), 255, 0).astype(np.uint8)
+    return fg, "opencv:grabcut"
+
+
+def _remove_with_threshold(image):
+    """Segmenta por distancia al color medio de los bordes (NumPy puro). Devuelve (mask, engine_str)."""
+    rgb = np.asarray(image.convert("RGB"), dtype=np.float32)
+    h, w = rgb.shape[:2]
+    border = np.concatenate([rgb[0, :, :], rgb[-1, :, :], rgb[:, 0, :], rgb[:, -1, :]], axis=0)
+    bg_color = border.mean(axis=0)
+    dist = np.linalg.norm(rgb - bg_color, axis=2)
+    thresh = max(30.0, float(dist.mean()))
+    fg = (dist > thresh).astype(np.uint8) * 255
+    return fg, "threshold:border"
+
+
+def remove_background(image_path: str, engine: str = "auto") -> dict:
+    """
+    Elimina el fondo de una imagen y compone el objeto sobre un fondo gris neutro.
+
+    Parámetros:
+        image_path: ruta a la imagen de entrada (cualquier formato que PIL abra).
+        engine: "auto" (default) prueba rembg -> GrabCut -> umbral en cascada y NUNCA falla
+            (cae al umbral NumPy puro sin deps externas); también admite forzar un motor concreto:
+            "rembg", "grabcut" o "threshold". Si se fuerza un motor y no está disponible/falla,
+            o la máscara resulta degenerada, se devuelve status error.
+
+    Devuelve (dict, nunca lanza):
+        Éxito: {"status": "ok", "image": PIL.Image RGB del objeto compuesto sobre gris neutro,
+                "mask": ndarray HxW uint8 (0..255, 255=objeto), "engine": str del motor usado
+                ("rembg:u2net" | "opencv:grabcut" | "threshold:border" | "passthrough:alpha"),
+                "height": int, "width": int, "fg_fraction": float (fracción de píxeles objeto,
+                redondeada a 4 decimales)}.
+        Error: {"status": "error", "error": str} (ruta inválida, motor desconocido, motor forzado
+                no disponible/fallido, o ningún motor produjo una máscara válida).
+    """
+    try:
+        image = Image.open(image_path)
+
+        # Passthrough: si la imagen ya viene recortada (PNG RGBA con alfa), reutiliza su alfa.
+        # Solo en modo auto; si se fuerza un motor concreto se respeta esa elección.
+        if engine == "auto":
+            existing = _existing_alpha_mask(image)
+            if existing is not None:
+                composed = _composite_over_neutral(image, existing)
+                frac = float((existing >= 128).mean())
+                h, w = existing.shape[:2]
+                return {
+                    "status": "ok",
+                    "image": composed,
+                    "mask": existing,
+                    "engine": "passthrough:alpha",
+                    "height": int(h),
+                    "width": int(w),
+                    "fg_fraction": round(frac, 4),
+                }
+
+        # Construir la lista de motores a probar según el engine pedido.
+        if engine == "auto":
+            attempts = [_remove_with_rembg, _remove_with_grabcut, _remove_with_threshold]
+        elif engine == "rembg":
+            attempts = [_remove_with_rembg]
+        elif engine == "grabcut":
+            attempts = [_remove_with_grabcut]
+        elif engine == "threshold":
+            attempts = [_remove_with_threshold]
+        else:
+            attempts = []
+
+        if not attempts:
+            return {"status": "error", "error": f"Motor desconocido: {engine!r}"}
+
+        last_exc = None
+        for attempt in attempts:
+            try:
+                mask, used = attempt(image)
+            except Exception as e:  # noqa: BLE001
+                last_exc = e
+                continue
+
+            # Rechazar máscaras degeneradas (casi todo fondo o casi todo objeto).
+            frac = float((mask >= 128).mean())
+            if frac < 0.01 or frac > 0.995:
+                last_exc = f"mascara degenerada (fg_fraction={round(frac, 4)}) con {used}"
+                continue
+
+            composed = _composite_over_neutral(image, mask)
+            h, w = mask.shape[:2]
+            return {
+                "status": "ok",
+                "image": composed,
+                "mask": mask,
+                "engine": used,
+                "height": int(h),
+                "width": int(w),
+                "fg_fraction": round(frac, 4),
+            }
+
+        return {
+            "status": "error",
+            "error": f"No se pudo eliminar el fondo con engine={engine!r}: {last_exc}",
+        }
+    except Exception as e:  # noqa: BLE001
+        return {"status": "error", "error": str(e)}
+
+
+if __name__ == "__main__":
+    # Demo runner para `fn run remove_background_py_datascience <image_path> [engine] [out_dir]`.
+    # Imprime un resumen JSON-serializable (el ndarray y la PIL.Image no se serializan).
+    import json
+    import os
+    import sys
+
+    if len(sys.argv) < 2:
+        print(json.dumps({"status": "error", "error": "uso: <image_path> [engine] [out_dir]"}))
+        sys.exit(1)
+
+    path = sys.argv[1]
+    eng = sys.argv[2] if len(sys.argv) > 2 else "auto"
+    out_dir = sys.argv[3] if len(sys.argv) > 3 else None
+
+    res = remove_background(path, engine=eng)
+    if res["status"] == "ok":
+        summary = {
+            "status": "ok",
+            "engine": res["engine"],
+            "height": res["height"],
+            "width": res["width"],
+            "fg_fraction": res["fg_fraction"],
+        }
+        if out_dir:
+            os.makedirs(out_dir, exist_ok=True)
+            rgb_path = os.path.join(out_dir, "rgb.png")
+            mask_path = os.path.join(out_dir, "mask.png")
+            res["image"].save(rgb_path)
+            Image.fromarray(res["mask"]).save(mask_path)
+            summary["rgb_path"] = rgb_path
+            summary["mask_path"] = mask_path
+        print(json.dumps(summary))
+    else:
+        print(json.dumps(res))
+        sys.exit(1)

python/functions/pipelines/monitor_freelance_projects.md

@@ -5,7 +5,7 @@ lang: py
 domain: pipelines
 version: "1.0.0"
 purity: impure
-signature: "def monitor_freelance_projects(category: str = 'it-programming', language: str = 'es', query: str = '', pages: int = 1, include_upwork: bool = False, upwork_query: str = 'custom software', duckdb_path: str = '', xlsx_path: str = '', port: int = 9222, timeout_s: float = 25.0) -> dict"
+signature: "def monitor_freelance_projects(category: str = 'it-programming', language: str = 'es', query: str = '', pages: int = 1, include_upwork: bool = False, upwork_query: str = 'custom software', duckdb_path: str = '', xlsx_path: str = '', port: int = 9334, timeout_s: float = 25.0) -> dict"
 description: "Monitor de captacion de clientes freelance: scrapea proyectos nuevos de Workana (+ Upwork opcional) via CDP, los persiste en DuckDB con dedup por url, marca los de software a medida y exporta a Excel (hojas Nuevos y Todos)."
 tags: [market-intel, recon, launcher, pipelines, freelance, workana, upwork, duckdb, excel]
 uses_functions:
@@ -42,7 +42,7 @@ params:
   - name: xlsx_path
     desc: "Ruta del .xlsx de salida. Si vacia, usa ~/.fn_freelance/freelance_projects.xlsx (crea el directorio). Se sobrescribe en cada corrida."
   - name: port
-    desc: "Puerto de remote debugging del Chrome que usan los scrapers (CDP). Default 9222 (chromium-personal logueado). Usa 9333 para el Chrome aislado del browser_mcp."
+    desc: "Puerto de remote debugging del Chrome que usan los scrapers (CDP). Default 9334 (perfil headless dedicado del scraping). NUNCA 9222 por defecto: ese es el chromium-personal del usuario. Para la corrida programada usa el wrapper monitor_freelance_projects_headless (levanta el Chrome headless en 9334 y lo cierra). 9333 = Chrome aislado interactivo del browser_mcp."
   - name: timeout_s
     desc: "Timeout en segundos por pagina para los scrapers (navegacion + espera de cards). Default 25.0."
 output: "dict. En exito: {status:'ok', new_count:int (proyectos nuevos de esta corrida), total_in_db:int, new_projects:[...], xlsx_path:'<abs>', duckdb_path:'<abs>', sources:{workana:{count,status}, upwork:{count,status}|'skipped'}}. En error (sin lanzar): {status:'error', error:str, sources:{...}}."
@@ -51,11 +51,14 @@ output: "dict. En exito: {status:'ok', new_count:int (proyectos nuevos de esta c
 ## Ejemplo
 
 ```bash
-# Requiere un Chrome con remote debugging vivo en el puerto indicado.
-# Produccion (chromium-personal logueado, port 9222) con los paths por defecto:
+# Para la corrida programada usa el wrapper headless (levanta Chrome en 9334 y lo
+# cierra): fn run monitor_freelance_projects_headless. Este pipeline asume que YA hay
+# un Chrome con remote debugging vivo en `port`.
+
+# Contra el perfil headless dedicado (port 9334 por defecto), paths por defecto:
 fn run monitor_freelance_projects
 
-# Probar contra el Chrome aislado del browser_mcp (port 9333) con paths efimeros:
+# Probar contra el Chrome aislado interactivo del browser_mcp (port 9333), paths efimeros:
 fn run monitor_freelance_projects --port 9333 \
   --duckdb-path /tmp/freelance.duckdb --xlsx-path /tmp/freelance.xlsx
 ```
@@ -88,8 +91,10 @@ oportunidades nuevas.
 
 - **Requiere un Chrome con CDP vivo en `port`**: los scrapers (Workana/Upwork son
   SPAs) renderizan via Chrome DevTools Protocol. Sin remote debugging escuchando en
-  ese puerto el pipeline devuelve `status:'error'` con el detalle. Produccion = 9222
-  (chromium-personal logueado); Chrome aislado = 9333 (browser_mcp).
+  ese puerto el pipeline devuelve `status:'error'` con el detalle. Por defecto 9334
+  (perfil headless dedicado, lo levanta/cierra `monitor_freelance_projects_headless`).
+  NO usa 9222 (chromium-personal del usuario) por defecto. 9333 = browser_mcp para
+  smoke interactivo.
 - **Upwork OFF por defecto**: sus selectores no estan validados en vivo (sin sesion
   Upwork). Con `include_upwork=True`, si Upwork devuelve `status:'error'` el pipeline
   loguea un WARN a stderr y sigue solo con Workana — nunca aborta por Upwork.

python/functions/pipelines/monitor_freelance_projects.py

@@ -226,7 +226,7 @@ def monitor_freelance_projects(
     upwork_query: str = "custom software",
     duckdb_path: str = "",
     xlsx_path: str = "",
-    port: int = 9222,
+    port: int = 9334,
     timeout_s: float = 25.0,
 ) -> dict:
     """Detecta proyectos freelance nuevos, los persiste con dedup y exporta a Excel.
@@ -262,7 +262,10 @@ def monitor_freelance_projects(
         xlsx_path: ruta del .xlsx de salida. Si "", usa
             ~/.fn_freelance/freelance_projects.xlsx (creando el directorio).
         port: puerto de remote debugging del Chrome a usar por los scrapers.
-            Default 9222 (chromium-personal logueado).
+            Default 9334 (perfil headless dedicado del scraping). NUNCA 9222 por
+            defecto: ese es el chromium-personal del usuario. Para la corrida
+            programada usa el wrapper monitor_freelance_projects_headless, que
+            levanta el Chrome headless en 9334 y lo cierra al terminar.
         timeout_s: timeout en segundos por pagina para los scrapers. Default 25.0.
 
     Returns:
@@ -454,7 +457,7 @@ def main() -> int:
     ap.add_argument("--upwork-query", default="custom software")
     ap.add_argument("--duckdb-path", default="")
     ap.add_argument("--xlsx-path", default="")
-    ap.add_argument("--port", type=int, default=9222)
+    ap.add_argument("--port", type=int, default=9334)
     ap.add_argument("--timeout-s", type=float, default=25.0)
     args = ap.parse_args()
 

python/functions/pipelines/monitor_freelance_projects_headless.md

@@ -0,0 +1,92 @@
+---
+name: monitor_freelance_projects_headless
+kind: pipeline
+lang: py
+domain: pipelines
+version: "1.0.0"
+purity: impure
+signature: "def monitor_freelance_projects_headless(category: str = 'it-programming', language: str = 'es', query: str = '', pages: int = 1, include_upwork: bool = False, upwork_query: str = 'custom software', duckdb_path: str = '', xlsx_path: str = '', port: int = 9334, profile_dir: str = '', timeout_s: float = 25.0) -> dict"
+description: "Monitor de captacion de clientes freelance (Workana + Upwork -> DuckDB + Excel) en un Chrome headless AISLADO con perfil dedicado, lanzandolo y cerrandolo en cada corrida. Evita abrir pestanas en el navegador diario del usuario (chromium-personal, CDP 9222). Wrapper de monitor_freelance_projects que solo gestiona el ciclo de vida del navegador. Proyecto captacion_clientes."
+tags: [market-intel, captacion_clientes, headless, cdp, freelance, scraper, recon]
+uses_functions: [monitor_freelance_projects_py_pipelines]
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/pipelines/monitor_freelance_projects_headless.py"
+params:
+  - name: category
+    desc: "Categoria de Workana (?category=). Default 'it-programming'."
+  - name: language
+    desc: "Idioma de los proyectos de Workana (?language=). Default 'es'."
+  - name: query
+    desc: "Query libre aplicada a ambas fuentes (extra_query en Workana; sobrescribe upwork_query en Upwork si no esta vacia). Default vacio."
+  - name: pages
+    desc: "Numero de paginas de listado a recorrer por fuente. Default 1."
+  - name: include_upwork
+    desc: "Si True, scrapea Upwork ademas de Workana (tolerante a fallo). Default False (sus selectores no estan validados en vivo y requiere login)."
+  - name: upwork_query
+    desc: "Query para Upwork cuando include_upwork. Default 'custom software'. `query` lo sobrescribe si se pasa."
+  - name: duckdb_path
+    desc: "Ruta del archivo DuckDB de persistencia con dedup por url. Vacio -> ~/.fn_freelance/freelance.duckdb (se crea el directorio)."
+  - name: xlsx_path
+    desc: "Ruta del .xlsx de salida (hojas 'Nuevos' y 'Todos'). Vacio -> ~/.fn_freelance/freelance_projects.xlsx (se crea el directorio)."
+  - name: port
+    desc: "Puerto de remote-debugging del Chrome headless aislado que este wrapper lanza y al que apunta el monitor. Default 9334 (NO el 9222 del navegador diario)."
+  - name: profile_dir
+    desc: "user-data-dir dedicado del Chrome aislado. Vacio -> ~/.config/fn_scrape_chrome (se crea si no existe). Perfil persistente entre corridas."
+  - name: timeout_s
+    desc: "Timeout en segundos por pagina para los scrapers. Default 25.0."
+output: "dict que SIEMPRE incluye {status: 'ok'|'error', port, profile_dir, launched: bool, closed: bool} y, en exito, las claves del resultado de monitor_freelance_projects (new_count, total_in_db, new_projects, xlsx_path, duckdb_path, sources). En error sin lanzar incluye `error`. El finally cierra siempre la instancia que lanzo (closed=True); si reutiliza un CDP ya vivo en el puerto, launched=False y closed=False (no cierra lo ajeno). Nunca lanza excepcion al caller."
+---
+
+## Ejemplo
+
+```bash
+# Monitor freelance en Chrome headless aislado (lanzar -> scrape -> cerrar).
+# OJO: fn run pasa los args POSICIONALES, en el orden de la firma:
+#   category, language, query, pages, ...
+fn run monitor_freelance_projects_headless it-programming es "" 1
+# -> {"status":"ok","port":9334,"profile_dir":"/home/<user>/.config/fn_scrape_chrome",
+#     "launched":true,"closed":true,"new_count":N,"total_in_db":M,
+#     "xlsx_path":"/home/<user>/.fn_freelance/freelance_projects.xlsx",
+#     "duckdb_path":"/home/<user>/.fn_freelance/freelance.duckdb",
+#     "sources":{"workana":{"count":N,"status":"ok"},"upwork":"skipped"}}
+```
+
+Invocacion directa del modulo (acepta flags `--category`/`--language`/`--pages`/...):
+
+```bash
+python/.venv/bin/python3 python/functions/pipelines/monitor_freelance_projects_headless.py \
+    --category it-programming --language es --pages 2
+```
+
+## Cuando usarla
+
+Usala para la ingesta diaria/programada (dag_engine) del monitor de captacion freelance del
+proyecto captacion_clientes cuando NO quieras que el scraping abra pestanas en tu navegador
+diario. Levanta su propio Chromium headless con perfil dedicado (puerto 9334) y lo cierra al
+terminar — el navegador personal (`chromium-personal`, CDP 9222) queda intacto. Es el
+reemplazo de llamar `monitor_freelance_projects` con `--port 9222` a pelo (que usaria el
+navegador interactivo logueado).
+
+## Gotchas
+
+- **Impura: lanza y mata Chrome.** Arranca un Chromium headless via `systemd-run --user`
+  (scope `fnscrape_dag_<port>`); si `systemd-run` no esta, cae a `subprocess.Popen` con grupo
+  de proceso propio. Lanzarlo con `exec` directo desde el agente da **exit-144** — por eso
+  systemd-run. En el `finally` siempre cierra lo que lanzo (`systemctl --user stop` del
+  scope/service + respaldo `pkill -f "user-data-dir=<perfil>"`) y verifica con un GET final
+  que el puerto ya no responde (`closed`).
+- **Perfil dedicado persistente.** `~/.config/fn_scrape_chrome` sobrevive entre corridas
+  (cookies/cache del scraping). No se borra. Borralo a mano si quieres sesion limpia.
+- **Reutiliza CDP existente.** Si el puerto ya responde al arrancar, NO lanza otro Chrome:
+  reutiliza el vivo y `launched=False` + `closed=False` (no cierra algo que no abrio).
+- **Workana puede cambiar selectores o bloquear.** Workana es una SPA Vue: si cambia sus
+  selectores o aplica anti-bot, el monitor devuelve `status: error` (sin inventar datos),
+  pero el Chrome aislado **igual se cierra** en el finally. Upwork esta en `skipped` por
+  defecto (selectores no validados en vivo + login).

python/functions/pipelines/monitor_freelance_projects_headless.py

@@ -0,0 +1,335 @@
+"""monitor_freelance_projects_headless — monitor freelance en un Chrome headless aislado.
+
+Wrapper de `monitor_freelance_projects` (pipeline del proyecto captacion_clientes) que lanza
+un Chromium **headless** con un **perfil dedicado** y un puerto de remote-debugging propio,
+corre el monitor de proyectos freelance apuntando a ESE puerto, y **cierra la instancia al
+terminar** — siempre, incluso si el scraping falla.
+
+Motivo: el scraping NO debe abrir pestañas en el navegador diario del usuario
+(`chromium-personal`, puerto 9222). Norma: perfil dedicado + headless + cerrar al terminar.
+
+El Chrome se lanza vía `systemd-run --user` (un scope transitorio), porque lanzar chromium
+con un `exec`/`Popen` directo desde el proceso del agente da exit-144 cuando hereda el grupo
+de control del agente. Si `systemd-run` no está disponible, se cae a `subprocess.Popen` en un
+grupo de proceso nuevo (`start_new_session=True`).
+
+A diferencia de `ingest_market_trends_headless` (que itera fuentes CDP), este wrapper llama
+UNA sola vez al pipeline `monitor_freelance_projects`, pasándole el puerto del Chrome aislado.
+El pipeline scrapea Workana (y opcionalmente Upwork) por CDP, deduplica en DuckDB y exporta a
+Excel; este wrapper solo gestiona el ciclo de vida del navegador.
+"""
+
+import argparse
+import json
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+import urllib.request
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+sys.path.insert(0, os.path.join(ROOT, "python", "functions"))
+
+from pipelines.monitor_freelance_projects import monitor_freelance_projects  # noqa: E402
+
+DEFAULT_PORT = 9334
+DEFAULT_PROFILE = "~/.config/fn_scrape_chrome"
+
+# Candidatos de binario chromium/chrome. shutil.which primero (respeta PATH), luego
+# rutas absolutas conocidas del sistema (el `chromium` del usuario suele ser un alias de
+# shell no visible a subprocess, y el binario real vive en /usr/lib/chromium/chromium).
+_CHROME_NAMES = ("chromium", "chromium-browser", "google-chrome", "google-chrome-stable")
+_CHROME_ABS = (
+    "/usr/bin/chromium",
+    "/usr/lib/chromium/chromium",
+    "/usr/bin/chromium-browser",
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/snap/bin/chromium",
+)
+
+
+def _find_chrome() -> str | None:
+    """Devuelve la ruta a un binario chromium/chrome ejecutable, o None."""
+    for name in _CHROME_NAMES:
+        path = shutil.which(name)
+        if path:
+            return path
+    for path in _CHROME_ABS:
+        if os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+    return None
+
+
+def _cdp_alive(port: int, timeout: float = 1.0) -> bool:
+    """True si el endpoint CDP responde en 127.0.0.1:<port>/json/version."""
+    url = f"http://127.0.0.1:{port}/json/version"
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            return 200 <= resp.status < 300
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _wait_cdp(port: int, deadline_s: float = 12.0) -> bool:
+    """Espera a que el CDP responda hasta `deadline_s` (sondea cada 0.5s)."""
+    end = time.time() + deadline_s
+    while time.time() < end:
+        if _cdp_alive(port):
+            return True
+        time.sleep(0.5)
+    return False
+
+
+def _chrome_args(chrome_bin: str, port: int, profile_dir: str) -> list[str]:
+    return [
+        chrome_bin,
+        "--headless=new",
+        "--disable-gpu",
+        f"--remote-debugging-port={port}",
+        f"--user-data-dir={profile_dir}",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--remote-allow-origins=*",
+        "--disable-extensions",
+    ]
+
+
+def _launch(chrome_bin: str, port: int, profile_dir: str) -> tuple[str, int | None]:
+    """Lanza Chrome headless aislado. Devuelve (mecanismo, pid).
+
+    mecanismo: 'systemd' (scope transitorio) o 'popen' (grupo de proceso propio).
+    pid: solo poblado en modo 'popen' (para poder matar el grupo en el cierre).
+    """
+    unit = f"fnscrape_dag_{port}"
+    systemd_run = shutil.which("systemd-run")
+    if systemd_run:
+        cmd = [
+            systemd_run, "--user", "--quiet", "--collect", f"--unit={unit}",
+            *_chrome_args(chrome_bin, port, profile_dir),
+        ]
+        try:
+            subprocess.run(cmd, check=True, timeout=15,
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            return "systemd", None
+        except Exception:  # noqa: BLE001
+            # systemd-run falló (sin --user bus, etc.) -> fallback a Popen.
+            pass
+
+    proc = subprocess.Popen(
+        _chrome_args(chrome_bin, port, profile_dir),
+        start_new_session=True,
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+    )
+    return "popen", proc.pid
+
+
+def _close(mechanism: str, pid: int | None, port: int, profile_dir: str) -> bool:
+    """Cierra la instancia que ESTE wrapper lanzó. Devuelve True si el puerto ya no responde."""
+    unit = f"fnscrape_dag_{port}"
+    if mechanism == "systemd":
+        systemctl = shutil.which("systemctl")
+        if systemctl:
+            for kind in (f"{unit}.scope", f"{unit}.service"):
+                try:
+                    subprocess.run([systemctl, "--user", "stop", kind],
+                                   timeout=10, stdout=subprocess.DEVNULL,
+                                   stderr=subprocess.DEVNULL)
+                except Exception:  # noqa: BLE001
+                    pass
+    elif mechanism == "popen" and pid is not None:
+        try:
+            pgid = os.getpgid(pid)
+            os.killpg(pgid, signal.SIGTERM)
+            for _ in range(20):  # hasta ~2s para salida limpia
+                time.sleep(0.1)
+                if not _cdp_alive(port):
+                    break
+            if _cdp_alive(port):
+                os.killpg(pgid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        except Exception:  # noqa: BLE001
+            pass
+
+    # Respaldo: matar cualquier chromium colgado de este perfil concreto.
+    pkill = shutil.which("pkill")
+    if pkill:
+        try:
+            subprocess.run([pkill, "-f", f"user-data-dir={profile_dir}"],
+                           timeout=10, stdout=subprocess.DEVNULL,
+                           stderr=subprocess.DEVNULL)
+        except Exception:  # noqa: BLE001
+            pass
+
+    # Esperar a que el puerto deje de responder (cierre asíncrono del cgroup).
+    for _ in range(20):  # hasta ~2s
+        if not _cdp_alive(port):
+            return True
+        time.sleep(0.1)
+    return not _cdp_alive(port)
+
+
+def monitor_freelance_projects_headless(
+    category: str = "it-programming",
+    language: str = "es",
+    query: str = "",
+    pages: int = 1,
+    include_upwork: bool = False,
+    upwork_query: str = "custom software",
+    duckdb_path: str = "",
+    xlsx_path: str = "",
+    port: int = DEFAULT_PORT,
+    profile_dir: str = "",
+    timeout_s: float = 25.0,
+) -> dict:
+    """Lanza un Chrome headless aislado, corre el monitor freelance y lo cierra al terminar.
+
+    Pipeline IMPURO: arranca su propio Chromium headless con perfil dedicado, ejecuta
+    `monitor_freelance_projects` apuntando a ESE puerto, y en el `finally` cierra la
+    instancia que lanzó. Nunca abre pestañas en el navegador diario del usuario
+    (`chromium-personal`, CDP 9222). NUNCA lanza excepción al caller: cualquier fallo se
+    refleja en `status`/`error` y el navegador se cierra igual.
+
+    Args:
+        category: categoría de Workana (?category=). Default "it-programming".
+        language: idioma de los proyectos de Workana (?language=). Default "es".
+        query: query libre aplicada a ambas fuentes (extra_query en Workana; sobrescribe
+            upwork_query en Upwork si no está vacía).
+        pages: número de páginas de listado a recorrer por fuente. Default 1.
+        include_upwork: si True, scrapea Upwork además de Workana. Default False.
+        upwork_query: query para Upwork cuando include_upwork. Default "custom software".
+        duckdb_path: ruta del archivo DuckDB. Vacío -> ~/.fn_freelance/freelance.duckdb.
+        xlsx_path: ruta del .xlsx de salida. Vacío -> ~/.fn_freelance/freelance_projects.xlsx.
+        port: puerto de remote-debugging del Chrome headless aislado. Default 9334.
+        profile_dir: user-data-dir dedicado. Vacío -> ~/.config/fn_scrape_chrome.
+        timeout_s: timeout en segundos por página para los scrapers. Default 25.0.
+
+    Returns:
+        dict que SIEMPRE incluye {status, port, profile_dir, launched, closed} y, en éxito,
+        las claves del resultado de `monitor_freelance_projects` (new_count, total_in_db,
+        new_projects, xlsx_path, duckdb_path, sources, ...). En error sin lanzar incluye
+        `error`. El finally cierra siempre la instancia que lanzó (no la que reutiliza).
+    """
+    if not profile_dir:
+        profile_dir = os.path.expanduser(DEFAULT_PROFILE)
+    profile_dir = os.path.abspath(os.path.expanduser(profile_dir))
+    os.makedirs(profile_dir, exist_ok=True)
+
+    out: dict = {
+        "status": "error",
+        "port": port,
+        "profile_dir": profile_dir,
+        "launched": False,
+        "closed": False,
+    }
+
+    mechanism = ""
+    pid: int | None = None
+    reuse = False
+
+    # 1) Si ya hay un CDP vivo en el puerto, reutilizarlo (no lo cerraremos).
+    if _cdp_alive(port):
+        reuse = True
+    else:
+        chrome_bin = _find_chrome()
+        if not chrome_bin:
+            out["error"] = (
+                "no se encontró binario chromium/chrome "
+                f"(probados: {', '.join(_CHROME_NAMES)} + rutas absolutas conocidas)"
+            )
+            return out
+        try:
+            mechanism, pid = _launch(chrome_bin, port, profile_dir)
+            out["launched"] = True
+        except Exception as exc:  # noqa: BLE001
+            out["error"] = f"fallo al lanzar chromium: {exc}"
+            return out
+
+        # 2) Esperar a que el CDP responda.
+        if not _wait_cdp(port, deadline_s=12.0):
+            out["error"] = f"el CDP no respondió en 127.0.0.1:{port} tras 12s"
+            out["closed"] = _close(mechanism, pid, port, profile_dir)
+            return out
+
+    # 3) Correr el monitor freelance contra el puerto del Chrome aislado.
+    try:
+        res = monitor_freelance_projects(
+            category=category,
+            language=language,
+            query=query,
+            pages=pages,
+            include_upwork=include_upwork,
+            upwork_query=upwork_query,
+            duckdb_path=duckdb_path,
+            xlsx_path=xlsx_path,
+            port=port,
+            timeout_s=timeout_s,
+        )
+        if isinstance(res, dict):
+            # Mezclar el resultado del monitor; las claves de lifecycle (status, port,
+            # profile_dir, launched, closed) se restauran/recalculan abajo.
+            out.update(res)
+        else:
+            out["error"] = f"monitor_freelance_projects devolvió un tipo inesperado: {type(res).__name__}"
+            out["status"] = "error"
+    except Exception as exc:  # noqa: BLE001 — el wrapper nunca lanza al caller
+        out["error"] = f"{type(exc).__name__}: {exc}"
+        out["status"] = "error"
+    finally:
+        # 4) Restaurar las claves de lifecycle que `out.update(res)` pudo pisar.
+        out["port"] = port
+        out["profile_dir"] = profile_dir
+        out["launched"] = bool(out.get("launched"))
+        # 5) Cerrar SIEMPRE lo que nosotros lanzamos (no si reutilizamos uno ajeno).
+        if out["launched"] and not reuse:
+            out["closed"] = _close(mechanism, pid, port, profile_dir)
+        else:
+            out["closed"] = False
+
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description=(
+            "Monitor de captacion freelance (Workana + Upwork -> DuckDB + Excel) en un "
+            "Chrome headless AISLADO con perfil dedicado."
+        )
+    )
+    ap.add_argument("--category", default="it-programming")
+    ap.add_argument("--language", default="es")
+    ap.add_argument("--query", default="")
+    ap.add_argument("--pages", type=int, default=1)
+    ap.add_argument("--include-upwork", action="store_true")
+    ap.add_argument("--upwork-query", default="custom software")
+    ap.add_argument("--duckdb-path", default="")
+    ap.add_argument("--xlsx-path", default="")
+    ap.add_argument("--port", type=int, default=DEFAULT_PORT,
+                    help="Puerto remote-debugging del Chrome aislado (default 9334).")
+    ap.add_argument("--profile-dir", default="",
+                    help="user-data-dir dedicado (vacío -> ~/.config/fn_scrape_chrome).")
+    ap.add_argument("--timeout-s", type=float, default=25.0)
+    args = ap.parse_args()
+
+    result = monitor_freelance_projects_headless(
+        category=args.category,
+        language=args.language,
+        query=args.query,
+        pages=args.pages,
+        include_upwork=args.include_upwork,
+        upwork_query=args.upwork_query,
+        duckdb_path=args.duckdb_path,
+        xlsx_path=args.xlsx_path,
+        port=args.port,
+        profile_dir=args.profile_dir,
+        timeout_s=args.timeout_s,
+    )
+    print(json.dumps(result, ensure_ascii=False))
+    return 0 if result.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())