agent_runner_api/app.md

name, lang, domain, version, description, tags, icon, framework, entry_point, dir_path, repo_url, uses_functions, uses_types, service, e2e_checks

name	lang	domain	version	description	tags	icon	framework	entry_point	dir_path	repo_url	uses_functions	uses_types	service	e2e_checks
agent_runner_api	go	agents	0.1.0	Service Go que orquesta agentes Claude headless en git worktrees con DoD	service agents go workflows dod	phosphor accent robot #3b82f6	stdlib-http	main.go	apps/agent_runner_api	https://gitea.organic-machine.com/dataforge/agent_runner_api			port health_endpoint health_timeout_s systemd_unit systemd_scope restart_policy runtime pc_targets is_local_only 8486 /api/health 3 agent_runner_api.service user always systemd-user aurgi-pc home-wsl true	id cmd timeout_s build CGO_ENABLED=1 go build -o agent_runner_api . 120 id cmd health smoke ./agent_runner_api --port 8486 --db /tmp/agent_runner_api_e2e.db & http://127.0.0.1:8486/api/health id cmd tests go test -count=1 ./...

Visual

Backend puro, sin UI. Consume por skill_tree v2 + kanban_cpp.

Endpoints

• GET /api/health — {status, port, db}.
• POST /api/runs — body {issue_id?, card_id?, kanban_app?, mode, prompt?} -> {run_id, branch, worktree_path, sse_url}. Crea worktree + lanza subprocess Claude (o echo STUB: si AGENT_RUNNER_STUB=1).
• GET /api/runs?status=&app=&since= — lista runs filtrada.
• GET /api/runs/:id — detalle + dod_items.
• GET /api/runs/:id/sse — stream text/event-stream (events: connected, status, evidence, validated, merged, aborted).
• POST /api/runs/:id/evidence — {item_id|item_key, kind, payload_path?, payload_url?, payload_text?}. Auto-crea dod_item si solo se da item_key.
• POST /api/runs/:id/evidence/:eid/validate — {validated_by}.
• POST /api/runs/:id/merge — TBD merge auto/<branch> a master --no-ff (gate: todos los dod_items.required = 1 deben tener evidencia validated).
• POST /api/runs/:id/abort — kill PID + git worktree remove --force + branch -D + status=aborted.

Schema (5 migrations idempotentes via embed.FS)

Tabla	Para que
workflows	Templates de prompt + dod_schema_json
runs	Run vivo: workflow/issue/card/kanban_app + branch + worktree_path + PID + status
worktrees	1 row por worktree creada, marcada removed_at al abort/merge
dod_items	Items DoD del run (`pending
dod_evidence	Evidencias adjuntas (`text

Lanzamiento

cd apps/agent_runner_api
CGO_ENABLED=1 go build -o agent_runner_api .
./agent_runner_api --port 8486 --db agent_runs.db --repo-root /home/lucas/fn_registry --worktrees-root /tmp

systemd-user: systemctl --user enable --now agent_runner_api.service (despues de copiar agent_runner_api.service a ~/.config/systemd/user/).

Gotchas

• git worktree add falla si la rama ya existe -> el Spawn() la borra antes con branch -D (best-effort).
• Worktree y main repo comparten .git/hooks/ — pre-commit del main puede bloquear commits del agente; usar --no-verify documentado.
• claude --headless requiere PATH correcto en systemd. Si claude no esta en $PATH, el subprocess cae automaticamente a echo STUB: (mismo comportamiento que AGENT_RUNNER_STUB=1).
• Subprocess corre async — el handler HTTP devuelve run_id apenas inserta + lanza, no espera al exit.
• SSE: clientes deben reconectar al cerrar conexion. Heartbeat cada 15s para mantener conexion abierta.

Capability growth log

• v0.1.0 (2026-05-18) — scaffold inicial: stdlib http, embed.FS migrations, SSE hub, spawn stub fallback, DoD gate en merge.