@trycore/spec-build-harness 0.13.0 → 0.14.0

package/hooks/build/lib/runtime-client.sh

@@ -221,6 +221,28 @@ runtime_projection_path() {
   echo "$(config_root)/.claude/state/runtime-projection.json"
 }
 
+# runtime_disconnected — 0 si este agente está en modo runtime y NO puede ver el
+# estado del hub; 1 en cualquier otro caso.
+#
+# Existe para separar dos situaciones que hasta ahora colapsaban en el mismo
+# `exit 0` de los guards y que significan lo contrario:
+#
+#   auto-arme     el proyecto todavía no usa el arnés (no hay credenciales) →
+#                 no hay nada que vigilar y hay que dejar trabajar.
+#   desconectado  el proyecto SÍ está registrado (hay credenciales) pero falta la
+#                 proyección → el agente no sabe qué le manda el hub. Aquí callar
+#                 es peor que estorbar: es exactamente el estado en el que dos
+#                 workers reclaman el mismo trabajo o pisan los mismos ficheros.
+#
+# En legacy|dual devuelve 1 siempre: el fichero local es la fuente de verdad y no
+# hay hub del que desconectarse.
+runtime_disconnected() {
+  [ "$(runtime_mode)" = "runtime" ] || return 1
+  [ -f "$(runtime_credentials_path)" ] || return 1   # auto-arme legítimo
+  [ -f "$(runtime_projection_path)" ] && return 1
+  return 0
+}
+
 runtime_projection_read() {
   local file; file="$(runtime_projection_path)"
   [ -f "$file" ] || { echo "{}"; return; }
@@ -257,6 +279,76 @@ except Exception:
 PY
 }
 
+# _runtime_graph_version — versión de grafo conocida por la proyección local ("" si el hub no
+# versiona o no hay caché). Vive aquí, y no en projection.sh, porque el despacho de la outbox
+# la necesita y projection.sh depende de este fichero (invertirlo sería un ciclo de sourcing).
+_runtime_graph_version() {
+  local f; f="$(runtime_projection_path)"
+  [ -f "$f" ] || { echo ""; return; }
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  python3 - "$f" <<'PY' 2>/dev/null || echo ""
+import json,sys
+try:
+    v=(json.load(open(sys.argv[1])).get("context") or {}).get("graph_version")
+except Exception:
+    v=None
+print("" if v is None else v)
+PY
+}
+
+runtime_graph_status_path() { echo "$(config_root)/.claude/state/graph-status.json"; }
+
+# runtime_graph_note_stale <local> <servidor> — deja constancia de que el hub rechazó una
+# acción por grafo rancio [#63]. Es lo que hace VISIBLE el desfase en `status`: sin este
+# rastro, el 409 se resolvería solo y el usuario nunca sabría que ocurrió.
+# Una versión ausente (cadena vacía) se graba como `null`, NUNCA como 0: «no sé qué versión
+# tenía» y «tenía la versión cero» son cosas distintas, y la segunda mentiría en `status`.
+# [Ronda final] El fallo de escritura ya NO se traga: se avisa y se devuelve rc 1. Tragarlo
+# borraba en silencio justo el rastro que esta función existe para dejar — el desfase habría
+# ocurrido y nadie podría verlo.
+runtime_graph_note_stale() {
+  local local_v="$1" server_v="$2" f
+  f="$(runtime_graph_status_path)"
+  mkdir -p "$(dirname "$f")"
+  command -v python3 >/dev/null 2>&1 || { echo "⚠ sin python3: no se pudo anotar el desfase de grafo (local v${local_v:-?}, hub v${server_v:-?})" >&2; return 1; }
+  python3 - "$f" "$local_v" "$server_v" <<'PY' 2>/dev/null || { echo "⚠ no se pudo anotar el desfase de grafo en $f (local v${local_v:-?}, hub v${server_v:-?}): no será visible en \`status\`" >&2; return 1; }
+import json,sys,os,tempfile,datetime
+path,lv,sv=sys.argv[1],sys.argv[2],sys.argv[3]
+def num(x):
+    try: return int(x)
+    except Exception: return None
+d={"local":num(lv),"server":num(sv),
+   "seen_at":datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")}
+dirn=os.path.dirname(path) or "."
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".graph-status.",suffix=".tmp")
+try:
+    with os.fdopen(fd,"w") as out:
+        json.dump(d,out,indent=2); out.flush(); os.fsync(out.fileno())
+    os.replace(tmp,path)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+    raise
+PY
+  return 0
+}
+
+runtime_graph_status_read() {
+  local f; f="$(runtime_graph_status_path)"
+  [ -f "$f" ] || { echo "{}"; return; }
+  command -v python3 >/dev/null 2>&1 || { echo "{}"; return; }
+  python3 - "$f" <<'PY' 2>/dev/null || echo "{}"
+import json,sys
+try:
+    print(json.dumps(json.load(open(sys.argv[1]))))
+except Exception:
+    print("{}")
+PY
+}
+
+# runtime_graph_clear_stale — el desfase dejó de existir (la proyección alcanzó al servidor).
+runtime_graph_clear_stale() { rm -f "$(runtime_graph_status_path)" 2>/dev/null; return 0; }
+
 RUNTIME_OUTBOX_MAX_BYTES=5242880
 RUNTIME_OUTBOX_MAX_AGE_S=259200
 # [EP-OR-08-C] Los hechos de dominio que emiten las skills (slice-ops.sh) tampoco se evictan:
@@ -275,7 +367,10 @@ RUNTIME_OUTBOX_MAX_AGE_S=259200
 # [#52] `phase_advanced` es protegido: el orden de fases del hub es ESTRICTO — evictar un
 # eslabón de la cadena haría ilegales todos los eventos posteriores del slice (incluido el
 # slice_archived, que exige phase == pr).
-RUNTIME_OUTBOX_PROTECTED="checkpoint_recorded gate_verdict slice_escalated slice_submitted slice_archived handoff_recorded telemetry_gap wiring_checklist_seeded wiring_item_updated project_fact_updated phase_advanced checkpoint_created verdict_reported escalation_raised"
+# [#62] `epic_proposed` viaja por el CARRIL DIRECTO (su propio endpoint, no el lote de
+# /events) pero comparte cola y cota: evictar una propuesta de épica perdería trabajo humano
+# ya redactado y aprobado en la terminal, sin rastro en el hub.
+RUNTIME_OUTBOX_PROTECTED="checkpoint_recorded gate_verdict slice_escalated slice_submitted slice_archived handoff_recorded telemetry_gap wiring_checklist_seeded wiring_item_updated project_fact_updated phase_advanced checkpoint_created verdict_reported escalation_raised epic_proposed"
 
 runtime_outbox_dir() {
   echo "$(config_root)/.claude/state/outbox"
@@ -313,6 +408,167 @@ PY
   runtime_outbox_enforce_cap >/dev/null
 }
 
+# runtime_enqueue_direct <type> <method> <path> <payload_file> [stamp_graph_version] — encola
+# una petición del CARRIL DIRECTO [#62]: un hecho que NO viaja en el lote de `POST /events`
+# sino a su propio endpoint (hoy: la propuesta de épica, hub#113). Comparte con la cola de
+# eventos el directorio, el formato en disco, la cota y el sentinela de flush; lo único
+# distinto es a dónde se despacha. Imprime el `client_event_id` (referencia local mientras el
+# hub no ha asignado el suyo). El payload va por FICHERO, nunca por argv.
+# La RUTA llega ya resuelta: runtime-client.sh no conoce la tabla de endpoints — la escribe
+# quien sí la conoce (lib/runtime-ops.sh), que es el único sitio del cliente con rutas.
+# [#63] Con `1` en el 5º argumento, el fichero se marca para que el DESPACHO le estampe la
+# versión de grafo vigente. Sellarla al encolar sería un error: una propuesta que espera dos
+# días en la cola offline saldría con la versión de hace dos días y nacería condenada al 409.
+runtime_enqueue_direct() {
+  local type="$1" method="$2" path="$3" pfile="$4" stamp="${5:-0}" dir
+  dir="$(runtime_outbox_dir)"; mkdir -p "$dir"
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$dir" "$type" "$method" "$path" "$pfile" "$stamp" <<'PY' 2>/dev/null || return 1
+import json,sys,os,tempfile,uuid,datetime
+dir_,typ,method,path,pfile,stamp=sys.argv[1],sys.argv[2],sys.argv[3],sys.argv[4],sys.argv[5],sys.argv[6]
+try:
+    payload=json.load(open(pfile))
+except Exception:
+    payload={}
+cid=str(uuid.uuid4())
+ts=datetime.datetime.now(datetime.timezone.utc)
+d={"client_event_id":cid,"type":typ,"channel":"direct","method":method,"path":path,
+   "payload":payload,"enqueued_at":ts.strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
+if stamp=="1":
+    d["stamp_graph_version"]=True
+fname=os.path.join(dir_, ts.strftime("%Y%m%d%H%M%S%f")+"-"+cid+".json")
+fd,tmp=tempfile.mkstemp(dir=dir_,prefix=".outbox.",suffix=".tmp")
+try:
+    with os.fdopen(fd,"w") as out:
+        json.dump(d,out,indent=2,ensure_ascii=False); out.flush(); os.fsync(out.fileno())
+    os.replace(tmp,fname)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+    raise
+print(cid)
+PY
+  runtime_outbox_enforce_cap >/dev/null
+}
+
+# _runtime_direct_field <fichero> <clave> — escalar de primer nivel de una petición encolada
+# ("" si falta o el fichero es ilegible).
+_runtime_direct_field() {
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  python3 - "$1" "$2" <<'PY' 2>/dev/null
+import json,sys
+try:
+    v=json.load(open(sys.argv[1])).get(sys.argv[2])
+except Exception:
+    v=None
+print("" if v is None else v)
+PY
+}
+
+# _runtime_direct_payload <fichero> — imprime el cuerpo que viaja al endpoint del carril
+# directo: el payload guardado MÁS el `client_event_id` como CLAVE DE IDEMPOTENCIA ("{}" si
+# falla). [#62 · ronda final] Sin esa clave el hub no podía deduplicar el carril directo: el
+# lote de `/events` la lleva desde siempre (protocolo §5), pero aquí el `client_event_id`
+# vivía solo como clave de primer nivel del FICHERO y no salía en la petición. Con dos
+# despachadores posibles (el daemon y el proceso de la skill), un doble envío de la misma
+# propuesta creaba DOS propuestas y, al aprobarlas, dos `EP-XXX` — la colisión que motiva #62,
+# reintroducida por el otro extremo. Se estampa al armar el cuerpo, no al encolar: el formato
+# en disco no cambia y los ficheros ya encolados drenan sin migración.
+_runtime_direct_payload() {
+  command -v python3 >/dev/null 2>&1 || { echo "{}"; return; }
+  python3 - "$1" <<'PY' 2>/dev/null || echo "{}"
+import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+    p=d.get("payload")
+    if p is None:
+        p={}
+    if isinstance(p,dict):
+        cid=d.get("client_event_id")
+        # Un `client_event_id` ya presente en el payload manda: lo puso quien encoló y
+        # sobrescribirlo cambiaría la identidad de la petición a espaldas del productor.
+        if cid and "client_event_id" not in p:
+            p["client_event_id"]=cid
+    print(json.dumps(p,ensure_ascii=False))
+except Exception:
+    print("{}")
+PY
+}
+
+# _runtime_reject_file <fichero> <razón> — aparta una petición a rejected/ con su razón
+# PERSISTIDA (la muestran `slice-ops.sh status` y `trycore-build status/doctor`: el stderr de
+# un daemon no lo lee nadie). Nunca lanza.
+_runtime_reject_file() {
+  local f="$1" reason="$2" rdir
+  rdir="$(runtime_outbox_dir)/rejected"
+  mkdir -p "$rdir"
+  echo "⚠ $reason" >&2
+  command -v python3 >/dev/null 2>&1 || { mv "$f" "$rdir/" 2>/dev/null; return 0; }
+  # [#62] Escritura ATÓMICA del apartado: `tempfile.mkstemp` en el mismo directorio destino
+  # + `os.replace` (restricción dura de la spec). Un `json.dump` directo a `dest` deja un
+  # fichero truncado legible a medio escribir si el proceso muere entre el open y el flush —
+  # inaceptable para algo que `slice-ops.sh status`/`trycore-build doctor` leen en caliente.
+  python3 - "$f" "$rdir" "$reason" <<'PY' 2>/dev/null || mv "$f" "$rdir/" 2>/dev/null
+import json,sys,os,tempfile
+f,rdir,reason=sys.argv[1],sys.argv[2],sys.argv[3]
+try:
+    d=json.load(open(f))
+except Exception:
+    d=None
+dest=os.path.join(rdir,os.path.basename(f))
+if isinstance(d,dict):
+    d["rejected_reason"]=reason
+    fd,tmp=tempfile.mkstemp(dir=rdir,prefix=".rejected.",suffix=".tmp")
+    try:
+        with os.fdopen(fd,"w") as out:
+            json.dump(d,out,indent=2,ensure_ascii=False); out.flush(); os.fsync(out.fileno())
+        os.replace(tmp,dest)
+        os.unlink(f)
+    except Exception:
+        try: os.unlink(tmp)
+        except OSError: pass
+        raise
+else:
+    os.replace(f,dest)
+PY
+  return 0
+}
+
+# _runtime_ack_direct <fichero> <respuesta-cruda> — deja el acuse en acks/<client_event_id>.json.
+# El ledger de dominio (qué propuesta es, en qué estado está) NO vive aquí: runtime-client.sh
+# es agnóstico al dominio. Quien correlaciona es lib/runtime-ops.sh.
+_runtime_ack_direct() {
+  local f="$1" resp="$2" adir
+  adir="$(runtime_outbox_dir)/acks"
+  mkdir -p "$adir"
+  command -v python3 >/dev/null 2>&1 || return 0
+  python3 - "$f" "$adir" "$resp" <<'PY' 2>/dev/null
+import json,sys,os,tempfile,datetime
+f,adir,resp=sys.argv[1],sys.argv[2],sys.argv[3]
+try:
+    d=json.load(open(f))
+except Exception:
+    d={}
+try:
+    body=json.loads(resp)
+except Exception:
+    body={}
+cid=d.get("client_event_id") or "sin-id"
+out={"client_event_id":cid,"type":d.get("type"),"status":"acked","response":body,
+     "acked_at":datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")}
+path=os.path.join(adir,cid+".json")
+fd,tmp=tempfile.mkstemp(dir=adir,prefix=".ack.",suffix=".tmp")
+try:
+    with os.fdopen(fd,"w") as fh:
+        json.dump(out,fh,indent=2,ensure_ascii=False); fh.flush(); os.fsync(fh.fileno())
+    os.replace(tmp,path)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+PY
+  return 0
+}
+
 # runtime_outbox_enforce_cap — cota 5MB/72h. Descarta primero los eventos NO protegidos
 # (más viejos primero); jamás descarta un tipo de RUNTIME_OUTBOX_PROTECTED. Si hubo
 # descartes, encola un telemetry_gap con el payload EXACTO del catálogo v2 [#44]
@@ -421,10 +677,245 @@ PY
 
 RUNTIME_OUTBOX_BACKOFF_SCHEDULE="1 5 30 300"
 
-# runtime_dispatch_outbox — despacho best-effort de la cola. No-op en modo legacy.
+# _runtime_partition_outbox <fichero…> — imprime "direct <ruta>", "batch <ruta>" o
+# "bad <ruta>" por línea. Una sola invocación de python3 para todos los ficheros: el despacho
+# corre en el hilo del daemon cada pocos segundos y no puede pagar un proceso por fichero.
+# [#62 · ronda final] La tercera clase existe porque un fichero ILEGIBLE (JSON corrupto, o un
+# JSON que no es un objeto) no se puede afirmar que sea del lote: clasificarlo como `batch`
+# lo condenaba a saltarse en silencio al armar el cuerpo y a quedarse atascado PARA SIEMPRE
+# —una pérdida muda sobre un tipo que además está protegido de la evicción por cota—. El
+# llamador lo aparta a rejected/ nombrando la causa.
+_runtime_partition_outbox() {
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$@" <<'PY' 2>/dev/null
+import json,sys
+for p in sys.argv[1:]:
+    try:
+        d=json.load(open(p))
+    except Exception:
+        d=None
+    if not isinstance(d,dict):
+        print("bad "+p)
+        continue
+    print(("direct " if d.get("channel")=="direct" else "batch ")+p)
+PY
+}
+
+# _runtime_bump_field <fichero> <clave> <valor-entero> — persiste un contador dentro de la
+# petición encolada (escritura atómica, con `fsync` — mismo patrón que el resto del fichero).
+# Sin esto, el conteo de 409 viviría en memoria y se perdería entre ciclos del daemon: el
+# reintento sería infinito por construcción. [Ronda de arreglo 1, Important 2] El fallo YA NO
+# se traga: se propaga (rc distinguible) para que el llamador aparte el fichero en vez de
+# reintentar para siempre sin poder nunca completar el conteo.
+_runtime_bump_field() {
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$1" "$2" "$3" <<'PY' 2>/dev/null
+import json,sys,os,tempfile
+path,key,val=sys.argv[1],sys.argv[2],sys.argv[3]
+try:
+    d=json.load(open(path))
+except Exception:
+    raise SystemExit(1)   # fichero ilegible: rc distinguible, el llamador decide (no reintento ciego)
+d[key]=int(val)
+dirn=os.path.dirname(path) or "."
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".outbox.",suffix=".tmp")
+try:
+    with os.fdopen(fd,"w") as out:
+        json.dump(d,out,indent=2,ensure_ascii=False); out.flush(); os.fsync(out.fileno())
+    os.replace(tmp,path)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+    raise
+PY
+}
+
+# _runtime_mark_graph_409 <fichero> <n> <version-local> — persiste el conteo de rechazos por
+# grafo rancio Y la versión local con la que se produjeron. Los dos campos van juntos porque la
+# racha es «tres rechazos contra la MISMA versión local», no «tres rechazos a secas» (ver
+# _runtime_dispatch_direct). Escritura atómica con fsync y fallo propagado (rc distinguible),
+# igual que _runtime_bump_field: si el conteo no se puede persistir, el llamador aparta el
+# fichero en vez de reintentar sin fin.
+_runtime_mark_graph_409() {
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$1" "$2" "$3" <<'PY' 2>/dev/null
+import json,sys,os,tempfile
+path,n,gv=sys.argv[1],sys.argv[2],sys.argv[3]
+try:
+    d=json.load(open(path))
+except Exception:
+    raise SystemExit(1)   # fichero ilegible: rc distinguible, el llamador decide
+d["graph_409"]=int(n)
+# Ausencia de versión = None, nunca 0: «salió sin estampar» y «salió con la versión 0» son
+# cosas distintas, y confundirlas haría que la racha se reiniciara sola sin motivo.
+d["graph_409_at_version"]=gv if gv else None
+dirn=os.path.dirname(path) or "."
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".outbox.",suffix=".tmp")
+try:
+    with os.fdopen(fd,"w") as out:
+        json.dump(d,out,indent=2,ensure_ascii=False); out.flush(); os.fsync(out.fileno())
+    os.replace(tmp,path)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+    raise
+PY
+}
+
+# _runtime_dispatch_direct <fichero…> — despacha el carril directo UNO a uno (cada petición
+# tiene su endpoint; no hay lote que armar). Contrato de resultado por fichero:
+#   2xx                    → ack en acks/, se borra el fichero y se limpia el desfase de grafo
+#                            si había uno anotado (la petición llegó, luego ya no vamos rancios).
+#   404                    → el hub NO implementa esa ruta (instancia sin soporte, hub#113
+#                            pendiente): se aparta diciéndolo con esas palabras.
+#   409 reason=stale_graph → grafo rancio [#63]: se anota el desfase y se CONSERVA (no es un
+#                            rechazo de contrato); a los 3 seguidos se aparta. Cualquier OTRO
+#                            409 (propuesta duplicada, conflicto de estado…) sigue el camino
+#                            normal de rechazo de contrato — el `reason` es lo único que decide.
+#   4xx (salvo 404/408/409-stale_graph/429) → rechazo de contrato: se aparta a rejected/.
+#   000 · 5xx · 408 · 429  → transitorio: se CONSERVA y se reintenta en el próximo ciclo.
+# rc 1 si algo quedó pendiente por causa transitoria, 0 si no queda nada del carril.
+# No agenda backoff propio a propósito: el carril directo es de volumen bajísimo (una
+# propuesta de épica) y compartir el backoff del lote dejaría los hechos de dominio del slice
+# esperando detrás de una propuesta. El ritmo real de reintento lo marca el ciclo del daemon.
+_runtime_dispatch_direct() {
+  local f rc=0 resp status type path method payload gv server_gv n409 prev_gv stamped reason
+  for f in "$@"; do
+    [ -f "$f" ] || continue
+    # [Ronda final] `gv` se reinicia POR ITERACIÓN: es `local` a la función y solo se asigna
+    # dentro del `if stamp_graph_version`, así que un fichero sin estampar que recibiera un 409
+    # heredaba la versión del fichero anterior y la usaba en el mensaje, en el marcador de
+    # desfase y en la racha — un dato inventado con apariencia de medida.
+    gv=""
+    type="$(_runtime_direct_field "$f" type)"
+    method="$(_runtime_direct_field "$f" method)"
+    path="$(_runtime_direct_field "$f" path)"
+    [ -n "$method" ] || method=POST
+    if [ -z "$path" ]; then
+      _runtime_reject_file "$f" "petición directa sin ruta de despacho (fichero corrupto): no se envió"
+      continue
+    fi
+    payload="$(_runtime_direct_payload "$f")"
+    # [#63] Estampado AL DESPACHAR, con la versión que la proyección tenga en ESTE instante.
+    if [ "$(_runtime_direct_field "$f" stamp_graph_version)" = "True" ]; then
+      gv="$(_runtime_graph_version)"
+      if [ -n "$gv" ]; then
+        # [Ronda de arreglo 1, Important 1] Si `$gv` no es un entero válido (hub#115 aún no
+        # existe: nada coacciona el tipo en `agent-context.sh`), `int()` lanza y python no
+        # imprime nada — NUNCA se sobrescribe `payload` con esa cadena vacía, o la petición
+        # saldría sin cuerpo y el 4xx del hub se reportaría como "rechazo del hub" en vez de
+        # como el fallo de estampado que de verdad es.
+        stamped="$(printf '%s' "$payload" | python3 -c 'import json,sys; d=json.load(sys.stdin); d["graph_version"]=int(sys.argv[1]); print(json.dumps(d,ensure_ascii=False))' "$gv" 2>/dev/null)"
+        [ -n "$stamped" ] && payload="$stamped"
+      fi
+    fi
+    resp="$(_runtime_http "$method" "$path" "$payload")"
+    status="$(runtime_http_status)"
+    case "$status" in
+      200|201|202)
+        _runtime_ack_direct "$f" "$resp"
+        rm -f "$f"
+        runtime_graph_clear_stale ;;
+      404)
+        # [bash 3.2] un carácter multibyte pegado a `$var` sin llaves («$type») rompe el
+        # escaneo del nombre bajo `set -u` en esta bash — `${type}` lo aísla.
+        _runtime_reject_file "$f" "el hub no expone $path (HTTP 404): esta instancia está sin soporte para «${type}» — actualiza el hub y vuelve a proponer" ;;
+      409)
+        # [Ronda de arreglo 1, Important 4] El `reason` decide, igual que en `_claim_once`:
+        # un 409 por OTRA causa (propuesta duplicada, conflicto de estado…) no es un grafo
+        # rancio y tratarlo como tal apartaría la propuesta con un diagnóstico falso.
+        reason="$(printf '%s' "$resp" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("reason") or "")' 2>/dev/null)"
+        if [ "$reason" = "stale_graph" ]; then
+          # No es un error de contrato: el grafo del hub cambió. Se anota el desfase (lo
+          # muestra `status`) y la petición se CONSERVA — el refresco del heartbeat (#61)
+          # traerá la versión nueva y el próximo ciclo la re-estampa. Con 3 rechazos seguidos
+          # se deja de insistir: a esas alturas no es una carrera, y un bucle silencioso es
+          # peor que un rechazo visible.
+          server_gv="$(printf '%s' "$resp" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("graph_version") or "")' 2>/dev/null)"
+          runtime_graph_note_stale "$gv" "$server_gv"
+          n409="$(_runtime_direct_field "$f" graph_409)"
+          case "$n409" in ''|*[!0-9]*) n409=0 ;; esac
+          # [Ronda final] La racha cuenta rechazos contra la MISMA versión local estampada. Las
+          # dos cadencias son independientes y nada las acopla: el despacho corre en cada tick
+          # que encuentre `outbox/.flush-request` —y `session-stop.sh` lo deja en CADA turno—,
+          # mientras el refresco de contexto va a `runtime.context_refresh_s` (45 s por defecto,
+          # y `0` lo DESACTIVA, valor soportado). Contando rechazos a secas, tres turnos en
+          # menos de 45 s gastaban las tres vidas de la propuesta contra la misma foto del
+          # grafo y la apartaban pidiendo un refresco que el cliente nunca se permitió hacer.
+          # Si la versión local cambió, hubo refresco de verdad: la racha empieza de cero.
+          prev_gv="$(_runtime_direct_field "$f" graph_409_at_version)"
+          [ "$prev_gv" = "$gv" ] || n409=0
+          n409=$((n409 + 1))
+          if [ "$n409" -ge 3 ]; then
+            _runtime_reject_file "$f" "el hub rechazó «${type}» tres veces por el MISMO grafo obsoleto (local v${gv:-?}, hub v${server_gv:-?}): refresca el proyecto y vuelve a proponer"
+          elif _runtime_mark_graph_409 "$f" "$n409" "$gv"; then
+            rc=1
+          else
+            # [Ronda de arreglo 1, Important 2] El conteo no se pudo persistir: reintentar a
+            # ciegas sería un bucle infinito (el contador jamás llegaría a 3). Se aparta.
+            _runtime_reject_file "$f" "no se pudo persistir el conteo de rechazos por grafo obsoleto de «${type}»: se aparta para evitar un reintento sin fin"
+          fi
+        else
+          _runtime_reject_file "$f" "el hub rechazó «${type}» (HTTP $status): $resp — no se reintentará"
+        fi ;;
+      408|429|5*|000)
+        # [Ronda de arreglo 1, Minor 6] «3 rechazos CONSECUTIVOS» debe ser literal: un
+        # transitorio intercalado (timeout, 5xx…) no es un stale_graph y no debe sumar a esa
+        # racha — se reinicia el contador si había uno. Best-effort: si la escritura falla,
+        # el `rc=1` de abajo igual reintenta el próximo ciclo (no hay riesgo de bucle, ya que
+        # solo la rama `409 stale_graph` puede volver a incrementarlo).
+        n409="$(_runtime_direct_field "$f" graph_409)"
+        case "$n409" in ''|*[!0-9]*) n409=0 ;; esac
+        [ "$n409" -gt 0 ] && _runtime_bump_field "$f" graph_409 0
+        rc=1 ;;
+      4*)
+        _runtime_reject_file "$f" "el hub rechazó «${type}» (HTTP $status): $resp — no se reintentará" ;;
+      *)
+        rc=1 ;;
+    esac
+  done
+  return $rc
+}
+
+RUNTIME_DISPATCH_LOCK_MAX_AGE_MIN=2
+
+runtime_dispatch_lock_path() { echo "$(config_root)/.claude/state/.outbox-dispatch.lock"; }
+
+# runtime_dispatch_outbox — envoltura con MUTEX de `_runtime_dispatch_outbox_once`.
+#
+# [#62 · ronda final] Hasta esta rama el único despachador era el daemon (proceso único) y no
+# hacía falta serializar nada. `slice-ops.sh propose-epic` despacha ahora en PRIMER PLANO, así
+# que el proceso de la skill y el daemon pueden recorrer la MISMA cola a la vez. Para el lote
+# no sería grave (su seguridad viene de la idempotencia server-side por `client_event_id`),
+# pero `runtime_http_status` es un FICHERO compartido: entre el `_runtime_http` de un proceso y
+# su lectura del status puede colarse el curl del otro, y un `409` leído como `2xx` borraría la
+# petición dándola por entregada sin que el hub la haya visto jamás.
+#
+# `mkdir` es atómico (mismo patrón que `hb_spawnlock` en heartbeat.sh); un lock huérfano
+# —proceso muerto entre el mkdir y el rmdir— se libera por edad. El umbral (2 min) queda muy
+# por encima de un ciclo real: el lote es una petición y el carril directo es de volumen
+# bajísimo, ambos con `curl -m 10`.
+runtime_dispatch_outbox() {
+  local lock rc
+  [ "$(runtime_mode)" = "legacy" ] && return 0
+  lock="$(runtime_dispatch_lock_path)"
+  mkdir -p "$(dirname "$lock")"
+  if [ -d "$lock" ] && [ -n "$(find "$lock" -maxdepth 0 -mmin "+$RUNTIME_DISPATCH_LOCK_MAX_AGE_MIN" 2>/dev/null)" ]; then
+    rmdir "$lock" 2>/dev/null
+  fi
+  # Otro proceso está despachando ESTA cola: no se toca nada y se reporta que quedó trabajo
+  # (rc 1). Devolver 0 sería afirmar que la cola quedó drenada sin haberlo comprobado.
+  mkdir "$lock" 2>/dev/null || return 1
+  _runtime_dispatch_outbox_once
+  rc=$?
+  rmdir "$lock" 2>/dev/null
+  return $rc
+}
+
+# _runtime_dispatch_outbox_once — despacho best-effort de la cola. No-op en modo legacy.
 # Respeta un backoff persistido (nunca bloquea reintentando en el hilo del hook). FIFO
 # global (el agrupado por-agregado nace con el catálogo de eventos del sub-slice C).
-runtime_dispatch_outbox() {
+_runtime_dispatch_outbox_once() {
   local mode; mode="$(runtime_mode)"
   [ "$mode" = "legacy" ] && return 0
 
@@ -442,9 +933,42 @@ runtime_dispatch_outbox() {
   fi
   [ "$now" -lt "$next_ok" ] && return 0
 
-  local files=()
-  while IFS= read -r f; do files+=("$f"); done < <(find "$dir" -maxdepth 1 -name '*.json' ! -name '.dispatch-state.json' | sort)
-  [ ${#files[@]} -eq 0 ] && return 0
+  # [#62] Dos carriles, un solo punto de despacho: los ficheros con `channel: "direct"` van a
+  # su propio endpoint; el resto arma el lote de POST /events como siempre.
+  local all=() files=() direct=() bad=() f line direct_rc=0 part prc
+  while IFS= read -r f; do all+=("$f"); done < <(find "$dir" -maxdepth 1 -name '*.json' ! -name '.dispatch-state.json' | sort)
+  [ ${#all[@]} -eq 0 ] && return 0
+  # [Ronda final] El rc de la partición se COMPRUEBA. Si falla (E2BIG con una cola muy grande,
+  # python3 caído a mitad), `direct` y `files` quedaban vacíos, se borraba el backoff agendado
+  # y la función devolvía 0 con la cola llena: un fallo reportado como drenaje limpio. Ahora se
+  # dice, no se toca el estado de backoff y se reintenta en el próximo ciclo.
+  part="$(_runtime_partition_outbox "${all[@]}")"
+  prc=$?
+  if [ "$prc" -ne 0 ]; then
+    echo "⚠ no se pudo clasificar la cola de la outbox (${#all[@]} fichero(s)): no se despacha en este ciclo, se reintentará" >&2
+    return 1
+  fi
+  while IFS= read -r line; do
+    case "$line" in
+      "direct "*) direct+=("${line#direct }") ;;
+      "batch "*)  files+=("${line#batch }") ;;
+      "bad "*)    bad+=("${line#bad }") ;;
+    esac
+  done <<EOF
+$part
+EOF
+  if [ ${#bad[@]} -gt 0 ]; then
+    for f in "${bad[@]}"; do
+      _runtime_reject_file "$f" "fichero de la outbox ilegible (no es un objeto JSON): no se puede saber por qué carril iba ni qué contiene — se aparta en vez de dejarlo atascado en la cola para siempre"
+    done
+  fi
+  if [ ${#direct[@]} -gt 0 ]; then
+    _runtime_dispatch_direct "${direct[@]}" || direct_rc=1
+  fi
+  if [ ${#files[@]} -eq 0 ]; then
+    [ "$direct_rc" -eq 0 ] && rm -f "$state_file"
+    return "$direct_rc"
+  fi
 
   # [#37] El hub (`EventBatchIn`) exige el sobre {"events": [...]} — el array pelado era
   # 422 en cada intento y la cola no drenaba jamás. Cada elemento va con `event_type`
@@ -544,9 +1068,13 @@ PY
   # Si todo lo pendiente eran tipos sin equivalente (ya apartados), no hay nada que enviar.
   local n_items
   n_items="$(printf '%s' "$batch" | python3 -c 'import json,sys;print(len(json.load(sys.stdin).get("events") or []))' 2>/dev/null || echo 0)"
+  # [#62] El lote no tenía nada que enviar, pero el carril directo puede seguir con algo
+  # pendiente por causa transitoria: el rc de la función tiene que reflejarlo (no solo el
+  # rc del lote), porque quien lo consume (p. ej. slice-ops.sh) decide en base a ÉL si
+  # queda trabajo por drenar.
   if [ "$n_items" = "0" ]; then
     rm -f "$state_file"
-    return 0
+    return "$direct_rc"
   fi
 
   local resp status
@@ -603,8 +1131,11 @@ for p in paths:
         except OSError:
             pass
 PY
+    # [#62] Igual que arriba: el lote se resolvió (200), pero el rc global tiene que
+    # reflejar también el carril directo si algo suyo quedó pendiente por causa
+    # transitoria en este mismo ciclo.
     rm -f "$state_file"
-    return 0
+    return "$direct_rc"
   fi
 
   # [#37] Un 4xx del LOTE (salvo 408/429) es un rechazo del contrato, no red caída:
@@ -614,7 +1145,7 @@ PY
   case "$status" in
     408|429) : ;;
     4*)
-      local rejected_dir f
+      local rejected_dir
       rejected_dir="$dir/rejected"
       mkdir -p "$rejected_dir"
       echo "⛔ el hub rechazó el lote de eventos (HTTP $status): $resp" >&2