---
name: mark_claude_parent
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def mark_claude_parent(pid: int, parent_orchestrator: str, wait_s: float = 10.0, sessions_dir: str | None = None, goals_dir: str | None = None) -> dict"
description: "Marca el orquestador padre de una sesion de Claude Code resolviendo PID -> sessionId. Sondea ~/.claude/sessions/<pid>.json (escrito por Claude Code unos segundos despues de arrancar) hasta wait_s segundos con deadline time.monotonic, extrae el sessionId y escribe SOLO la clave `parent_orchestrator` en ~/.claude/goals/<sessionId>.json preservando el resto del goal (goal, phase, dod, dod_contract, role...). Escritura atomica tmp + os.replace. Si el sessions JSON no aparece a tiempo devuelve ok=False timeout sin lanzar. Equivalente de mark_claude_role para la clave parent_orchestrator: lo invoca spawn_fleet_agent (--parent) para que el watcher de fleetview rutee los avisos del ejecutor al orquestador que lo lanzo cuando hay mas de uno activo."
tags: [fleet, claude-fleet, orchestration, parent, session, goal, orchestrator, launcher, pid]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["os", "json", "time"]
params:
  - name: pid
    desc: "PID del proceso Claude Code recien arrancado (el ejecutor). Se usa para localizar ~/.claude/sessions/<pid>.json"
  - name: parent_orchestrator
    desc: "sessionId del orquestador que lanzo el ejecutor. No puede ser vacio (lanza ValueError). Cualquier string no vacio es valido: es un sessionId arbitrario, no un enum"
  - name: wait_s
    desc: "segundos maximos a esperar (sondeo cada ~0.25s) a que aparezca sessions/<pid>.json con un sessionId no vacio. Default 10.0"
  - name: sessions_dir
    desc: "directorio de los sessions JSON. Default ~/.claude/sessions"
  - name: goals_dir
    desc: "directorio de los goal JSON. Default ~/.claude/goals (se crea si falta)"
output: "dict. En exito: ok=True, pid (int), session_id (str), parent_orchestrator (str), path (ruta del goal escrito). En timeout del poll: ok=False, error (str con 'timeout esperando sessions/<pid>.json'), pid (int). NO lanza en timeout; el launcher decide"
tested: true
tests:
  - "sessions presente resuelve y escribe parent_orchestrator preservando otros campos (incl role)"
  - "parent vacio lanza ValueError sin escribir"
  - "sessions ausente devuelve timeout sin crash"
  - "goal inexistente se crea con solo parent_orchestrator"
test_file_path: "python/functions/infra/mark_claude_parent_test.py"
file_path: "python/functions/infra/mark_claude_parent.py"
---

## Ejemplo

```python
from infra.mark_claude_parent import mark_claude_parent

# El orquestador acaba de lanzar un ejecutor (Claude Code) y conoce su PID, pero
# todavia NO su sessionId. Deja constancia de quien lo lanzo para que el watcher
# de fleetview rutee al orquestador correcto el aviso de cierre del ejecutor.
res = mark_claude_parent(executor_pid, my_session_id, wait_s=15.0)

if res["ok"]:
    print(f"padre marcado: {res['session_id']} -> {res['parent_orchestrator']}")
else:
    # Timeout: el sessions/<pid>.json no aparecio a tiempo. El launcher decide.
    print("no se pudo marcar el padre:", res["error"])
```

Invocacion canonica via `fn run` (asi lo llama `spawn_fleet_agent --parent`):

```bash
./fn run mark_claude_parent <pid_del_ejecutor> <sessionId_del_orquestador>
```

## Cuando usarla

Usala desde el launcher del orquestador de flota (`spawn_fleet_agent --parent`)
justo despues de arrancar un ejecutor, cuando conoces su PID pero todavia NO su
sessionId. Resuelve PID -> sessionId esperando el archivo que Claude Code escribe
unos segundos despues, y deja `parent_orchestrator` en el goal.json del ejecutor.
El watcher de fleetview consume esa clave para rutear el aviso de `DICE_TERMINADO`
/ estancamiento de cada ejecutor al pane tmux del orquestador que lo lanzo, en vez
de a toda la flota — necesario cuando hay mas de un orquestador activo. Es el par
de `mark_claude_role` (misma mecanica de poll, distinta clave escrita).

## Gotchas

- **Impura**: lee `~/.claude/sessions/<pid>.json` y escribe
  `~/.claude/goals/<sessionId>.json` (crea `goals_dir` si falta).
- **Timing del sessions JSON**: Claude Code NO escribe `sessions/<pid>.json` al
  instante de arrancar — tarda unos segundos. Por eso la funcion sondea hasta
  `wait_s` (deadline con `time.monotonic`, no un unico `sleep` largo) y reacciona
  en cuanto el archivo aparece con un `sessionId` no vacio.
- **Timeout NO lanza**: si el archivo no aparece a tiempo devuelve
  `{"ok": False, "error": "timeout esperando sessions/<pid>.json", "pid": pid}`.
  Solo `parent_orchestrator` vacio lanza (ValueError), y lo hace antes de tocar
  disco.
- **NO pisa otros campos del goal**: abre el goal existente (dict vacio si no
  existe o es JSON invalido / no-dict), setea UNICAMENTE la clave
  `parent_orchestrator` y conserva todo lo demas (`goal`, `phase`, `dod`,
  `dod_contract`, `role`, ...). Si el goal.json no existia, lo crea con solo
  `{"parent_orchestrator": ...}`.
- **Escritura atomica**: escribe a un archivo temporal y hace `os.replace`, asi un
  lector concurrente (la TUI / watcher fleetview) nunca ve un goal.json a medio
  escribir.
- **Orden con mark_claude_role**: cuando `spawn_fleet_agent` aplica `--role` y
  `--parent` a la vez, los encadena secuencialmente en el mismo subshell (primero
  role, luego parent) para que el segundo lea el goal ya con la primera clave
  escrita y no haya carrera de lectura-modificacion-escritura entre ambos.