fn_registry/bash/functions/infra/kill_fleet_agent.md

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

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	error_type	file_path	tested	tests	test_file_path	params	output
kill_fleet_agent	function	bash	infra	1.1.0	impure	kill_fleet_agent <sessionId|PID> [--socket <s>] [--dry-run]	Cierre limpio y dirigido de UN ejecutor de la flota tmux. Dado un sessionId (exacto o prefijo) o un PID, manda SIGTERM al proceso claude del ejecutor (cierre limpio, recuperable con claude --resume) y cierra su window tmux en el socket del perfil FleetView. Lo usa el orquestador para liberar el slot idle de cada ejecutor en cuanto verifica que su DoD-contrato esta met. Tres guards de seguridad: NUNCA mata a un agente con role=orchestrator (leido de su goal.json); NUNCA a la sesion que invoca la funcion (resuelve su propio PID de claude por los ancestros de /proc); y NUNCA cierra la window que aloja la TUI fleetview o la window 'console' con kill-window (eso se llevaria el panel de control por delante) — en ese caso cierra SOLO el pane del target con kill-pane y preserva la TUI. Por defecto EJECUTA; --dry-run imprime el plan (incluida la accion kill-pane vs kill-window) sin tocar nada. Es el cierre dirigido a UN agente, frente a reboot_all_claudes que opera sobre toda la flota.	fleet claude-fleet orchestration tmux kill infra			error_go_core	bash/functions/infra/kill_fleet_agent.sh	true	golden: ejecutor por sessionId, PID y prefijo se resuelve y dry-run imprime el plan guard: matar un role=orchestrator devuelve rc=3 y se niega guard: matar la sesion actual (self) devuelve rc=3 y se niega guard3: predicado _fleet_window_hosts_tui detecta window 'console' o pane fleetview error: target no resuelto rc=2; sin target rc=2	bash/functions/infra/kill_fleet_agent_test.sh	name desc target Primer arg posicional: sessionId del ejecutor (exacto o prefijo) o su PID (todo digitos). Por PID se lee sessions/<pid>.json para el sessionId; por sessionId se busca en sessions/*.json el que case y su archivo da el PID. name desc --socket Socket tmux del perfil FleetView donde vive la window. Default: $FLEET_SOCKET, o 'fleet' si no esta seteada. name desc --dry-run Imprime el plan (PID, sessionId, role, window, accion) y NO mata el proceso ni cierra la window. Sin esto, ejecuta.	Imprime una linea de plan con PID, sessionId, role, socket y window resueltos, seguida de la accion ejecutada (SIGTERM + kill-window) o, con --dry-run, de DRY-RUN. Exit 0 ok/dry-run; 2 uso incorrecto o target no resuelto a PID; 3 guard (target es un orchestrator o la sesion actual).

kill_fleet_agent

Cierra de forma dirigida UN ejecutor de la flota tmux: SIGTERM al proceso claude (cierre limpio, recuperable con claude --resume <sessionId>) más kill-window de su window en el socket del perfil FleetView. Es la pieza que el orquestador usa para liberar el slot idle de cada ejecutor en cuanto verifica que su DoD-contrato está met — sin esto, los ejecutores terminados se acumulan en reposo en la flota.

Ejemplo

# Cerrar un ejecutor por sessionId (el orquestador lo llama tras verificar `met`):
./fn run kill_fleet_agent 32945650-a4e1-472b-90c9-5b38ef60a463 --socket "$FLEET_SOCKET"

# Por prefijo de sessionId, en el socket por defecto ($FLEET_SOCKET o "fleet"):
./fn run kill_fleet_agent 32945650

# Ver el plan sin matar nada (PID, sessionId, role, window, accion):
./fn run kill_fleet_agent 48213 --dry-run

Cuando usarla

Úsala desde el modo orquestador justo después de que el verificador independiente devuelva met sobre un ejecutor: ciérralo para que no quede ocupando un slot idle en la flota. Resuelve el target por sessionId (exacto o prefijo) o por PID, comprueba los guards y manda SIGTERM + cierra la window. Es el cierre dirigido a un agente; para reiniciar/parar toda la flota usa reboot_all_claudes (con --exclude-current). Nunca uses pkill/killall claude (te matas a ti mismo, el orquestador).

Gotchas

• Impura y destructiva: manda SIGTERM y cierra una window tmux. Por defecto EJECUTA (es el caso de uso del bot: cerrar un ejecutor ya verificado met); usa --dry-run para inspeccionar antes.
• Guard anti-orquestador: si el goal.json del target tiene role=orchestrator, rehúsa con exit 3. Evita decapitar la flota por error. El role se lee de ~/.claude/goals/<sessionId>.json (lo escribe mark_claude_role).
• Guard anti-self: resuelve el PID de claude de la sesión actual subiendo por los ancestros de /proc; si el target coincide, rehúsa con exit 3 ("No me suicido"). Es el equivalente dirigido de la regla "nunca pkill claude".
• Guard 3 — anti-TUI/console (no decapitar el panel): antes de cerrar nada, comprueba si la window del target aloja la TUI fleetview (algún pane corre el binario fleetview) o se llama console. El layout FleetView mete la TUI y un Claude en la misma window console, y los focus-swaps (join-pane) pueden meter al ejecutor target en esa window; un kill-window ahí se llevaría la TUI por delante (causa del fallo descrito en fleetview v0.4.3). En ese caso la función NO usa kill-window: manda el SIGTERM al claude y cierra solo su pane con kill-pane, preservando el pane de la TUI. El plan (y el --dry-run) lo refleja como accion: kill-pane … (aloja la TUI/console) vs accion: kill-window …. El predicado es la función interna _fleet_window_hosts_tui (testeada). Se mantiene inline (no función propia del registry) por estar acoplada a este flujo y para no dejar una capacidad huérfana (KISS).
• Resolución de la window y el pane: usa tmux -L <socket> list-panes -a y casa pane_pid == PID, capturando window_id, pane_id y window_name. Funciona porque spawn_fleet_agent arranca el ejecutor con exec claude, así el pane_pid ES el PID de claude. Si no hay socket/tmux, la window queda "(no resuelta)" y solo se manda el SIGTERM (best-effort, no falla).
• SIGTERM, no SIGKILL: cierre limpio para que Claude Code persista su sesión; el trabajo se puede retomar con claude --resume <sessionId>.
• Requiere jq para leer los JSON de sessions/goals.
• Overrides de entorno solo para tests: FN_FLEET_SESSIONS_DIR, FN_FLEET_GOALS_DIR y FN_FLEET_SELF_PID redirigen los directorios y fuerzan el PID propio; no usarlos en operación normal.

Capability growth log

• v1.1.0 (2026-06-24) — Guard 3 anti-TUI/console (elimina un gotcha conocido). Antes, si un focus-swap metía al ejecutor target en la window console (la que aloja la TUI fleetview), kill-window cerraba la TUI por error. Ahora, cuando la window del target aloja la TUI (pane fleetview) o se llama console, se cierra solo el pane del target con kill-pane y la TUI sobrevive; el resto de windows siguen cerrándose con kill-window. Predicado interno _fleet_window_hosts_tui con tests. Es la causa raíz que complementa el auto-respawn de la TUI (supervise_fleetview_tui).
• v1.0.0 — versión inicial.