fn_registry/bash/functions/infra/spawn_fleet_agent.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, error_type, file_path, tested, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	error_type	file_path	tested	params	output
spawn_fleet_agent	function	bash	infra	1.2.0	impure	spawn_fleet_agent [--socket <s>] [--session <s>] [--cwd <dir>] [--prompt-file <f> | --skill <name>] [--role orchestrator|executor] [--parent <sid>] [--title <t>]	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.	fleet claude-fleet orchestration tmux infra	mark_claude_role_py_infra mark_claude_parent_py_infra detect_fleet_context_bash_infra		error_go_core	bash/functions/infra/spawn_fleet_agent.sh	false	name desc --socket 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 desc --session Nombre de la sesion tmux dentro del socket (normalmente igual al socket). Opcional: se auto-detecta de $TMUX si no se pasa. name desc --cwd Directorio de trabajo del nuevo Claude. Default: PWD. name desc --prompt-file Ruta a un archivo cuyo contenido sera el primer prompt del Claude (prompt autocontenido del ejecutor). El cat lo hace el shell del pane, admite multi-linea. name desc --skill Nombre de un skill a invocar como primer prompt (ej. orquestador -> envia '/orquestador'). Tiene prioridad sobre --prompt-file. name desc --role Role a escribir en el goal.json del nuevo Claude: orchestrator | executor. Se aplica via mark_claude_role en background. Sin esto, executor implicito. name desc --parent sessionId del orquestador que lanza este ejecutor. Si se pasa, escribe parent_orchestrator en el goal.json del nuevo Claude (via mark_claude_parent en background) para que el watcher de fleetview rutee sus avisos al orquestador padre. Opcional; sin esto el aviso no se atribuye a un orquestador concreto. name desc --title Nombre de la window tmux creada. Default: claude.	Imprime por stdout el window_id (ej. @7) de la window tmux creada. Exit 0 ok; 1 error de entorno (tmux ausente, sesion inexistente, prompt-file inexistente); 2 uso incorrecto.

spawn_fleet_agent

Lanza un Claude dentro de un perfil FleetView (sesion tmux de un socket aislado) como una window nueva, para que forme parte de la flota visible en la TUI fleetview y conmutable con /fleet focus. Es la pieza que hace que los ejecutores —y el orquestador— vivan en la flota tmux en vez de en kitties dispersas (flow 0012, Fase 3).

Ejemplo

# Meter el ORQUESTADOR en la flota actual (arranca en modo + se pinea arriba):
./fn run spawn_fleet_agent --socket fleet2 --session fleet2 --cwd "$HOME/fn_registry" \
  --skill orquestador --role orchestrator --title orquestador

# Lanzar un EJECUTOR con tarea autocontenida en la misma flota:
./fn run spawn_fleet_agent --socket fleet2 --session fleet2 --cwd "$HOME/fn_registry" \
  --prompt-file /tmp/orq_health.md --title "kanban-health"

# Ejecutor atribuido a SU orquestador padre (habilita el routing del watcher):
./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

Cuando el orquestador (o el launcher) necesita arrancar un Claude que debe vivir EN la flota tmux: un ejecutor con tarea, o el propio orquestador. Usala en lugar de launch_claude_agent_kitty_bash_infra siempre que ya exista un perfil fleet montado y quieras ver/conmutar el agente desde fleetview y /fleet. Tras lanzar un ejecutor, escribe su DoD-contrato con set_dod_contract.

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.