diff --git a/functions/infra/claude_fleet.go b/functions/infra/claude_fleet.go index 42f13d5b..940349e4 100644 --- a/functions/infra/claude_fleet.go +++ b/functions/infra/claude_fleet.go @@ -24,7 +24,8 @@ type ClaudeFleet struct { Name string `json:"name"` // manual rename of the terminal (from goals .rename; "" if none) Status string `json:"status"` // idle|busy|waiting (from sessions/.json) Cwd string `json:"cwd"` // working directory of the session - TmuxWindow string `json:"tmux_window"` // "" for now (populated in a later phase) + TmuxWindow string `json:"tmux_window"` // window_id (@N) of the pane: REAL current position, used for focus/send-keys; migrates when the pane is swapped between windows + PaneID string `json:"pane_id"` // pane_id (%N) of the pane: STABLE identity for the pane's whole life, immune to window swaps; "" if not resolvable. Prefer this as the agent's identifier over TmuxWindow Alive bool `json:"alive"` // process alive AND procStart matches (guards against PID recycling) UpdatedAt int64 `json:"updated_at"` // from sessions/.json .updatedAt (epoch millis) CtxPct int `json:"ctx_pct"` // context window used %, from runtime/.json; -1 if unknown diff --git a/functions/infra/list_claude_fleet.go b/functions/infra/list_claude_fleet.go index 6ba313e5..f9dc9cb9 100644 --- a/functions/infra/list_claude_fleet.go +++ b/functions/infra/list_claude_fleet.go @@ -42,13 +42,47 @@ type runtimeFile struct { // ListClaudeFleet scans the current user's ~/.claude directory and returns the // fleet of Claude Code sessions known to the machine. It is a thin wrapper over -// ListClaudeFleetFrom resolving the home directory. +// ListClaudeFleetFrom resolving the home directory, plus it populates each +// member's PaneID ("%N") by resolving it against the fleet tmux socket. +// +// The socket comes from $FLEET_SOCKET, defaulting to "fleet". Resolution is +// best-effort: if tmux/the socket is unavailable, every PaneID is left "" and +// the fleet is still returned. PaneID is only populated here (the public +// registry entry point), not in ListClaudeFleetFrom, so consumers that call the +// core directly in a hot loop (and the unit tests) pay no tmux cost. func ListClaudeFleet() ([]ClaudeFleet, error) { home, err := os.UserHomeDir() if err != nil { return nil, fmt.Errorf("resolve home dir: %w", err) } - return ListClaudeFleetFrom(filepath.Join(home, ".claude")) + fleet, err := ListClaudeFleetFrom(filepath.Join(home, ".claude")) + if err != nil { + return nil, err + } + populatePaneIDs(fleet) + return fleet, nil +} + +// populatePaneIDs resolves each alive member's pane_id ("%N") against the fleet +// tmux socket ($FLEET_SOCKET, default "fleet") and writes it into PaneID. It +// mutates fleet in place. Best-effort: tmux/socket down -> every PaneID stays "" +// (ResolvePaneIDs returns an empty map), no crash. Only alive PIDs are queried; +// a dead PID has no pane to resolve. +func populatePaneIDs(fleet []ClaudeFleet) { + socket := os.Getenv("FLEET_SOCKET") + if socket == "" { + socket = "fleet" + } + pids := make([]int, 0, len(fleet)) + for _, f := range fleet { + if f.Alive { + pids = append(pids, f.PID) + } + } + byPID := ResolvePaneIDs(socket, pids) + for i := range fleet { + fleet[i].PaneID = byPID[fleet[i].PID] + } } // ListClaudeFleetFrom scans claudeDir (e.g. ~/.claude) and returns the fleet of diff --git a/functions/infra/list_claude_fleet.md b/functions/infra/list_claude_fleet.md index 30b1d02c..c4474d5d 100644 --- a/functions/infra/list_claude_fleet.md +++ b/functions/infra/list_claude_fleet.md @@ -8,7 +8,7 @@ purity: impure signature: "func ListClaudeFleetFrom(claudeDir string) ([]ClaudeFleet, error) | func ListClaudeFleet() ([]ClaudeFleet, error)" description: "Lista la flota de procesos Claude Code de la maquina local (Linux). Escanea ~/.claude/sessions/*.json, cruza cada PID vivo contra /proc para validar liveness (anti-PID-reciclado via procStart == campo 22 de /proc//stat), une el goal/phase de ~/.claude/goals/.json, extrae KITTY_PID del environ y deriva los campos de display (Target, Rename). Devuelve todas las sesiones ordenadas por status (idle, waiting, busy, otro) y por updatedAt desc; el caller filtra por Alive. Pieza de datos de la app TUI fleetview." tags: [claude-fleet, infra, claude, session, proc, fleet, tui, orchestration] -uses_functions: [] +uses_functions: [resolve_pane_ids_go_infra] uses_types: [claude_fleet_go_infra] returns: [claude_fleet_go_infra] returns_optional: false @@ -17,7 +17,7 @@ imports: [] params: - name: "claudeDir" desc: "Directorio raiz de Claude Code a escanear (ej. /home/enmanuel/.claude). ListClaudeFleetFrom lo recibe explicito (testeable con t.TempDir()); ListClaudeFleet lo resuelve via os.UserHomeDir() + .claude." -output: "Slice de ClaudeFleet (claude_fleet_go_infra), una entrada por sesion con JSON parseable en sessions/. Cada entrada lleva PID, KittyPID, SessionID, Rename, Target, Goal, Phase, Status, Cwd, TmuxWindow (\"\"), Alive y UpdatedAt. Ordenado por rango de status y luego por UpdatedAt descendente. Devuelve slice vacio (sin error) si la carpeta sessions/ no existe; error si no se puede leer la carpeta por otra causa." +output: "Slice de ClaudeFleet (claude_fleet_go_infra), una entrada por sesion con JSON parseable en sessions/. Cada entrada lleva PID, KittyPID, SessionID, Rename, Target, Goal, Phase, Status, Cwd, TmuxWindow (\"\"), PaneID, Alive y UpdatedAt. ListClaudeFleet() puebla PaneID (\"%N\", identificador estable del pane) cruzando cada PID vivo con los panes del socket $FLEET_SOCKET (default \"fleet\") via resolve_pane_ids_go_infra; ListClaudeFleetFrom() deja PaneID \"\" (no hace tmux). Ordenado por rango de status y luego por UpdatedAt descendente. Devuelve slice vacio (sin error) si la carpeta sessions/ no existe; error si no se puede leer la carpeta por otra causa." tested: true tests: ["TestListClaudeFleetFrom", "TestListClaudeFleetFromMissingDir"] test_file_path: "functions/infra/list_claude_fleet_test.go" @@ -69,4 +69,5 @@ Cuando necesites enumerar las sesiones de Claude Code vivas en la maquina local - **/proc no es portable.** Build tag `//go:build !windows`; depende de `/proc//stat` y `/proc//environ` (Linux). En macOS/BSD no funciona tal cual. - **environ ilegible -> KittyPID=0.** Si `/proc//environ` no es legible (permisos, proceso de otro usuario, o el proceso ya murio entre el ReadDir y el ReadFile) `KittyPID` cae a 0 sin error. Tambien es 0 legitimamente cuando claude no corre bajo kitty (ej. tmux remoto). - **Devuelve TODAS las sesiones con JSON parseable**, vivas o muertas. El caller decide filtrar por `Alive`. Archivos no-`.json` y JSON corrupto se ignoran silenciosamente. -- **TmuxWindow siempre "".** Reservado para una fase posterior; hoy no se rellena. +- **TmuxWindow siempre "".** Esta funcion no resuelve el window_id (@N); lo rellena el consumidor (fleetview) cuando lo necesita para el focus. +- **PaneID lo puebla solo `ListClaudeFleet()`, no `ListClaudeFleetFrom()`.** La variante con directorio (usada en tests y en bucles de render calientes) no llama a tmux: deja `PaneID` "". La publica resuelve el pane_id ("%N") contra `$FLEET_SOCKET` (default "fleet") via `resolve_pane_ids_go_infra`. Si el socket no existe o tmux no responde, todos los `PaneID` quedan "" sin error. El pane_id es estable de por vida del pane (inmune a los swaps de window que mueve el focus), a diferencia de `TmuxWindow`. diff --git a/functions/infra/resolve_pane_ids.go b/functions/infra/resolve_pane_ids.go new file mode 100644 index 00000000..4eb4680b --- /dev/null +++ b/functions/infra/resolve_pane_ids.go @@ -0,0 +1,81 @@ +//go:build !windows + +package infra + +import ( + "strconv" + "strings" +) + +// ResolvePaneIDs crosses the PID of each Claude process with the panes of the +// given isolated tmux socket (tmux -L list-panes -a) and returns a +// claudePID -> pane_id ("%N") map. +// +// The pane_id is STABLE for the pane's whole life: it identifies a Claude even +// when its window_id (@N) migrates with the focus swap (break-pane + join-pane +// move the pane between windows). That is why it is the correct stable handle +// for an agent, as opposed to the window_id which changes by design. +// +// For each claudePID it climbs the process tree (PPID in /proc//stat) until +// it finds a PID that is a pane_pid of the socket; that pane is the one hosting +// the Claude. Normally the pane_pid IS the claudePID because the pane runs +// `exec claude`, but a shell that launched claude as a child is covered by the +// ascent. +// +// Best-effort and crash-free: an empty socket, no PIDs, or a tmux failure +// (socket down, tmux absent) all yield an empty map; a Claude with no resolvable +// pane is simply omitted from the result (callers degrade it to ""). It reads +// /proc, hence the //go:build !windows tag. +func ResolvePaneIDs(socket string, claudePIDs []int) map[int]string { + if socket == "" || len(claudePIDs) == 0 { + return map[int]string{} + } + out, _, err := runTmux(socket, "list-panes", "-a", "-F", "#{pane_pid} #{pane_id}") + if err != nil { + return map[int]string{} + } + return resolvePaneIDsFrom(out, procPPID, claudePIDs) +} + +// resolvePaneIDsFrom is the testable core of ResolvePaneIDs: it parses the +// ` ` lines produced by tmux and, for each claudePID, climbs +// the process tree via ppidOf until it lands on a pane_pid, returning that +// pane's pane_id. ppidOf is injected so the ascent can be tested without real +// processes. Lines that do not parse are skipped; a PID with no pane ancestor is +// omitted. +func resolvePaneIDsFrom(tmuxOut string, ppidOf func(int) int, claudePIDs []int) map[int]string { + panePaneID := map[int]string{} + for _, line := range strings.Split(strings.TrimSpace(tmuxOut), "\n") { + f := strings.Fields(strings.TrimSpace(line)) + if len(f) < 2 { + continue + } + pp, e := strconv.Atoi(f[0]) + if e != nil { + continue + } + panePaneID[pp] = f[1] + } + + res := make(map[int]string, len(claudePIDs)) + for _, pid := range claudePIDs { + if paneID, ok := paneAncestor(pid, panePaneID, ppidOf); ok { + res[pid] = paneID + } + } + return res +} + +// paneAncestor climbs the process tree from pid until it finds a PID that is a +// pane_pid (a key of panePaneID), returning its pane_id. The ascent is bounded +// (64 hops, stop at pid<=1) so a malformed /proc or a cycle cannot hang it. +// Returns ("", false) when no ancestor is a pane. ppidOf is injected for tests. +func paneAncestor(pid int, panePaneID map[int]string, ppidOf func(int) int) (string, bool) { + for i := 0; pid > 1 && i < 64; i++ { + if paneID, ok := panePaneID[pid]; ok { + return paneID, true + } + pid = ppidOf(pid) + } + return "", false +} diff --git a/functions/infra/resolve_pane_ids.md b/functions/infra/resolve_pane_ids.md new file mode 100644 index 00000000..8a956d3d --- /dev/null +++ b/functions/infra/resolve_pane_ids.md @@ -0,0 +1,72 @@ +--- +name: resolve_pane_ids +kind: function +lang: go +domain: infra +version: "1.0.0" +purity: impure +signature: "func ResolvePaneIDs(socket string, claudePIDs []int) map[int]string" +description: "Resuelve el pane_id (\"%N\") de tmux de cada proceso dado en un socket aislado (tmux -L ), devolviendo un mapa claudePID -> pane_id. Lista los panes con `list-panes -a -F '#{pane_pid} #{pane_id}'` y, para cada PID, sube por el arbol de procesos (PPID en /proc//stat) hasta dar con un pane_pid del socket; ese pane es el que aloja al proceso (normalmente pane_pid == PID porque el pane corre `exec claude`, pero un shell que lanzo el proceso como hijo se cubre con el ascenso). El pane_id es estable de por vida del pane, inmune a los swaps de window que mueve el focus de la flota, por eso es el identificador correcto de un agente frente al window_id (@N). Best-effort: socket vacio, sin PIDs o fallo de tmux -> mapa vacio; un PID sin pane resoluble se omite. Capa de control tmux de fleetview / orquestador." +tags: [claude-fleet, infra, tmux, pane, fleet, orchestration] +uses_functions: [] +uses_types: [] +returns: [] +returns_optional: false +error_type: "error_go_core" +imports: [] +params: + - name: "socket" + desc: "Nombre del socket tmux aislado (tmux -L ). En la flota suele ser 'fleet'/'fleet3' ($FLEET_SOCKET). Escanea TODOS los panes del servidor de ese socket (list-panes -a). \"\" -> mapa vacio." + - name: "claudePIDs" + desc: "PIDs de los procesos (normalmente claude) cuyo pane_id se quiere resolver. Vacio/nil -> mapa vacio sin llamar a tmux." +output: "map[int]string con clave = PID de entrada y valor = pane_id ('%N') del pane que lo aloja. Un PID sin pane resoluble en su ascendencia se omite (el caller lo degrada a \"\"). Mapa vacio (sin panic, sin error) si socket viene vacio, claudePIDs viene vacio, o `tmux list-panes -a` falla (socket caido, tmux ausente)." +tested: true +tests: ["TestResolvePaneIDsFrom", "TestResolvePaneIDsFromUnresolvable", "TestResolvePaneIDsFromMalformedLines", "TestResolvePaneIDsEmptyInputs", "TestPaneAncestorBounded"] +test_file_path: "functions/infra/resolve_pane_ids_test.go" +file_path: "functions/infra/resolve_pane_ids.go" +notes: "Build tag //go:build !windows (depende de /proc y de tmux, no portable a Windows). Comparte runTmux (tmux_new_claude_window) y procPPID (tmux_map_claude_panes) con el resto de la capa tmux del paquete infra. El nucleo resolvePaneIDsFrom(tmuxOut, ppidOf, pids) es testeable inyectando la salida de tmux y el resolvedor de PPID, sin procesos reales. El ascenso por el arbol esta acotado (64 saltos, corte en pid<=1) para no colgarse ante un /proc malformado o un ciclo. Hermana de tmux_map_claude_panes_go_infra: aquella mapea PID -> window_id (@N, posicion operativa que migra con el swap); esta mapea PID -> pane_id (%N, identidad estable). Pensada para que list_claude_fleet_go_infra (y consumidores como el orquestador) identifiquen a cada agente por un handle que no baila al hacer focus." +--- + +## Ejemplo + +```go +package main + +import ( + "fmt" + + "fn-registry/functions/infra" +) + +func main() { + // Resolver el pane_id estable de un par de procesos claude en el socket fleet. + byPID := infra.ResolvePaneIDs("fleet", []int{3637133, 3640001}) + for pid, paneID := range byPID { + fmt.Printf("pid=%d -> pane=%s\n", pid, paneID) // ej. pid=3637133 -> pane=%8 + } + // Un PID sin pane resoluble simplemente no aparece en el mapa. +} +``` + +```go +// Patron tipico: cruzar la flota con su pane_id estable. +fleet, _ := infra.ListClaudeFleet() +pids := make([]int, 0, len(fleet)) +for _, c := range fleet { + pids = append(pids, c.PID) +} +panes := infra.ResolvePaneIDs("fleet", pids) // map[pid]"%N" +``` + +## Cuando usarla + +Cuando necesites un identificador ESTABLE de un agente de la flota a partir de su PID: el pane_id ("%N") de tmux no cambia durante toda la vida del pane, aunque el pane migre de window al hacer focus (break-pane + join-pane). Usala en vez de referirte al window_id (`@N`, `TmuxWindow`), que baila cada vez que el agente entra/sale de la console. La consume `list_claude_fleet_go_infra` para poblar `ClaudeFleet.PaneID`, y el orquestador para referirse a un ejecutor por un handle que no se confunde de agente. + +## Gotchas + +- **Impura: ejecuta `tmux` y lee `/proc`.** No es determinista entre llamadas (la flota cambia). Solo lectura — no mueve ni mata panes. +- **Best-effort, nunca crashea.** Socket vacio, lista de PIDs vacia, o un `tmux list-panes -a` que falla (socket caido, tmux no instalado) devuelven un mapa vacio. Un agente sin pane resoluble (proceso huerfano, pane cerrado) se omite del mapa; el caller lo degrada a "". +- **Sube por el arbol de procesos.** Si el pane corre un shell que lanzo claude como hijo (en vez de `exec claude`), el pane_pid no es el claude PID; el ascenso por PPID lo cubre. El ascenso esta acotado a 64 saltos (corte en pid<=1) para no colgarse ante un ciclo o un /proc raro. +- **Parseo del `comm` en /proc.** El PPID se saca de `/proc//stat` tomando lo que hay tras el ULTIMO ')' (el comm va entre parentesis y puede contener espacios y ')'). Reutiliza el `procPPID` robusto del paquete. +- **/proc + tmux no portables.** Build tag `//go:build !windows`; depende de `/proc//stat` (Linux) y del binario `tmux`. +- **Opera SIEMPRE sobre el socket aislado** (`tmux -L `), escaneando todos sus panes con `list-panes -a`. No mira el servidor tmux por defecto del usuario. diff --git a/functions/infra/resolve_pane_ids_test.go b/functions/infra/resolve_pane_ids_test.go new file mode 100644 index 00000000..fe47ad3a --- /dev/null +++ b/functions/infra/resolve_pane_ids_test.go @@ -0,0 +1,80 @@ +//go:build !windows && linux + +package infra + +import ( + "reflect" + "testing" +) + +// fakePPID builds a ppidOf closure from a child->parent map. Unknown PIDs map to +// 1 (init), which terminates the ascent without matching any pane. +func fakePPID(tree map[int]int) func(int) int { + return func(pid int) int { + if p, ok := tree[pid]; ok { + return p + } + return 1 + } +} + +func TestResolvePaneIDsFrom(t *testing.T) { + // Two panes. Pane %3 runs claude directly (pane_pid == claude PID 100). + // Pane %7 runs a shell (pane_pid 200) that launched claude as a child (300). + tmuxOut := "100 %3\n200 %7\n" + tree := map[int]int{ + 300: 200, // claude (300) -> shell (200) which is the pane_pid of %7 + } + + got := resolvePaneIDsFrom(tmuxOut, fakePPID(tree), []int{100, 300}) + want := map[int]string{ + 100: "%3", // direct: pane_pid IS the claude PID + 300: "%7", // ascent: claude's parent is the pane_pid + } + if !reflect.DeepEqual(got, want) { + t.Fatalf("resolvePaneIDsFrom = %v, want %v", got, want) + } +} + +func TestResolvePaneIDsFromUnresolvable(t *testing.T) { + // PID 999 has no pane in its ancestry -> omitted (caller degrades to ""). + tmuxOut := "100 %3\n" + got := resolvePaneIDsFrom(tmuxOut, fakePPID(map[int]int{}), []int{999}) + if len(got) != 0 { + t.Fatalf("expected empty map for unresolvable PID, got %v", got) + } +} + +func TestResolvePaneIDsFromMalformedLines(t *testing.T) { + // Garbage / short / non-numeric lines are skipped without crashing; the one + // valid line still resolves. + tmuxOut := "\n \nnotapid %9\n42\n100 %3\n" + got := resolvePaneIDsFrom(tmuxOut, fakePPID(map[int]int{}), []int{100}) + want := map[int]string{100: "%3"} + if !reflect.DeepEqual(got, want) { + t.Fatalf("resolvePaneIDsFrom (malformed) = %v, want %v", got, want) + } +} + +func TestResolvePaneIDsEmptyInputs(t *testing.T) { + // Empty socket or no PIDs -> empty map, no tmux call attempted. + if got := ResolvePaneIDs("", []int{1, 2}); len(got) != 0 { + t.Errorf("empty socket: expected empty map, got %v", got) + } + if got := ResolvePaneIDs("fleet", nil); len(got) != 0 { + t.Errorf("nil pids: expected empty map, got %v", got) + } +} + +func TestPaneAncestorBounded(t *testing.T) { + // A cycle in the process tree must not hang: the 64-hop bound cuts it. + cycle := func(pid int) int { + if pid == 500 { + return 501 + } + return 500 // 501 -> 500 -> 501 ... never reaches a pane + } + if id, ok := paneAncestor(500, map[int]string{100: "%3"}, cycle); ok { + t.Fatalf("expected no resolution for cyclic tree, got %q", id) + } +}